Serialisation utils

Serialisation utils — Helper functions for classes implementing serialisation

Functions

Includes

#include <libgwyddion/gwyddion.h>

Description

Functions

gwy_serialize_append_unit()

void
gwy_serialize_append_unit (GwySIUnit *unit,
                           const GwySerializableItem *model,
                           GwySerializableItems *items,
                           guint *n);

Helps to serialise one object member of unit type.

It is not an error to pass a NULL as unit . A NULL unit is not serialised.

Parameters

unit

A unit member object.

 

model

Item template (of GWY_SERIALIZABLE_OBJECT type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_string()

void
gwy_serialize_append_string (gchar *string,
                             const GwySerializableItem *model,
                             GwySerializableItems *items,
                             guint *n);

Helps to serialise one object member of string type.

It is not an error to pass a NULL as string . A NULL string is not serialised.

The string is never modified by this function.

Parameters

string

A string member.

 

model

Item template (of GWY_SERIALIZABLE_STRING type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_int32()

void
gwy_serialize_append_int32 (gint32 value,
                            const GwySerializableItem *model,
                            GwySerializableItems *items,
                            guint *n);

Helps to serialise one object member of 32bit integer type.

Parameters

value

A 32bit integer member.

 

model

Item template (of GWY_SERIALIZABLE_INT32 type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_int64()

void
gwy_serialize_append_int64 (gint64 value,
                            const GwySerializableItem *model,
                            GwySerializableItems *items,
                            guint *n);

Helps to serialise one object member of 64bit integer type.

Parameters

value

A 64bit integer member.

 

model

Item template (of GWY_SERIALIZABLE_INT64 type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_boolean()

void
gwy_serialize_append_boolean (gboolean value,
                              const GwySerializableItem *model,
                              GwySerializableItems *items,
                              guint *n);

Helps to serialise one object member of boolean type.

Parameters

value

A boolean member.

 

model

Item template (of GWY_SERIALIZABLE_BOOLEAN type).

 

items

List of serialisation items.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_double()

void
gwy_serialize_append_double (gdouble value,
                             const GwySerializableItem *model,
                             GwySerializableItems *items,
                             guint *n);

Helps to serialise one object member of double type.

If the value is equal to the value in model (assumed default) it is not serialised.

Parameters

value

A double member.

 

model

Item template (of GWY_SERIALIZABLE_DOUBLE type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_string_array()

void
gwy_serialize_append_string_array (gchar **strings,
                                   gsize len,
                                   const GwySerializableItem *model,
                                   GwySerializableItems *items,
                                   guint *n);

Helps to serialise one object member of string array type.

It is not an error to an empty array as strings . If len is zero, strings is NULL or strings is an array containing only NULL elements, the member is not serialised. Otherwise it is serialised and all the strings must exist. It is an error to pass strings array with some elements NULL and some non-NULL.

The array contents is never modified by this function.

Parameters

strings

A string array member.

 

len

Number of elements in strings .

 

model

Item template (of GWY_SERIALIZABLE_STRING_ARRAY type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_int32_array()

void
gwy_serialize_append_int32_array (gint32 *values,
                                  gsize len,
                                  const GwySerializableItem *model,
                                  GwySerializableItems *items,
                                  guint *n);

Helps to serialise one object member of 32bit integer array type.

It is not an error to an empty array as values . If len is zero or values is NULL, the member is not serialised. It is valid to pass non-zero len with NULL values and vice versa.

The array contents is never modified by this function.

Parameters

values

An array of 32bit integers member.

 

len

Number of elements in values .

 

model

Item template (of GWY_SERIALIZABLE_INT32_ARRAY type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_int64_array()

void
gwy_serialize_append_int64_array (gint64 *values,
                                  gsize len,
                                  const GwySerializableItem *model,
                                  GwySerializableItems *items,
                                  guint *n);

Helps to serialise one object member of 64bit integer array type.

It is not an error to an empty array as values . If len is zero or values is NULL, the member is not serialised. It is valid to pass non-zero len with NULL values and vice versa.

The array contents is never modified by this function.

Parameters

values

An array of 64bit integers member.

 

len

Number of elements in values .

 

model

Item template (of GWY_SERIALIZABLE_INT64_ARRAY type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_append_double_array()

void
gwy_serialize_append_double_array (gdouble *values,
                                   gsize len,
                                   const GwySerializableItem *model,
                                   GwySerializableItems *items,
                                   guint *n);

Helps to serialise one object member of double array type.

It is not an error to an empty array as values . If len is zero or values is NULL, the member is not serialised. It is valid to pass non-zero len with NULL values and vice versa.

The array contents is never modified by this function.

Parameters

values

An array of doubles member.

 

len

Number of elements in values .

 

model

Item template (of GWY_SERIALIZABLE_DOUBLE_ARRAY type).

 

items

List of items to append to.

 

n

Location with the number of this this object's items to possibly update.

 

gwy_serialize_items_done()

void
gwy_serialize_items_done (GwySerializableItems *items);

Frees temporary serialisation data for a list of serialisation items.

The functions is useful for serialisers, not individual classes implementing serialisation. It calls gwy_serializable_done() on all objects in items that need it, in the correct (i.e. backwards) order. This is normally done at the end of serialisation.

Keep in mind that it only releases whatever is inside the top-level serialised object. You also need to finally call gwy_serializable_done() on the top-level object itself to release its temporary data.

Parameters

items

List of flattened object tree items.

 

gwy_fill_serializable_defaults_pspec()

void
gwy_fill_serializable_defaults_pspec (GwySerializableItem *items,
                                      gsize n_items,
                                      gboolean names_may_differ);

Fills serializable template item values using param specs.

The item type must be compatible with the param spec type. For instance, a 32bit integer item may have param spec of signed or unsigned integer type or it can be an enum.

If both items and properties have names set they should be equal (the function prints a warning unless names_may_differ is TRUE). Items that do not have names but have a param spec will have their names set to match the corresponding properties. In such case the property name must be a static string.

Only atomic items which have aux.pspec set have the values set.

Parameters

items

List of serialisation items.

 

n_items

The number of items in items .

 

names_may_differ

Pass TRUE if items and properties both have names and they can differ.

 

gwy_deserialize_filter_items()

void
gwy_deserialize_filter_items (GwySerializableItem *model,
                              gsize n_items,
                              GwySerializableItems *items,
                              const gchar *type_name,
                              GwyErrorList **error_list);

Fills the template of expected items with values from received item list.

This is a helper function for use in GwySerializable.construct() method.

Expected values are moved from items to model . This means the owner of model becomes the owner of dynamically allocated data in these items. Unexpected items are left in items . The the owner of items has to free them which normally means you do not need to concern yourself with them.

The owner of model is, however, responsible for freeing data there. Often this means it just takes over the arrays/objects and uses them in its own data structures. Do not forget freeing the data also in the case of failure though.

An item template is identified by its name and type. Multiple items of the same name are permitted in model as long as their types differ (this can be useful e.g. to accept old serialised representations for compatibility).

The concrete type of boxed types is not part of the identification, i.e. only one boxed item of a specific name can be given in model and the type, if specified as array_size , must match exactly.

Parameters

model

List of expected items. Generally, the values should be set to defaults (NULL for non-atomic types).

 

n_items

The number of items in the template.

 

items

Item list passed to construct().

 

type_name

Name of the deserialised type for error messages.

 

error_list

Location to store the errors occuring, NULL to ignore. Only non-fatal error GWY_DESERIALIZE_ERROR_ITEM can occur.

 

gwy_check_object_component()

gboolean
gwy_check_object_component (const GwySerializableItem *item,
                            const gchar *type_name,
                            GType component_type,
                            GwyErrorList **error_list);

Checks if objects in a deserialised item list match the expected type.

The item must be of type GWY_SERIALIZABLE_OBJECT or GWY_SERIALIZABLE_OBJECT_ARRAY. In the latter case all elements are checked.

If a single object is NULL (i.e. the corresponding component was not present in the file) the function return FALSE but does not report any error. This is usually the most useful behaviour. If you need to distinguish missing and invalid objects, simply check value.v_object .

An array of objects cannot have holes. So either the array exists and is full of objects or the entire array is missing. The function returns TRUE only if the array exists and all objects match the type. When the array is NULL, FALSE is returned, but no errors are set.

Parameters

item

Serialised item.

 

type_name

Name of the type being deserialised (used for error messages only).

 

component_type

Expected component type.

 

error_list

Location to store the errors occuring, NULL to ignore.

 

Returns

TRUE if the types match, FALSE if they do not.


gwy_check_double_component()

gboolean
gwy_check_double_component (const GwySerializableItem *item,
                            const gchar *type_name,
                            gdouble min,
                            gdouble max,
                            GwyErrorList **error_list);

Checks if a floating point value in a deserialised item list is normal and within allowed range.

The item must be of type GWY_SERIALIZABLE_DOUBLE.

Parameters

item

Serialised item for a floating point value.

 

type_name

Name of the type being deserialised (used for error messages only).

 

min

The minimum allowed value.

 

max

The maximum allowed value.

 

error_list

Location to store the errors occuring, NULL to ignore.

 

Returns

TRUE if the value is normal and within range [min ,max ] (inclusive), FALSE if it is not.


gwy_check_int32_component()

gboolean
gwy_check_int32_component (const GwySerializableItem *item,
                           const gchar *type_name,
                           gint32 min,
                           gint32 max,
                           GwyErrorList **error_list);

Checks if a 32bit integer value in a deserialised item list is within allowed range.

The item must be of type GWY_SERIALIZABLE_INT32.

Parameters

item

Serialised item for a 32bit integer point value.

 

type_name

Name of the type being deserialised (used for error messages only).

 

min

The minimum allowed value.

 

max

The maximum allowed value.

 

error_list

Location to store the errors occuring, NULL to ignore.

 

Returns

TRUE if the value is within range [min ,max ] (inclusive), FALSE if it is not.


gwy_check_enum_component()

gboolean
gwy_check_enum_component (const GwySerializableItem *item,
                          const gchar *type_name,
                          GType enum_type,
                          GwyErrorList **error_list);

Checks if an enumerated value in a deserialised item list is valid.

The item must be of type GWY_SERIALIZABLE_INT32.

Parameters

item

Serialised item for a 32bit integer point value.

 

type_name

Name of the type being deserialised (used for error messages only).

 

enum_type

Type of the enum the value must belong to.

 

error_list

Location to store the errors occuring, NULL to ignore.

 

Returns

TRUE if the value is among the enumerated values, FALSE if it is not.


gwy_check_data_length_multiple()

gboolean
gwy_check_data_length_multiple (GwyErrorList **error_list,
                                const gchar *type_name,
                                gsize len,
                                guint multiple);

Checks if data length is a multiple of a fixed number.

Zero length is considered valid.

Parameters

error_list

Location to store the errors occuring, NULL to ignore.

 

type_name

Name of the type being deserialised (used for error messages only).

 

len

Data length.

 

multiple

Positive number len must be a multiple of.

 

Returns

TRUE if the data length is valid, FALSE if it is not.


gwy_check_data_dimension()

gboolean
gwy_check_data_dimension (GwyErrorList **error_list,
                          const gchar *type_name,
                          guint n_dims,
                          gsize expected_size,
                          ...);

Checks if deserialised data dimensions are valid.

Any positive dimensions which do not multiply to an integer overflow are currently considered valid, unless expected_size is also given. In such case they must multiply exactly to expected_size . Since individual zero dimensions are invalid zero is never a valid expected_size .

A zero-dimensional array always has one element (a scalar). The empty product is equal to 1 by definition. However, it is usually not meaningful to call this function with n_dims =0.

Parameters

error_list

Location to store the errors occuring, NULL to ignore.

 

type_name

Name of the type being deserialised (used for error messages only).

 

n_dims

Number of dimensions.

 

expected_size

Expected data size (product of all the dimensions), if known. Pass 0 to not check the total size.

 

...

Exactly n_dims numbers which were deserialised as dimensions of a possibly multi-dimensional array. The numbers are guint (not gsize).

 

Returns

TRUE if the dimensions are valid, FALSE if they are not.