Gwyfile Library
Objects
typedef void(* GwyfileObjectForeachFunc) (const GwyfileItem *item, void *user_data)
 Type of function for iterating over GWY file data object items. More...
 
GwyfileObject * gwyfile_object_new (const char *name,...)
 Creates a new GWY file object. More...
 
GwyfileObject * gwyfile_object_newv (const char *name, GwyfileItem **items, unsigned int nitems)
 Creates a new GWY file object. More...
 
void gwyfile_object_free (GwyfileObject *object)
 Frees a GWY file data object. More...
 
const char * gwyfile_object_name (const GwyfileObject *object)
 Obtains the name of a GWY file data object. More...
 
size_t gwyfile_object_size (const GwyfileObject *object)
 Obtains the size of a GWY file data object. More...
 
bool gwyfile_object_add (GwyfileObject *object, GwyfileItem *item)
 Adds an data item to a GWY file data object. More...
 
bool gwyfile_object_remove (GwyfileObject *object, const char *name)
 Removes an item from a GWY file data object and frees it. More...
 
GwyfileItem * gwyfile_object_get (const GwyfileObject *object, const char *name)
 Finds a data item in a GWY file object. More...
 
GwyfileItem * gwyfile_object_take (GwyfileObject *object, const char *name)
 Takes an item from a GWY file data object. More...
 
GwyfileItem * gwyfile_object_get_with_type (const GwyfileObject *object, const char *name, GwyfileItemType type)
 Finds a data item in a GWY file object, ensuring its type. More...
 
GwyfileItem * gwyfile_object_take_with_type (GwyfileObject *object, const char *name, GwyfileItemType type)
 Takes a data item from a GWY file object, ensuring its type. More...
 
void gwyfile_object_foreach (const GwyfileObject *object, GwyfileObjectForeachFunc function, void *user_data)
 Calls a function for each item contained in a GWY file data object. More...
 
unsigned int gwyfile_object_nitems (const GwyfileObject *object)
 Obtains the number of items in a GWY file data object. More...
 
const char ** gwyfile_object_item_names (const GwyfileObject *object)
 Constructs the list of names of all items in a GWY file data object. More...
 
bool gwyfile_object_fwrite (GwyfileObject *object, FILE *stream, GwyfileError **error)
 Writes a GWY file data object to a stdio stream. More...
 
GwyfileObject * gwyfile_object_fread (FILE *stream, size_t max_size, GwyfileError **error)
 Reads a GWY file data object from a stdio stream. More...
 

Detailed Description

Typedef Documentation

GwyfileObjectForeachFunc

Type of function for iterating over GWY file data object items.

This function type is used for gwyfile_object_foreach().

Parameters
itemAn object GWY file data item.
user_dataData pointer passed to gwyfile_object_foreach().

Function Documentation

bool gwyfile_object_add ( GwyfileObject *  object,
GwyfileItem *  item 
)

Adds an data item to a GWY file data object.

If no item of the same name exists in this object, the item will be consumed by the object that will take care of freeing it later. Generally, you should not access the item after passing it to this function as there is no guarantee when it will be freed.

If an item of the same name already exists in this object, the function will return false and keep the existing item. Note this means the item may be leaked if you do not check the return value.

Parameters
objectA GWY file data object.
itemA GWY file data item that is not present in any object.
Returns
true if the item was actually added.
Examples:
writegeneric.c.
void gwyfile_object_foreach ( const GwyfileObject *  object,
GwyfileObjectForeachFunc  function,
void *  user_data 
)

Calls a function for each item contained in a GWY file data object.

Parameters
objectA GWY file data object.
functionFunction to call for each item in the object.
user_dataData passed to the function. The function must not add items to object and it must not remove items either. And, of course, it must not cause object to be freed.
Examples:
readgeneric.c, and readgwy.c.
GwyfileObject* gwyfile_object_fread ( FILE *  stream,
size_t  max_size,
GwyfileError **  error 
)

Reads a GWY file data object from a stdio stream.

The stream does not have to be seekable.

On success, the position indicator in stream will be pointed after the end of the object.

On failure, the position indicator state in stream is undefined.

The maximum number of bytes to read is given by max_size which is of type size_t, however, be aware that sizes in GWY files are only 32bit. So any value that does not fit into a 32bit integer means the same as SIZE_MAX.

If reading more than max_size bytes would be required to reconstruct the top-level object, the function fails with GwyfileErrorCode::GWYFILE_ERROR_CONFINEMENT error in the GwyfileErrorDomain::GWYFILE_ERROR_DOMAIN_DATA domain.

Parameters
streamC stdio stream to read the GWY file from.
max_sizeMaximum number of bytes to read. Pass SIZE_MAX for unconstrained reading.
errorLocation for the error (or NULL).
Returns
The reconstructed data object, or NULL if the reading or reconstruction fails.
void gwyfile_object_free ( GwyfileObject *  object)

Frees a GWY file data object.

All items contained in the object are freed recursively. It is not permitted to free an object present in a data item.

You can pass NULL as object. The function is then no-op.

