Gwyfile Library
Gwyfile Library Documentation

The libgwyfile library contains fundamental functions for reading and writing Gwyddion GWY files as foreign data, i.e. without adopting the Gwyddion object system.

The latest libgwyfile source code and documentation can be found on the project web page at SourceForge.

Namespace

All macros, declarations and exported symbols bear the gwyfile prefix to avoid clash with other names. Specifically:

Names of this form are to be treated as reserved and avoided for your own symbols. This is recommended even if you are embedding the library as it makes easier updating to its future versions.

Ownership rules

Since the GWY file data structures always form a forest of trees, object and items are either roots (including standalone objects and items) or owned by the parent object or item. When you add an item into an object or put an object to an object-holding item, you always transfer the ownership. Only the roots are owned by you.

Specific non-atomic data, such as arrays and strings, are also typically owned by the data item containing them and the item takes care of freeing them when destroyed itself. Specifically, this is always the case when they are created by reading a file. However, the ownership can be transferred between the item and you.

For creation of non-atomic data, there are three types of functions:

Each item construction function has also an item data-setting counterpart. For instance gwyfile_item_set_string(), gwyfile_item_set_string_copy() and gwyfile_item_set_string_const() correspond to the three string item construction functions mentioned above.

For obtaining of non-atomic data, two different types of functions exist:

Error handling

Roughly, libgwyfile distinguishes three severities of errors

Version

This documentation was generated from the following source code revision:

$Id: gwyfile.c 283 2016-04-27 20:48:28Z yeti-dn $