GwySIUnit

GwySIUnit — unit representation, physical quantitiy formatting

Functions

Signals

void value-changed Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GwySIUnit

Implemented Interfaces

GwySIUnit implements GwySerializable.

Includes

#include <libgwyddion/gwyddion.h>

Description

GwySIUnit object represents a physical 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().

Functions

gwy_si_unit_new()

GwySIUnit *
gwy_si_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.)

Parameters

unit_string

Unit string (it can be NULL for an empty unit).

 

Returns

A new unit.


gwy_si_unit_new_parse()

GwySIUnit *
gwy_si_unit_new_parse (const gchar *unit_string,
                       gint *power10);

Creates a new 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 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).

 

power10

Where power of 10 should be stored (or NULL).

 

Returns

A new 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.).

Parameters

siunit

A 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 unit according to string representation.

This is a more powerful version of gwy_si_unit_set_from_string(). See gwy_si_unit_new_parse() for some discussion.

Parameters

siunit

A 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 unit.

Parameters

siunit

A 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 units.

Parameters

siunit1

A unit.

 

siunit2

A unit.

 

result

A 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 unit is created then and returned.

 

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.


gwy_si_unit_divide()

GwySIUnit *
gwy_si_unit_divide (GwySIUnit *siunit1,
                    GwySIUnit *siunit2,
                    GwySIUnit *result);

Divides two units.

Parameters

siunit1

A unit.

 

siunit2

A unit.

 

result

A 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 unit is created then and returned.

 

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.


gwy_si_unit_power()

GwySIUnit *
gwy_si_unit_power (GwySIUnit *siunit,
                   gint power,
                   GwySIUnit *result);

Computes a power of an unit.

Parameters

siunit

A unit.

 

power

Power to raise siunit to.

 

result

A 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 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 unit.

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

Parameters

siunit

A unit.

 

ipower

The root to take: 2 means a quadratic root, 3 means cubic root, etc.

 

result

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


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 units raised to arbitrary powers.

This is the most complex unit arithmetic function. It can be easily chained when more than two units are to be multiplied.

Parameters

siunit1

A unit.

 

power1

Power to raise siunit1 to.

 

siunit2

A unit.

 

power2

Power to raise siunit2 to.

 

result

A unit to set to siunit1 ^power1 *siunit2 ^power2 . It is safe to pass siunit1 or siunit2 . It can be NULL too, a new unit is created then and returned.

 

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.


gwy_si_unit_factor_to_base()

GwySIUnit *
gwy_si_unit_factor_to_base (GwySIUnit *siunit,
                            GwySIUnit *result,
                            gdouble *mfactor);

Factors a possibly derived unit to base units.

For instance, if siunit 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 siunit , 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

siunit

A unit.

 

result

A unit to set to decomposed siunit . It is safe to pass siunit itself. It can be NULL too, a new unit is created then and returned.

 

mfactor

Location to store multiplicative factor between siunit 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.

 

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.


gwy_si_unit_equal()

gboolean
gwy_si_unit_equal (GwySIUnit *siunit,
                   GwySIUnit *siunit2);

Checks whether two units are equal.

Parameters

siunit

First unit.

 

siunit2

Second unit.

 

Returns

TRUE if the units are equal.


gwy_si_unit_equal_string()

gboolean
gwy_si_unit_equal_string (GwySIUnit *siunit,
                          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

siunit

A unit.

 

unit_string

Unit string (it can be NULL for an empty unit).

 

Returns

TRUE if the units is equivalent to the given string.


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.

Parameters

siunit

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.

 

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 .

Parameters

siunit

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

Parameters

siunit

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.

 

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.

Parameters

siunit

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.

 

Returns

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


gwy_si_unit_copy()

GwySIUnit *
gwy_si_unit_copy (GwySIUnit *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_si_unit_assign()

void
gwy_si_unit_assign (GwySIUnit *destination,
                    GwySIUnit *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 GwySIUnitFormatStyle

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_SI_UNIT_FORMAT_NONE

No units. This value is unused by GwySIUnit itself and must not be requested as a format style.

 

GWY_SI_UNIT_FORMAT_PLAIN

Plain style, as one would use on a text terminal.

 

GWY_SI_UNIT_FORMAT_MARKUP

Pango markup, for units usable standalone.

 

GWY_SI_UNIT_FORMAT_VFMARKUP

Pango markup, for units directly after value.

 

GWY_SI_UNIT_FORMAT_TEX

Representation that can be typeset by TeX, for units usable standalone.

 

GWY_SI_UNIT_FORMAT_VFTEX

Representation that can be typeset by TeX, for units directly after value.

 

GWY_SI_UNIT_FORMAT_UNICODE

Representation in which exponents are rendered as Unicode characters, for units usable standalone.

 

GWY_SI_UNIT_FORMAT_VFUNICODE

Representation in which exponents are rendered as Unicode characters, for units directly after value.

 

struct GwySIUnit

struct GwySIUnit;

The GwySIUnit struct contains private data only and should be accessed using the functions below.


struct GwySIUnitClass

struct GwySIUnitClass {
    GObjectClass parent_class;

    void (*value_changed)(GwySIUnit *siunit);
};

Signal Details

The “value-changed” signal

void
user_function (GwySIUnit *gwysiunit,
               gpointer   user_data)

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

Parameters

gwysiunit

The GwySIUnit which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First