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