GwySIUnit

GwySIUnit — SI unit representation, physical quantitiy formatting

Synopsis




            GwySIValueFormat;
            GwySIUnit;
            GwySIUnitClass;
#define     gwy_si_unit_duplicate           (siunit)
GObject*    gwy_si_unit_new                 (const gchar *unit_string);
GObject*    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);
GwySIValueFormat* gwy_si_unit_get_format    (GwySIUnit *siunit,
                                             gdouble value,
                                             GwySIValueFormat *format);
GwySIValueFormat* gwy_si_unit_get_format_with_resolution
                                            (GwySIUnit *siunit,
                                             gdouble maximum,
                                             gdouble resolution,
                                             GwySIValueFormat *format);
GwySIValueFormat* gwy_si_unit_get_format_with_digits
                                            (GwySIUnit *siunit,
                                             gdouble maximum,
                                             gint sdigits,
                                             GwySIValueFormat *format);
void        gwy_si_unit_value_format_free   (GwySIValueFormat *format);
gboolean    gwy_si_unit_equal               (GwySIUnit *siunit1,
                                             GwySIUnit *siunit2);

Object Hierarchy


  GObject
   +----GwySIUnit

Implemented Interfaces

GwySIUnit implements GwySerializable.

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;
} GwySIValueFormat;

A physical quantity formatting information.

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.

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;

    gpointer *reserved1;
    gpointer *reserved2;
} GwySIUnitClass;


gwy_si_unit_duplicate()

#define gwy_si_unit_duplicate(siunit) ((GwySIUnit*)gwy_serializable_duplicate(G_OBJECT(siunit)))

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

siunit : An SI unit to duplicate.

Since 1.8


gwy_si_unit_new ()

GObject*    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 GwySiUnit with a given string.

gwy_si_unit_new_parse ()

GObject*    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-9 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.

Since 1.8


gwy_si_unit_set_unit_string ()

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.

gwy_si_unit_set_unit_string_parse ()

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

Since 1.8


gwy_si_unit_get_unit_string ()

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

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 can be one of siunit1, siunit2.
Returns : result, for convenience.

Since 1.8


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 can be one of siunit1, siunit2.
Returns : result, for convenience.

Since 1.8


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 can be siunit itself.
Returns : result, for convenience.

Since 1.8


gwy_si_unit_get_format ()

GwySIValueFormat* gwy_si_unit_get_format    (GwySIUnit *siunit,
                                             gdouble value,
                                             GwySIValueFormat *format);

Finds reasonable representation for a number. This means that number value should be written as value / format->magnitude [format->units].

siunit : GwySiUnit
value : input value
format : returned number representation parameters
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,
                                             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.
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,
                                             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.
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_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.

Since 1.9