GwyUnit: Gwyddion Library Reference Manual

## GwyUnit GwyUnit — unit representation, physical quantitiy formatting |

## Functions

#define | GWY_FREE_VALUE_FORMAT()
GwyUnit * | gwy_unit_new ()
GwyUnit * | gwy_unit_new_parse ()
void | gwy_unit_clear ()
gint | gwy_unit_set_from_string ()
gchar * | gwy_unit_get_string ()
GwyUnit * | gwy_unit_multiply ()
GwyUnit * | gwy_unit_divide ()
GwyUnit * | gwy_unit_power ()
gboolean | gwy_unit_nth_root ()
GwyUnit * | gwy_unit_power_multiply ()
GwyUnit * | gwy_unit_factor_to_base ()
gboolean | gwy_unit_equal ()
gboolean | gwy_unit_equal_string ()
GwyValueFormat * | gwy_unit_get_format ()
GwyValueFormat * | gwy_unit_get_format_for_power10 ()
GwyValueFormat * | gwy_unit_get_format_with_resolution ()
GwyValueFormat * | gwy_unit_get_format_with_digits ()
GwyUnit * | gwy_unit_copy ()
void | gwy_unit_assign ()

## Signals

void | value-changed | Run First

## Types and Values

enum | GwyUnitFormatStyle
struct | GwyUnit
struct | GwyUnitClass

## Object Hierarchy

        GObject
        ╰── GwyUnit

## Implemented Interfaces

GwyUnit implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyUnit object represents a physical unit, it can be created from a unit string with `gwy_unit_new()`.

GwyUnit 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 GwyValueFormat structure) with given resolution -- `gwy_unit_get_format_with_resolution()`, or number of significant digits -- `gwy_unit_get_format_with_digits()`.

Functions for unit arithmetic return the input (reuslt) object for convenience in C. It enables chaining operations and creating new units as the result of the unit arithmetic:

    1
    product_unit = gwy_unit_multiply(gwy_unit_new(NULL), unit1, unit2);

However, language bindings do not see that the input and output objects are always the same object, and such construction may not behave correctly (things should balance out for simple reference counting, but it may not be what a particular language does).

## Functions

### GWY_FREE_VALUE_FORMAT()

    #define             GWY_FREE_VALUE_FORMAT(vf)

Frees and nulls a pointer to a GwyValueFormat if it exists.

The value format must have been created using a `gwy_unit_get_format()`, `gwy_field_get_value_format_z()` or a similar function.

If `vf` is not `NULL`, `gwy_value_format_free()` is called on it, freeing also string data, and `NULL` is assigned to the variable. In all cases `vf` will be `NULL` at the end.

A useful property of this macro is its idempotence.

#### Parameters

vf | A GwyValueFormat pointer to free or `NULL`. |

### gwy_unit_new()

    GwyUnit *
    gwy_unit_new (const gchar *unit_string);

Creates a new unit from string representation.

Unit string represents unit with no prefixes (e. g. "m", "N", "A", etc.)

[constructor]

#### Parameters

unit_string | Unit string (it can be `NULL` for an empty unit). | [nullable]

#### Returns

A new unit.

[transfer full]

### gwy_unit_new_parse()

    GwyUnit *
    gwy_unit_new_parse (const gchar *unit_string,
                        gint *power10);

Creates a new unit from string representation.

This is a more powerful version of `gwy_unit_new()`: `unit_string` may be a relatively complex unit, with prefixes, like "pA/s" or "km^2". Beside conversion to a base 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.

#### Parameters

unit_string | Unit string (it can be `NULL` for an empty unit). | [nullable]
power10 | Where power of 10 should be stored (or `NULL`). | [out][optional]

#### Returns

A new unit.

[transfer full]

### gwy_unit_clear()

    void
    gwy_unit_clear (GwyUnit *unit);

Sets a unit to empty.

#### Parameters

unit | A unit. |

### gwy_unit_set_from_string()

    gint
    gwy_unit_set_from_string (GwyUnit *unit,
                              const gchar *unit_string);

Changes an unit according to string representation.

See `gwy_unit_new_parse()` for a discussion of the returned power of 10.

The string can be `NULL` to make the unit empty, but you can just use `gwy_unit_clear()` then.

#### Parameters

unit | A unit. |
unit_string | Unit string to set `unit` from. | [nullable]

#### Returns

The power of 10 corresponding to `unit_string` .

### gwy_unit_get_string()

    gchar *
    gwy_unit_get_string (GwyUnit *unit,
                         GwyUnitFormatStyle style);

