GwyValueFormat: Gwyddion Library Reference Manual

## GwyValueFormat GwyValueFormat — Physical quantitiy formatting |

## Functions

GwyValueFormat * | gwy_value_format_new ()
GwyValueFormat * | gwy_value_format_copy ()
void | gwy_value_format_free ()
void | gwy_value_format_assign ()
void | gwy_value_format_set_units ()

## Types and Values

| GwyValueFormat

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyValueFormat object represents instructions how to format numbers representing physical quantities, including precision and units. They are usually created based on a GwyUnit and some data ranges with functions such as `gwy_unit_get_format_with_resolution()` or `gwy_unit_get_format_with_digits()`. Various data objects also offer method for obtaining value formats representing reasonably their coordinates or values, for instance `gwy_field_get_value_format_xy()`.

## Functions

### gwy_value_format_new()

    GwyValueFormat *
    gwy_value_format_new (gdouble magnitude,
                          gint precision,
                          const gchar *units);

Constructs a new value format directly.

Usually you construct value formats from a GwyUnit using functions such as `gwy_unit_get_format_with_digits()` or obtain it from data object functions.

#### Parameters

magnitude | Number to divide a quantity by (a power of 1000). |
precision | Number of decimal places to format a quantity to. |
units | Units to put after quantity divided by `magnitude` . |

#### Returns

Newly allocated value format.

### gwy_value_format_copy()

    GwyValueFormat *
    gwy_value_format_copy (GwyValueFormat *format);

Copies a value format structure.

#### Parameters

format | A value format to copy. |

#### Returns

Newly allocated value format, identical to `format` .

### gwy_value_format_free()

    void
    gwy_value_format_free (GwyValueFormat *format);

Frees a value format structure.

#### Parameters

format | A value format to free. |

### gwy_value_format_assign()

    void
    gwy_value_format_assign (GwyValueFormat *format,
                             GwyValueFormat *source);

Assigns a value format from another.

#### Parameters

format | Destination value format. |
source | Source value format. |

### gwy_value_format_set_units()

    void
    gwy_value_format_set_units (GwyValueFormat *format,
                                const gchar *units);

Sets the units field of a value format structure.

This function keeps the `units` and `units_gstring` fields consistent.

#### Parameters

format | A value format to set units of. |
units | The units string. |

## Types and Values

### GwyValueFormat

    typedef struct {
        gdouble magnitude;
        gint precision;
        gchar *units;
    } GwyValueFormat;

A physical quantity formatting information.

The `magnitude` and `precision` fields can be directly modified if necessary. Units must be always set with `gwy_value_format_set_units()` to update the internal representation correctly.

#### Members

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 field must be considered read-only as it is actually an alias to `units_gstring->str` . |