## GwySIValueFormat GwySIValueFormat — Physical quantitiy formatting |

## Functions

GwySIValueFormat * | gwy_si_unit_value_format_new ()
GwySIValueFormat * | gwy_si_unit_value_format_copy ()
void | gwy_si_unit_value_format_free ()
GwySIValueFormat * | gwy_si_unit_value_format_clone ()
void | gwy_si_unit_value_format_set_units ()

## Types and Values

| GwySIValueFormat

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

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

## Functions

### gwy_si_unit_value_format_new ()

    GwySIValueFormat *
    gwy_si_unit_value_format_new (gdouble magnitude,
                                  gint precision,
                                  const gchar *units);

Constructs a new value format directly.

Usually you construct value formats from a GwySIUnit using functions such as `gwy_si_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.

Since: 2.46

### gwy_si_unit_value_format_copy ()

    GwySIValueFormat *
    gwy_si_unit_value_format_copy (GwySIValueFormat *format);

Copies a value format structure.

#### Parameters

format | A value format to copy. |

#### Returns

Newly allocated value format, identical to `format` .

Since: 2.39

### gwy_si_unit_value_format_free ()

    void
    gwy_si_unit_value_format_free (GwySIValueFormat *format);

Frees a value format structure.

#### Parameters

format | A value format to free. |

### gwy_si_unit_value_format_clone ()

    GwySIValueFormat *
    gwy_si_unit_value_format_clone (GwySIValueFormat *source,
                                    GwySIValueFormat *dest);

Clones a value format to another.

This function follows the convention of many value format updating functions that can either modify an existing format or allocate a new one.

#### Parameters

source | Source value format. |
dest | Destination value format, or `NULL`. |

#### Returns

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

Since: 2.46

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

#### Parameters

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

## Types and Values

### GwySIValueFormat

    typedef struct {
        gdouble magnitude;
        gint precision;
        gchar *units;
    } 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 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` . |