Obtains string representing a unit.

#### Parameters

unit | A unit. |
style | Unit format style. |

#### Returns

A newly allocated string that represents the base unit (with no prefixes).

### gwy_unit_multiply()

    GwyUnit *
    gwy_unit_multiply (GwyUnit *unit,
                       GwyUnit *operand1,
                       GwyUnit *operand2);

Sets a unit to the product of two other units.

It is possible to pass either of `operand1` and `operand2` (or even both) as `unit` .

#### Parameters

unit | A unit to set to the product of `operand1` and `operand2` . |
operand1 | A unit to multiply. | [transfer none]
operand2 | Another unit to multiply. | [transfer none]

#### Returns

`unit` itself for convenience in C; see the introduction for caveats.

[transfer none]

### gwy_unit_divide()

    GwyUnit *
    gwy_unit_divide (GwyUnit *unit,
                     GwyUnit *operand1,
                     GwyUnit *operand2);

Sets a unit to the ratio of two other units.

It is possible to pass either of `operand1` and `operand2` (or even both) as `unit` .

#### Parameters

unit | A unit to set to the ratio of `operand1` and `operand2` . |
operand1 | A unit to multiply. | [transfer none]
operand2 | Another unit to multiply. | [transfer none]

#### Returns

`unit` itself for convenience in C; see the introduction for caveats.

[transfer none]

### gwy_unit_power()

    GwyUnit *
    gwy_unit_power (GwyUnit *unit,
                    GwyUnit *operand,
                    gint power);

Sets a unit to an integer power of another unit.

It is possible to pass `operand` as `unit` .

#### Parameters

unit | A unit to set to the n-th power of `operand` . |
operand | A unit to raise to power `power` . | [transfer none]
power | Power to raise `operand` to. |

#### Returns

`unit` itself for convenience in C; see the introduction for caveats.

[transfer none]

### gwy_unit_nth_root()

    gboolean
    gwy_unit_nth_root (GwyUnit *unit,
                       GwyUnit *operand,
                       gint ipower);

Sets a unit to the the n-th root of another unit.

The operation fails if the result would have fractional powers that are not representable by GwyUnit.

It is possible to pass `operand` as `unit` .

#### Parameters

unit | A unit to set to the n-th root of `operand` . |
operand | A unit to raise to power `power` . | [transfer none]
ipower | The root to take: 2 means a quadratic root, 3 means cubic root, etc. |

#### Returns

`TRUE` on success, `FALSE` when taking the root was not possible and `unit` was left unchanged.

### gwy_unit_power_multiply()

    GwyUnit *
    gwy_unit_power_multiply (GwyUnit *unit,
                             GwyUnit *operand1,
                             gint power1,
                             GwyUnit *operand2,
                             gint power2);

Sets a unit to the product of two other units raised to arbitrary integer powers.

It is possible to pass either of `operand1` and `operand2` (or even both) as `unit` .

#### Parameters

unit | A unit to set to the product of powers of `operand1` and `operand2` . |
operand1 | A unit to power-multiply. | [transfer none]
power1 | Power to raise `operand1` to. |
operand2 | A unit to power-multiply. | [transfer none]
power2 | Power to raise `operand2` to. |

#### Returns

`unit` itself for convenience in C; see the introduction for caveats.

[transfer none]

### gwy_unit_factor_to_base()

    GwyUnit *
    gwy_unit_factor_to_base (GwyUnit *unit,
                             GwyUnit *result,
                             gdouble *mfactor);

Factors a possibly derived unit to base units.

For instance, if `unit` was set to "N/m" the result will be "kg/s^2".

Normally the result will consist only of the base seven units. However, recognised non-units (and pseudounits) in `unit` , such as "px" are left intact in the decomposition.

Also note that the decomposition is done to prefixable units. Kilogram is not prefixable (gram is) and there is no general way to keep the kilo- on the kilograms when deriving units for different powers of 10. Therefore, the calculated factor corresponds to decomposition to grams.

You must multiply the corresponding data with `factor` if you intend to use the `result` for them instead of `unit` !

#### Parameters

unit | A unit. |
result | A unit to set to decomposed `unit` . It is safe to pass `unit` itself. It can be `NULL` too, a new unit is created then and returned. | [nullable][transfer full]
mfactor | Location to store multiplicative factor between `unit` and `result` . For instance, for electronvolt the value 1.60217653e-16 would be stored (the factor 1000 comes from kilogram). Pass `NULL` if you are only interested dimension equality. | [out][optional]

