[frames] | no frames]

# Class SIUnit

source code

SI unit representation, physical quantitiy formatting

`SIUnit` object represents a physical SI unit (or any other unit), it can be created from a unit string with `SIUnit.new`().

SIUnit is also responsible for prefixes selection and generally formatting of physical quantities (see also gwymath for pure number formatting functions). There are several functions computing value format (as a `SIValueFormat` structure) with given resolution -- SIUnit.get_format_with_resolution(), or number of significant digits -- SIUnit.get_format_with_digits().

 Instance Methods

 __init__(unit_string) Creates a new SI unit from string representation. source code

 set_from_string(unit_string) Sets string that represents unit. source code

 set_from_string_parse(unit_string) Changes an SI unit according to string representation. source code

 get_string(style) Obtains string representing a SI unit. source code

 multiply(siunit2, result) Multiplies two SI units. source code

 divide(siunit2, result) Divides two SI units. source code

 power(power, result) Computes a power of an SI unit. source code

 nth_root(ipower, result) Calulates n-th root of an SI unit. source code

 power_multiply(power1, siunit2, power2, result) Computes the product of two SI units raised to arbitrary powers. source code

 equal(siunit2) Checks whether two SI units are equal. source code

 equal_string(unit_string) Checks whether an SI unit corresponds to given string. source code

 get_format(style, value, format) Finds a good format for representing a value. source code

 get_format_for_power10(style, power10, format) Finds format for representing a specific power-of-10 multiple of a unit. source code

 get_format_with_resolution(style, maximum, resolution, format) Finds a good format for representing a range of values with given resolution. source code

 get_format_with_digits(style, maximum, sdigits, format) Finds a good format for representing a values with given number of significant digits. source code

 Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting. source code
 Method Details

### __init__(unit_string)(Constructor)

source code

Creates a new SI unit from string representation.

Unit string represents unit with no prefixes (e. g. "m", "N", "A", etc.)

Parameters:
• `unit_string` - Unit string (it can be `None` for an empty unit). (string)
Returns:
A new SI unit. (SIUnit)

### set_from_string(unit_string)

source code

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 `None` for an empty unit). (string)

### set_from_string_parse(unit_string)

source code

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 `None` for an empty unit). (string)
Returns:
Value `power10`. ((int))

### get_string(style)

source code

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`, `SI_UNIT_FORMAT_VFTEX`, `SI_UNIT_FORMAT_UNICODE`, `SI_UNIT_FORMAT_VFUNICODE`. (SIUnitFormatStyle)
Returns:
A newly allocated string that represents the base unit (with no prefixes). (string)

### multiply(siunit2, result)

source code

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 `None` too, a new SI unit is created then and returned. (SIUnit)
Returns:
When `result` is `None`, 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. (SIUnit)

### divide(siunit2, result)

source code

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 `None` too, a new SI unit is created then and returned. (SIUnit)
Returns:
When `result` is `None`, 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. (SIUnit)

### power(power, result)

source code

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 `None` too, a new SI unit is created then and returned. (SIUnit)
Returns:
When `result` is `None`, 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. (SIUnit)

### nth_root(ipower, result)

source code

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 `None` too, a new SI unit is created then and returned. (SIUnit)
Returns:
On success: When `result` is `None`, 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 `None` is always returned. (SIUnit)

Since: 2.5

### power_multiply(power1, siunit2, power2, result)

source code

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 `None` too, a new SI unit is created then and returned. (SIUnit)
Returns:
When `result` is `None`, 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. (SIUnit)

Since: 2.4

### equal(siunit2)

source code

Checks whether two SI units are equal.

Parameters:
• `siunit2` - Second unit. (SIUnit)
Returns:
`True` if the units are equal. (bool)

### equal_string(unit_string)

source code

Checks whether an SI unit corresponds to given string.

Any power-of-ten prefixes are ignored. This function is mostly useful for quick comparison with simple units such as "m" and for checking whether a unit is non-empty (by comparing with `None` or an empty string).

Parameters:
• `unit_string` - Unit string (it can be `None` for an empty unit). (string)
Returns:
`True` if the units is equivalent to the given string. (bool)

Since: 2.49

### get_format(style, value, format)

source code

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`, `SI_UNIT_FORMAT_VFTEX`, `SI_UNIT_FORMAT_UNICODE`, `SI_UNIT_FORMAT_VFUNICODE`. (SIUnitFormatStyle)
• `value` - Value the format should be suitable for. (float)
• `format` - A value format to set-up, may be `None`, a new value format is allocated then. (SIValueFormat)
Returns:
The value format. If `format` was `None`, a newly allocated format is returned, otherwise (modified) `format` itself is returned. (SIValueFormat)

### get_format_for_power10(style, power10, format)

source code

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`, `SI_UNIT_FORMAT_VFTEX`, `SI_UNIT_FORMAT_UNICODE`, `SI_UNIT_FORMAT_VFUNICODE`. (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 `None`, a new value format is allocated then. (SIValueFormat)
Returns:
The value format. If `format` was `None`, a newly allocated format is returned, otherwise (modified) `format` itself is returned. (SIValueFormat)

### get_format_with_resolution(style, maximum, resolution, format)

source code

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`, `SI_UNIT_FORMAT_VFTEX`, `SI_UNIT_FORMAT_UNICODE`, `SI_UNIT_FORMAT_VFUNICODE`. (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 `None`, a new value format is allocated then. (SIValueFormat)
Returns:
The value format. If `format` was `None`, a newly allocated format is returned, otherwise (modified) `format` itself is returned. (SIValueFormat)

### get_format_with_digits(style, maximum, sdigits, format)

source code

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`, `SI_UNIT_FORMAT_VFTEX`, `SI_UNIT_FORMAT_UNICODE`, `SI_UNIT_FORMAT_VFUNICODE`. (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 `None`, a new value format is allocated then. (SIValueFormat)
Returns:
The value format. If `format` was `None`, a newly allocated format is returned, otherwise (modified) `format` itself is returned. (SIValueFormat)

### duplicate()

source code

Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.

Returns:
(SIUnit)

 Generated by Epydoc 3.0.1 http://epydoc.sourceforge.net