![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
|
---|---|---|---|---|
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_from_string (GwySIUnit *siunit, const gchar *unit_string); void gwy_si_unit_set_from_string_parse (GwySIUnit *siunit, const gchar *unit_string, gint *power10); gchar* gwy_si_unit_get_string (GwySIUnit *siunit, GwySIUnitFormatStyle style); 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); GwySIUnit* gwy_si_unit_power_multiply (GwySIUnit *siunit1, gint power1, GwySIUnit *siunit2, gint power2, 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); void gwy_si_unit_value_format_set_units (GwySIValueFormat *format, const gchar *units);
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.
The magnitude
and precision
fields can be directly modified if necessary.
Units must be always set with gwy_si_unit_value_format_set_units()
to update
the internal representation properly.
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); void (*reserved1)(void); void (*reserved2)(void); } 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);
Creates a new SI unit from string representation.
Unit string represents unit with no prefixes (e. g. "m", "N", "A", etc.)
unit_string : |
Unit string (it can be NULL for an empty unit).
|
Returns : | A new SI unit. |
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.
void gwy_si_unit_set_from_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 set siunit from (it can be NULL for an empty
unit).
|
void gwy_si_unit_set_from_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_from_string()
, please
see gwy_si_unit_new_parse()
for some discussion.
gchar* gwy_si_unit_get_string (GwySIUnit *siunit, GwySIUnitFormatStyle style);
Obtains string representing a SI unit.
siunit : |
An SI unit. |
style : |
Unit format style. |
Returns : | A newly allocated string that represents the 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 raise 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.
|
GwySIUnit* gwy_si_unit_power_multiply (GwySIUnit *siunit1, gint power1, GwySIUnit *siunit2, gint power2, GwySIUnit *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 chanied when more than two units are to be multiplied.
siunit1 : |
An SI unit. |
power1 : |
Power to raise siunit1 to.
|
siunit2 : |
An SI unit. |
power2 : |
Power to raise siunit2 to.
|
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.
|
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
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. |
void gwy_si_unit_value_format_set_units (GwySIValueFormat *format, const gchar *units);
Sets the units field of a value format structure.
This function keeps the units
and units_gstring
fields consistent.
format : |
A value format to set units of. |
units : |
The units string. |