#### Returns

When `result` is `NULL`, a newly created unit that has to be dereferenced when no longer used later. Otherwise `result` itself is simply returned, its reference count is NOT increased.

[transfer full]

### gwy_unit_equal()

    gboolean
    gwy_unit_equal (GwyUnit *unit,
                    GwyUnit *operand);

Checks whether two units are equal.

#### Parameters

unit | First unit. |
operand | Second unit. |

#### Returns

`TRUE` if the units are equal.

### gwy_unit_equal_string()

    gboolean
    gwy_unit_equal_string (GwyUnit *unit,
                           const gchar *unit_string);

Checks whether an unit corresponds to given string.

Any power-of-ten prefixes are ignored. This function is mostly useful for quick commensurability checks with simple units such as "m" and for checking whether a unit is non-empty (by comparing with `NULL` or an empty string).

#### Parameters

unit | A unit. |
unit_string | Unit string (it can be `NULL` for an empty unit). | [nullable]

#### Returns

`TRUE` if the units is equivalent to the given string.

### gwy_unit_get_format()

    GwyValueFormat *
    gwy_unit_get_format (GwyUnit *unit,
                         GwyUnitFormatStyle style,
                         gdouble value,
                         GwyValueFormat *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.

#### Parameters

unit | A 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. | [nullable]

#### Returns

The value format. If `format` was `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_unit_get_format_for_power10()

    GwyValueFormat *
    gwy_unit_get_format_for_power10 (GwyUnit *unit,
                                     GwyUnitFormatStyle style,
                                     gint power10,
                                     GwyValueFormat *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` .

#### Parameters

unit | A unit. |
style | Unit format style. |
power10 | Power of 10, in the same sense as `gwy_unit_new_parse()` returns it. |
format | A value format to set-up, may be `NULL`, a new value format is allocated then. | [nullable]

#### Returns

The value format. If `format` was `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_unit_get_format_with_resolution()

    GwyValueFormat *
    gwy_unit_get_format_with_resolution (GwyUnit *unit,
                                         GwyUnitFormatStyle style,
                                         gdouble maximum,
                                         gdouble resolution,
                                         GwyValueFormat *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.

#### Parameters

unit | A 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. | [nullable]

#### Returns

The value format. If `format` was `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_unit_get_format_with_digits()

    GwyValueFormat *
    gwy_unit_get_format_with_digits (GwyUnit *unit,
                                     GwyUnitFormatStyle style,
                                     gdouble maximum,
                                     gint sdigits,
                                     GwyValueFormat *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.

#### Parameters

unit | A 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. | [nullable]

#### Returns

The value format. If `format` was `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_unit_copy()

    GwyUnit *
    gwy_unit_copy (GwyUnit *unit);

Create a new unit as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

unit | A unit to duplicate. |

#### Returns

A copy of the unit.

[transfer full]

### gwy_unit_assign()

    void
    gwy_unit_assign (GwyUnit *destination,
                     GwyUnit *source);

Makes one unit equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target unit. |
source | Source unit. |

## Types and Values

### enum GwyUnitFormatStyle

Physical quantity formatting style.

The VF-variants differ from tne non-VF ones by a multiplication sign at the start of units (where appropriate).

#### Members

GWY_UNIT_FORMAT_NONE | No units. This value is unused by GwyUnit itself and must not be requested as a format style. |
GWY_UNIT_FORMAT_PLAIN | Plain style, as one would use on a text terminal. |
GWY_UNIT_FORMAT_MARKUP | Pango markup, for units usable standalone. |
GWY_UNIT_FORMAT_VFMARKUP | Pango markup, for units directly after value. |
GWY_UNIT_FORMAT_TEX | Representation that can be typeset by TeX, for units usable standalone. |
GWY_UNIT_FORMAT_VFTEX | Representation that can be typeset by TeX, for units directly after value. |
GWY_UNIT_FORMAT_UNICODE | Representation in which exponents are rendered as Unicode characters, for units usable standalone. |
GWY_UNIT_FORMAT_VFUNICODE | Representation in which exponents are rendered as Unicode characters, for units directly after value. |

### struct GwyUnit

    struct GwyUnit;

### struct GwyUnitClass

    struct GwyUnitClass {
        GObjectClass parent_class;

        void (*value_changed)(GwyUnit *unit);
    };

## Signal Details

### The `“value-changed”` signal

    void
    user_function (GwyUnit *gwysiunit,
                   gpointer user_data)

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

#### Parameters

gwysiunit | The GwyUnit which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First