![]() |
![]() |
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); 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 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. |
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. |