## GwySIUnit

GwySIUnit — SI unit representation, physical quantitiy formatting

## Synopsis

    #include <libgwyddion/gwyddion.h>

                        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_nth_root                (GwySIUnit *siunit,
                                                             gint ipower,
                                                             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);

## Object Hierarchy

      GObject
       +----GwySIUnit

## Implemented Interfaces

GwySIUnit implements GwySerializable.

## Signals

      "value-changed"                                  : 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 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.

### gwy_si_unit_nth_root ()

    GwySIUnit*          gwy_si_unit_nth_root                (GwySIUnit *siunit,
                                                             gint ipower,
                                                             GwySIUnit *result);

Calulates n-th root of an SI unit.

This operation fails if the result would have fractional powers that are not representable by GwySIUnit.

`siunit` : | An SI unit.
`ipower` : | The root to take: 2 means a quadratic root, 3 means cubic root, etc.
`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 : | On success: 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. On failure `NULL` is always returned.

Since 2.5

### gwy_si_unit_power_multiply ()

    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 chained 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

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