Trees       Indices       Help   
Module gwy :: Class SIUnit
[hide private]
[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 [hide private]
 
__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
 
duplicate()
Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.		 source code
Method Details [hide private]

__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 commensurability checks 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)

   Trees       Indices       Help   
Generated by Epydoc 3.0.1 http://epydoc.sourceforge.net