Validate (HEAD)

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