Validate: Gwyddion Application Library Reference Manual

## Validate Validate — Check data sanity and consistency |

## Functions

GSList * | gwy_data_validate ()
const gchar * | gwy_data_error_desrcibe ()
void | gwy_data_validation_failure_list_free ()

## Types and Values

enum | GwyDataError
enum | GwyDataValidateFlags
| GwyDataValidationFailure

## Includes

    #include <app/gwyapp.h>

## Description

A GwyContainer can be used to represent all sorts of data. However, Gwyddion, the application, follows certain conventions in data organization. Function `gwy_data_validate()` checks whether the data actually follows them. This includes but is not limited to representability of keys in ASCII, conformance to the key naming convention, types of objects and other items corresponding to expectation, string values being valid UTF-8 and no stray secondary data.

## Functions

### gwy_data_validate ()

    GSList *
    gwy_data_validate (GwyContainer *data,
                       GwyDataValidateFlags flags);

Checks the contents of a data file.

If `GWY_DATA_VALIDATE_CORRECT` is given in `flags` , correctable problems are corrected. At present correctable problems are those that can be fixed by removal of the offending data.

#### Parameters

data | Data container. It should not be managed by the data browser (yet) if flags contain `GWY_DATA_VALIDATE_CORRECT` (because things can in principle break during the correction) or `GWY_DATA_VALIDATE_REF_COUNT` (because the application took some references). |
flags | Validation flags. Some influence what is checked, some determine what to do when problems are found. |

#### Returns

List of errors found, free with `gwy_data_validation_failure_list_free()`. The list is independent on whether `GWY_DATA_VALIDATE_CORRECT` is given in flags, even though the offending items may be no longer exist in the container after correction. If `GWY_DATA_VALIDATE_NO_REPORT` is present in flags, `NULL` is always returned.

Since: 2.9

### gwy_data_error_desrcibe ()

    const gchar *
    gwy_data_error_desrcibe (GwyDataError error);

Describes a data validation error type.

#### Parameters

error | Data validation error type. |

#### Returns

Error description as an untranslated string owned by the library.

Since: 2.9

### gwy_data_validation_failure_list_free ()

    void
    gwy_data_validation_failure_list_free (GSList *list);

Frees a data validation failure list.

#### Parameters

list | Failure list returned by `gwy_data_validate()`. |

Since: 2.9

## Types and Values

### enum GwyDataError

Type of data validation errors.

#### Members

GWY_DATA_ERROR_KEY_FORMAT | Key format is invalid (e.g. does not start with `GWY_CONTAINER_PATHSEP`). |
GWY_DATA_ERROR_KEY_CHARACTERS | Key contains unprintable characters or characters not representable in ASCII. |
GWY_DATA_ERROR_KEY_UNKNOWN | Key does not correspond to any data item known to this version of Gwyddion. |
GWY_DATA_ERROR_KEY_ID | Key corresponds to a data item with bogus id number. |
GWY_DATA_ERROR_ITEM_TYPE | Wrong item type (for instance an integer at key `"/0/data"`). |
GWY_DATA_ERROR_NON_UTF8_STRING | String value is not valid UTF-8. |
GWY_DATA_ERROR_REF_COUNT | Reference count is higher than 1. |
GWY_DATA_ERROR_STRAY_SECONDARY_DATA | Secondary data item (e.g. mask, selection or visibility) without a corresponding valid primary data item. |

Since: 2.9

### enum GwyDataValidateFlags

Flags controlling `gwy_data_validate()` behaviour.

Note passing `GWY_DATA_VALIDATE_NO_REPORT` is allowed only if `GWY_DATA_VALIDATE_CORRECT` is present too.

#### Members

GWY_DATA_VALIDATE_UNKNOWN | Report all unknown keys as `GWY_DATA_ERROR_KEY_UNKNOWN` errors. Note while a data item unknown to the current version of Gwyddion can come from a newer version therefore it can be in certain sense valid. |
GWY_DATA_VALIDATE_REF_COUNT | Report all object items with reference count higher than 1 as `GWY_DATA_ERROR_REF_COUNT` errors. Obviously this makes sense only with `fresh' data containers. |
GWY_DATA_VALIDATE_ALL | All above flags combined. |
GWY_DATA_VALIDATE_CORRECT | Attempt to correct problems. |
GWY_DATA_VALIDATE_NO_REPORT | Do not report problems. |

Since: 2.9

### GwyDataValidationFailure

    typedef struct {
        GwyDataError error;
        GQuark key;
        gchar *details;
    } GwyDataValidationFailure;

Information about one data validate error.

Note the structure may contain more private fields.

#### Members

GwyDataError `error`; | Error type. |
GQuark `key`; | Key of the problematic data item. |
gchar *`details`; | Error details, may be `NULL` for some types of `error` . This is a dynamically allocated string owned by the caller, however, he normally frees the complete errors lists with `gwy_data_validation_failure_list_free()` which frees these fields too. |

Since: 2.9