Serialisation utils: Gwyddion Library Reference Manual

## Serialisation utils Serialisation utils — Helper functions for classes implementing serialisation |

## Functions

void | gwy_fill_serializable_defaults_pspec ()
void | gwy_deserialize_filter_items ()
gboolean | gwy_check_object_component ()
gboolean | gwy_check_double_component ()
gboolean | gwy_check_float_component ()
gboolean | gwy_check_int32_component ()
gboolean | gwy_check_enum_component ()
gboolean | gwy_check_data_length_multiple ()
gboolean | gwy_check_data_dimension ()

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### 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. | [array length=n_items]
n_items | The number of items in `group` . |
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,
                                  GwySerializableGroup *group,
                                  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 `group` to `model` . It means their ownership is transferred from `group` to `model` . Unexpected items are left in `group` . The owner of `group` frees such items. It normally means you do not need to concern yourself with them because `group` is owned by the deserialisation function.

The owner of `model` (normally the object being constructed) is, however, responsible for consuming or freeing all data moved there. Often it means it just takes over the arrays/objects and uses them in its own data structures. Do not forget to free the data also in the case of failure.

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 using the `aux` field, 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. |
group | 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. | [nullable]

### 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_float_component()

    gboolean
    gwy_check_float_component (const GwySerializableItem *item,
                               const gchar *type_name,
                               gfloat min,
                               gfloat 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 array_size,
                              const gsize *logical_dims);

Checks if deserialised data dimensions are valid.

Any positive dimensions which do not multiply to an integer overflow are currently considered valid, unless `array_size` is also given. In such case they must multiply exactly to `array_size` . Since individual zero dimensions are invalid, zero is never a valid `array_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. |
array_size | Physical array size (product of all the dimensions), if known. Pass 0 to not check the total size. |
logical_dims | `n_dims` logical dimensions, i.e. numbers which were deserialised as dimensions of a possibly multi-dimensional array. |

#### Returns

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