gwy.SIUnit

Module gwy :: Class SIUnit

[show private | hide private]

Class SIUnit

The SIUnit struct contains private data only and should be accessed using the functions below.

Method Summary
	`divide(siunit2, result)` Divides two SI units.
	`equal(siunit2)` Checks whether two SI units are equal.
	`get_string(style)` Obtains string representing a SI unit.
	`multiply(siunit2, result)` Multiplies two SI units.
	`nth_root(ipower, result)` Calulates n-th root of an SI unit.
	`power(power, result)` Computes a power of an SI unit.
	`power_multiply(power1, siunit2, power2, result)` Computes the product of two SI units raised to arbitrary powers.
	`set_from_string(unit_string)` Sets string that represents unit.
	`set_from_string_parse(unit_string, power10)` Changes an SI unit according to string representation.
	`UNIMPLEMENTED_get_format(style, value, format)` Finds a good format for representing a value.
	`UNIMPLEMENTED_get_format_for_power10(style, power10, format)` Finds format for representing a specific power-of-10 multiple of a unit.
	`UNIMPLEMENTED_get_format_with_digits(style, maximum, sdigits, format)` Finds a good format for representing a values with given number of significant digits.
	`UNIMPLEMENTED_get_format_with_resolution(style, maximum, resolution, format)` Finds a good format for representing a range of values with given resolution.

Method Details

divide(siunit2, result)

Divides two SI units.

Parameters:: siunit2 - An SI unit. (SIUnit); result - An SI unit to set to quotient of siunit1 and siunit2. It is safe to pass one of siunit1, siunit2. It can be NULL too, a new SI unit is created then and returned. (SIUnit)

Returns:: When result is NULL, a newly created SI unit that has to be dereferenced when no longer used later. Otherwise result itself is simply returned, its reference count is NOT increased.

equal(siunit2)

Checks whether two SI units are equal.

Parameters:: siunit2 - Second unit. (SIUnit)

Returns:: True if units are equal.

get_string(style)

Obtains string representing a SI unit.

Parameters:: style - Unit format style.Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, (SIUnitFormatStyle)

Returns:: A newly allocated string that represents the base unit (with no prefixes).

multiply(siunit2, result)

Multiplies two SI units.

Parameters:: siunit2 - An SI unit. (SIUnit); result - An SI unit to set to product of siunit1 and siunit2. It is safe to pass one of siunit1, siunit2. It can be NULL too, a new SI unit is created then and returned. (SIUnit)

Returns:: When result is NULL, a newly created SI unit that has to be dereferenced when no longer used later. Otherwise result itself is simply returned, its reference count is NOT increased.

nth_root(ipower, result)

Calulates n-th root of an SI unit.

This operation fails if the result would have fractional powers that are not representable by SIUnit.

Parameters:: ipower - The root to take: 2 means a quadratic root, 3 means cubic root, etc. (int); result - An SI unit to set to power of siunit. It is safe to pass siunit itself. It can be NULL too, a new SI unit is created then and returned. (SIUnit)

Returns:: On success: When result is NULL, a newly created SI unit that has to be dereferenced when no longer used later, otherwise result itself is simply returned, its reference count is NOT increased. On failure NULL is always returned.
Since: 2.5

power(power, result)

Computes a power of an SI unit.

Parameters:: power - Power to raise siunit to. (int); result - An SI unit to set to power of siunit. It is safe to pass siunit itself. It can be NULL too, a new SI unit is created then and returned. (SIUnit)

Returns:: When result is NULL, a newly created SI unit that has to be dereferenced when no longer used later. Otherwise result itself is simply returned, its reference count is NOT increased.

power_multiply(power1, siunit2, power2, result)

Computes the product of two SI units raised to arbitrary powers.

This is the most complex SI unit arithmetic function. It can be easily chained when more than two units are to be multiplied.

Parameters:: power1 - Power to raise siunit1 to. (int); siunit2 - An SI unit. (SIUnit); power2 - Power to raise siunit2 to. (int); result - An SI unit to set to siunit1^power1*siunit2^power2. It is safe to pass siunit1 or siunit2. It can be NULL too, a new SI unit is created then and returned. (SIUnit)

Returns:: When result is NULL, a newly created SI unit that has to be dereferenced when no longer used later. Otherwise result itself is simply returned, its reference count is NOT increased.
Since: 2.4

set_from_string(unit_string)

Sets string that represents unit.

It must be base unit with no prefixes (e. g. "m", "N", "A", etc.).

Parameters:: unit_string - Unit string to set siunit from (it can be NULL for an empty unit). (string)

set_from_string_parse(unit_string, power10)

Changes an SI unit according to string representation.

This is a more powerful version of SiUnit.set_from_string(), please see SiUnit.new_parse() for some discussion.

Parameters:: unit_string - Unit string to set siunit from (it can be NULL for an empty unit). (string); power10 - Where power of 10 should be stored (or NULL). (int)

UNIMPLEMENTED_get_format(style, value, format)

Finds a good format for representing a value.

The values should be then printed as value/format->magnitude [format->units] with format->precision decimal places.

Parameters:: style - Unit format style.Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, (SIUnitFormatStyle); value - Value the format should be suitable for. (float); format - A value format to set-up, may be NULL, a new value format is allocated then. (SIValueFormat*)

Returns:: The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

UNIMPLEMENTED_get_format_for_power10(style, power10, format)

Finds format for representing a specific power-of-10 multiple of a unit.

The values should be then printed as value/format->magnitude [format->units] with format->precision decimal places.

This function does not change the precision field of format.

Parameters:: style - Unit format style.Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, (SIUnitFormatStyle); power10 - Power of 10, in the same sense as SiUnit.new_parse() returns it. (int); format - A value format to set-up, may be NULL, a new value format is allocated then. (SIValueFormat*)

Returns:: The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

UNIMPLEMENTED_get_format_with_digits(style, maximum, sdigits, format)

Finds a good format for representing a values with given number of significant digits.

The values should be then printed as value/format->magnitude [format->units] with format->precision decimal places.

Parameters:: style - Unit format style.Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, (SIUnitFormatStyle); maximum - The maximum value to be represented. (float); sdigits - The number of significant digits the value should have. (int); format - A value format to set-up, may be NULL, a new value format is allocated then. (SIValueFormat*)

Returns:: The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

UNIMPLEMENTED_get_format_with_resolution(style, maximum, resolution, format)

Finds a good format for representing a range of values with given resolution.

The values should be then printed as value/format->magnitude [format->units] with format->precision decimal places.

Parameters:: style - Unit format style.Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, (SIUnitFormatStyle); maximum - The maximum value to be represented. (float); resolution - The smallest step (approximately) that should make a visible difference in the representation. (float); format - A value format to set-up, may be NULL, a new value format is allocated then. (SIValueFormat*)

Returns:: The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

Generated by Epydoc 2.1 on Tue Dec 30 04:01:42 2008

http://epydoc.sf.net