## Validate

Validate — Check data sanity and consistency

## Synopsis

    #include <app/gwyapp.h>

    enum                GwyDataError;
    enum                GwyDataValidateFlags;
                        GwyDataValidationFailure;
    GSList*             gwy_data_validate                   (GwyContainer *data,
                                                             GwyDataValidateFlags flags);
    const gchar*        gwy_data_error_desrcibe             (GwyDataError error);
    void                gwy_data_validation_failure_list_free
                                                            (GSList *list);

## 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.

## Details

### enum GwyDataError

    typedef enum {
        GWY_DATA_ERROR_KEY_FORMAT = 1,
        GWY_DATA_ERROR_KEY_CHARACTERS,
        GWY_DATA_ERROR_KEY_UNKNOWN,
        GWY_DATA_ERROR_KEY_ID,
        GWY_DATA_ERROR_ITEM_TYPE,
        GWY_DATA_ERROR_NON_UTF8_STRING,
        GWY_DATA_ERROR_REF_COUNT,
        GWY_DATA_ERROR_STRAY_SECONDARY_DATA,
    } GwyDataError;

Type of data validation errors.

`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

    typedef enum {
        GWY_DATA_VALIDATE_UNKNOWN   = 1 << 0,
        GWY_DATA_VALIDATE_REF_COUNT = 1 << 1,
        GWY_DATA_VALIDATE_ALL       = 0x0003,
        GWY_DATA_VALIDATE_CORRECT   = 1 << 16,
        GWY_DATA_VALIDATE_NO_REPORT = 1 << 17,
    } 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.

`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.

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

### 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.

`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.

`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.

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

Since 2.9