GwySIUnit

GwySIUnit — SI unit representation, physical quantitiy formatting

Synopsis




struct      GwySIValueFormat;
struct      GwySIUnit;
struct      GwySIUnitClass;
GObject*    gwy_si_unit_new                 (const gchar *unit_string);
void        gwy_si_unit_set_unit_string     (GwySIUnit *siunit,
                                             gchar *unit_string);
gchar*      gwy_si_unit_get_unit_string     (GwySIUnit *siunit);
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);

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

struct GwySIValueFormat

struct GwySIValueFormat {

    gdouble magnitude;
    gint precision;
    gchar *units;
};

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.

struct GwySIUnit

struct GwySIUnit;

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


struct GwySIUnitClass

struct GwySIUnitClass {

    GObjectClass parent_class;

    gpointer *reserved1;
    gpointer *reserved2;
};


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

void        gwy_si_unit_set_unit_string     (GwySIUnit *siunit,
                                             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_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 unit (with no prefixes).

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.