![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
---|
GwySIUnitGwySIUnit — SI unit representation, physical quantitiy formatting |
GwySIValueFormat; GwySIUnit; GwySIUnitClass; #define gwy_si_unit_duplicate (siunit) GwySIUnit* gwy_si_unit_new (const gchar *unit_string); GwySIUnit* gwy_si_unit_new_parse (const gchar *unit_string, gint *power10); void gwy_si_unit_set_unit_string (GwySIUnit *siunit, const gchar *unit_string); void gwy_si_unit_set_unit_string_parse (GwySIUnit *siunit, const gchar *unit_string, gint *power10); gchar* gwy_si_unit_get_unit_string (GwySIUnit *siunit); GwySIUnit* gwy_si_unit_multiply (GwySIUnit *siunit1, GwySIUnit *siunit2, GwySIUnit *result); GwySIUnit* gwy_si_unit_divide (GwySIUnit *siunit1, GwySIUnit *siunit2, GwySIUnit *result); GwySIUnit* gwy_si_unit_power (GwySIUnit *siunit, gint power, GwySIUnit *result); gboolean gwy_si_unit_equal (GwySIUnit *siunit1, GwySIUnit *siunit2); GwySIValueFormat* gwy_si_unit_get_format (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble value, GwySIValueFormat *format); GwySIValueFormat* gwy_si_unit_get_format_for_power10 (GwySIUnit *siunit, GwySIUnitFormatStyle style, gint power10, GwySIValueFormat *format); GwySIValueFormat* gwy_si_unit_get_format_with_resolution (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble maximum, gdouble resolution, GwySIValueFormat *format); GwySIValueFormat* gwy_si_unit_get_format_with_digits (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble maximum, gint sdigits, GwySIValueFormat *format); void gwy_si_unit_value_format_free (GwySIValueFormat *format);
GwySIUnit object represents a physical SI unit (or any other unit), it can be created from a unit string with gwy_si_unit_new().
GwySIUnit 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 GwySIValueFormat structure) with given resolution -- gwy_si_unit_get_format_with_resolution(), or number of significant digits -- gwy_si_unit_get_format_with_digits().
typedef struct { gdouble magnitude; gint precision; gchar *units; GString *units_gstring; } GwySIValueFormat;
A physical quantity formatting information.
You should not generally modify the units part manually, if you do, modify units_gstring and update units to units_gstring->str.
gdouble magnitude; | Number to divide a quantity by (a power of 1000). |
gint precision; | Number of decimal places to format a quantity to. |
gchar *units; | Units to put after quantity divided by magnitude. This is actually an alias to units_gstring->str. |
GString *units_gstring; | GString used to represent units internally. |
typedef struct _GwySIUnit GwySIUnit;
The GwySIUnit struct contains private data only and should be accessed using the functions below.
typedef struct { GObjectClass parent_class; void (*value_changed)(GwySIUnit *siunit); gpointer *reserved1; gpointer *reserved2; } GwySIUnitClass;
#define gwy_si_unit_duplicate(siunit)
Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.
siunit : | An SI unit to duplicate. |
GwySIUnit* gwy_si_unit_new (const gchar *unit_string);
Unit string represents unit with no prefixes (e. g. "m", "N", "A", etc.)
unit_string : | Unit string. |
Returns : | A new SI unit with a given string. |
GwySIUnit* gwy_si_unit_new_parse (const gchar *unit_string, gint *power10);
Creates a new SI unit from string representation.
This is a more powerful version of gwy_si_unit_new(): unit_string may be a relatively complex unit, with prefixes, like "pA/s" or "km^2". Beside conversion to a base SI unit like "A/s" or "m^2" it also computes the power of 10 one has to multiply the base unit with to get an equivalent of unit_string.
For example, for "pA/s" it will store -12 to power10 because 1 pA/s is 1e-12 A/s, for "km^2" it will store 6 to power10 because 1 km^2 is 1e6 m^2.
unit_string : | Unit string. |
power10 : | Where power of 10 should be stored (or NULL). |
Returns : | A new SI unit. |
void gwy_si_unit_set_unit_string (GwySIUnit *siunit, const gchar *unit_string);
Sets string that represents unit.
It must be base unit with no prefixes (e. g. "m", "N", "A", etc.).
siunit : | An SI unit. |
unit_string : | Unit string to be set. |
void gwy_si_unit_set_unit_string_parse (GwySIUnit *siunit, const gchar *unit_string, gint *power10);
Changes an SI unit according to string representation.
This is a more powerful version of gwy_si_unit_set_unit_string(), please see gwy_si_unit_new_parse() for some discussion.
siunit : | An SI unit. |
unit_string : | Unit string to be set. |
power10 : | Where power of 10 should be stored (or NULL). |
gchar* gwy_si_unit_get_unit_string (GwySIUnit *siunit);
Obtains string representing a SI unit.
siunit : | An SI unit. |
Returns : | String that represents base unit (with no prefixes). |
GwySIUnit* gwy_si_unit_multiply (GwySIUnit *siunit1, GwySIUnit *siunit2, GwySIUnit *result);
Multiplies two SI units.
siunit1 : | An SI unit. |
siunit2 : | An SI unit. |
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. |
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. |
GwySIUnit* gwy_si_unit_divide (GwySIUnit *siunit1, GwySIUnit *siunit2, GwySIUnit *result);
Divides two SI units.
siunit1 : | An SI unit. |
siunit2 : | An SI unit. |
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. |
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. |
GwySIUnit* gwy_si_unit_power (GwySIUnit *siunit, gint power, GwySIUnit *result);
Computes a power of an SI unit.
siunit : | An SI unit. |
power : | Power to power siunit to. |
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. |
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. |
gboolean gwy_si_unit_equal (GwySIUnit *siunit1, GwySIUnit *siunit2);
Checks whether two SI units are equal.
siunit1 : | First unit. |
siunit2 : | Second unit. |
Returns : | TRUE if units are equal. |
GwySIValueFormat* gwy_si_unit_get_format (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble value, GwySIValueFormat *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.
siunit : | An SI unit. |
style : | Unit format style. |
value : | Value the format should be suitable for. |
format : | A value format to set-up, may be NULL, a new value format is allocated then. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
GwySIValueFormat* gwy_si_unit_get_format_for_power10 (GwySIUnit *siunit, GwySIUnitFormatStyle style, gint power10, GwySIValueFormat *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.
siunit : | An SI unit. |
style : | Unit format style. |
power10 : | Power of 10, in the same sense as gwy_si_unit_new_parse() returns it. |
format : | A value format to set-up, may be NULL, a new value format is allocated then. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
GwySIValueFormat* gwy_si_unit_get_format_with_resolution (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble maximum, gdouble resolution, GwySIValueFormat *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.
siunit : | A SI unit. |
style : | Unit format style. |
maximum : | The maximum value to be represented. |
resolution : | The smallest step (approximately) that should make a visible difference in the representation. |
format : | A value format to set-up, may be NULL, a new value format is allocated then. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
GwySIValueFormat* gwy_si_unit_get_format_with_digits (GwySIUnit *siunit, GwySIUnitFormatStyle style, gdouble maximum, gint sdigits, GwySIValueFormat *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.
siunit : | A SI unit. |
style : | Unit format style. |
maximum : | The maximum value to be represented. |
sdigits : | The number of significant digits the value should have. |
format : | A value format to set-up, may be NULL, a new value format is allocated then. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
void gwy_si_unit_value_format_free (GwySIValueFormat *format);
Frees a value format structure.
format : | A value format to free. |
<< gwyexpr | gwyutils >> |