GwySIUnit

GwySIUnit — SI unit representation, physical quantitiy formatting

Synopsis




            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);

Object Hierarchy


  GObject
   +----GwySIUnit

Implemented Interfaces

GwySIUnit implements GwySerializable.

Signals


"value-changed"
            void        user_function      (GwySIUnit *gwysiunit,
                                            gpointer   user_data)      : Run first

Description

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().

Details

GwySIValueFormat

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.

GwySIUnit

typedef struct _GwySIUnit GwySIUnit;

The GwySIUnit struct contains private data only and should be accessed using the functions below.


GwySIUnitClass

typedef struct {
    GObjectClass parent_class;

    void (*value_changed)(GwySIUnit *siunit);

    void (*reserved1)(void);
    void (*reserved2)(void);
} GwySIUnitClass;


gwy_si_unit_duplicate()

#define     gwy_si_unit_duplicate(siunit)

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

siunit : An SI unit to duplicate.

gwy_si_unit_new ()

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.

gwy_si_unit_new_parse ()

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 (it can be NULL for an empty unit).
power10 : Where power of 10 should be stored (or NULL).
Returns : A new SI unit.

gwy_si_unit_set_from_string ()

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).

gwy_si_unit_set_from_string_parse ()

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.

siunit : An SI unit.
unit_string : Unit string to set siunit from (it can be NULL for an empty unit).
power10 : Where power of 10 should be stored (or NULL).

gwy_si_unit_get_string ()

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).

gwy_si_unit_multiply ()

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.

gwy_si_unit_divide ()

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.

gwy_si_unit_power ()

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.

gwy_si_unit_equal ()

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.

gwy_si_unit_get_format ()

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.

gwy_si_unit_get_format_for_power10 ()

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.

gwy_si_unit_get_format_with_resolution ()

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.

gwy_si_unit_get_format_with_digits ()

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.

gwy_si_unit_value_format_free ()

void        gwy_si_unit_value_format_free   (GwySIValueFormat *format);

Frees a value format structure.

format : A value format to free.

gwy_si_unit_value_format_set_units ()

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.

Signal Details

The "value-changed" signal

void        user_function                  (GwySIUnit *gwysiunit,
                                            gpointer   user_data)      : Run first

The ::value-changed signal is emitted whenever SI unit changes.

gwysiunit : The GwySIUnit which received the signal.
user_data : user data set when the signal handler was connected.