Parameters
objectA GWY file data object.
Examples:
checkgeneric.c, readgeneric.c, readgwy.c, writegeneric.c, and writegwy.c.
bool gwyfile_object_fwrite ( GwyfileObject *  object,
FILE *  stream,
GwyfileError **  error 
)

Writes a GWY file data object to a stdio stream.

The stream does not have to be seekable.

On success, the position indicator in stream will be pointed after the end of the written object.

On failure, the position indicator state in stream is undefined.

Parameters
objectA GWY file data object.
streamC stdio stream to write the object to.
errorLocation for the error (or NULL).
Returns
true if the writing succeeded.
GwyfileItem* gwyfile_object_get ( const GwyfileObject *  object,
const char *  name 
)

Finds a data item in a GWY file object.

This function looks up the item by name. If you want to ensure the item is also of a specified type, use gwyfile_object_get_with_type().

Parameters
objectA GWY file data object.
nameName of data item to find.
Returns
The item, if found. Otherwise NULL is returned.
Examples:
readgwy.c.
GwyfileItem* gwyfile_object_get_with_type ( const GwyfileObject *  object,
const char *  name,
GwyfileItemType  type 
)

Finds a data item in a GWY file object, ensuring its type.

This function returns an item only if both its name and type match the arguments.

Parameters
objectA GWY file data object.
nameName of data item to find.
typeType of the item to find.
Returns
The item, if found. Otherwise NULL is returned.
See also
gwyfile_object_take_with_type
Examples:
readgwy.c.
const char** gwyfile_object_item_names ( const GwyfileObject *  object)

Constructs the list of names of all items in a GWY file data object.

Parameters
objectA GWY file data object. Note the called must free the array with free() when no longer needed, but the strings within remain owned by object and are generally only guaranteed to be valid until object is changed.
Returns
A newly allocated array with names of all items in object. When there are no items NULL is returned. Upon memory allocation failure NULL is returned and errno is set to ENOMEM.
const char* gwyfile_object_name ( const GwyfileObject *  object)

Obtains the name of a GWY file data object.

Parameters
objectA GWY file data object.
Returns
The object type name. The returned string is owned by object and must not be modified or freed.
Examples:
readgeneric.c, and readgwy.c.
GwyfileObject* gwyfile_object_new ( const char *  name,
  ... 
)

Creates a new GWY file object.

The object type name must be a valid identifier formed from ASCII letters, digits and underscores. Usually, it is the name of a serialisable Gwyddion object such as "GwyDataField". However, if you use GWY files to store other hierarchical data (not intended for Gwyddion) this does not have to hold.

Each item must have a unique name.

The created object will consume all the items and will take care of freeing them. You must not touch them any more after this function returns.

Parameters
nameObject type name. It determines what data items are expected inside.
...A NULL-terminated list of items to add to the object.
Returns
The newly created GWY file object.
See also
gwyfile_object_newv
Examples:
writegeneric.c, and writegwy.c.
GwyfileObject* gwyfile_object_newv ( const char *  name,
GwyfileItem **  items,
unsigned int  nitems 
)

Creates a new GWY file object.

The object type name must be a valid identifier formed from ASCII letters, digits and underscores. Usually, it is the name of a serialisable Gwyddion object such as "GwyDataField". However, if you use GWY files to store other hierarchical data (not intended for Gwyddion) this does not have to hold.

Each item must have a unique name.

The created object will consume all the items and will take care of freeing them. You must not touch them any more after this function returns.

The array items, however, remains owned by the caller.

Parameters
nameObject type name.
itemsArray of items to add to the object.
nitemsNumber of items in items.
Returns
The newly created GWY file object.
See also
gwyfile_object_new
unsigned int gwyfile_object_nitems ( const GwyfileObject *  object)

Obtains the number of items in a GWY file data object.

Parameters
objectA GWY file data object. This function is intended to be used in conjunction with gwyfile_object_item_names() or possibly gwyfile_object_foreach().
Returns
The number of items in object.
bool gwyfile_object_remove ( GwyfileObject *  object,
const char *  name 
)

Removes an item from a GWY file data object and frees it.

Parameters
objectA GWY file data object.
nameName of data item to remove.
Returns
Whether such item was present and was removed.
size_t gwyfile_object_size ( const GwyfileObject *  object)

Obtains the size of a GWY file data object.

The size includes the size of object name and the size field itself. See gwyfile_object_data_size() for the size of just object data.

Parameters
objectA GWY file data object.
Returns
The object size, in bytes.
GwyfileItem* gwyfile_object_take ( GwyfileObject *  object,
const char *  name 
)

Takes an item from a GWY file data object.

The caller becomes the owner of the returned item and is responsible for freeing it later.

Parameters
objectA GWY file data object.
nameName of data item to take.
Returns
The item, if found. Otherwise NULL is returned.
GwyfileItem* gwyfile_object_take_with_type ( GwyfileObject *  object,
const char *  name,
GwyfileItemType  type 
)

Takes a data item from a GWY file object, ensuring its type.

This function returns an item only if both its name and type match the arguments.

The caller becomes the owner of the returned item and is responsible for freeing it later.

Parameters
objectA GWY file data object.
nameName of data item to find.
typeType of the item to find.
Returns
The item, if found. Otherwise NULL is returned.
See also
gwyfile_object_get_with_type