## file module utils

file module utils — Utility functions for file modules

## Synopsis

    #include <app/gwymoduleutils-file.h>

    gboolean            gwy_get_gboolean8                   (const guchar **ppv);
    gint16              gwy_get_gint16_le                   (const guchar **ppv);
    gint16              gwy_get_gint16_be                   (const guchar **ppv);
    guint16             gwy_get_guint16_le                  (const guchar **ppv);
    guint16             gwy_get_guint16_be                  (const guchar **ppv);
    gint32              gwy_get_gint32_le                   (const guchar **ppv);
    gint32              gwy_get_gint32_be                   (const guchar **ppv);
    guint32             gwy_get_guint32_le                  (const guchar **ppv);
    guint32             gwy_get_guint32_be                  (const guchar **ppv);
    gint64              gwy_get_gint64_le                   (const guchar **ppv);
    gint64              gwy_get_gint64_be                   (const guchar **ppv);
    guint64             gwy_get_guint64_le                  (const guchar **ppv);
    guint64             gwy_get_guint64_be                  (const guchar **ppv);
    gfloat              gwy_get_gfloat_le                   (const guchar **ppv);
    gfloat              gwy_get_gfloat_be                   (const guchar **ppv);
    gdouble             gwy_get_gdouble_le                  (const guchar **ppv);
    gdouble             gwy_get_gdouble_be                  (const guchar **ppv);
    gdouble             gwy_get_pascal_real_le              (const guchar **ppv);
    gdouble             gwy_get_pascal_real_be              (const guchar **ppv);
    gboolean            gwy_app_channel_check_nonsquare     (GwyContainer *data,
                                                             gint id);
    gboolean            gwy_app_channel_title_fall_back     (GwyContainer *data,
                                                             gint id);

## Description

Functions `gwy_app_channel_check_nonsquare()` and `gwy_app_channel_title_fall_back()` perform common tasks improving the imported of channels from foreign data files. Typically one calls them on all imported channel ids after storing the data fields the the container, if they are useful for a given file type.

The group of functions `gwy_get_gint16_le()`, `gwy_get_gint16_be()`, etc. is intended to portably read packed binary data structures that are commonly found in SPM files. They all work identically: the binary data value is read from the buffer, converted if necessary, and the provided buffer pointer is moved to point after the value to faciliate sequential reading.

As no buffer size is passed, obviously no buffer size checking is performed. The caller has to ensure the buffer is large enough -- it is expected the caller checks the total buffer size before starting to parse it.

For example to portably read the following packed struct stored in big-endian byte order:

    struct {
        guint16 xres;
        guint16 yres;
        gfloat measure;
    } header;

one can do (after checking the buffer size):

    const guchar *p = buffer;
    header.xres    = gwy_get_guint16_be(&p);
    header.yres    = gwy_get_guint16_be(&p);
    header.measure = gwy_get_gfloat_be(&p);

and `p` will point after `measure` in `buffer` after this snippet is finished.

The data types used in `header` do not matter (provided they are large enough to hold the values), the exact types are determined by the functions used. Therefore the reading would work identically if `header` was defined using common types:

    struct {
        gint xres;
        gint yres;
        gdouble measure;
    } header;

## Details

### gwy_get_gboolean8 ()

    gboolean            gwy_get_gboolean8                   (const guchar **ppv);

Reads a boolean value stored as a signle byte from a binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to boolean (stored as a signle byte) in a memory buffer.
Returns : | The gboolean value read from the buffer.

Since 2.3

### gwy_get_gint16_le ()

    gint16              gwy_get_gint16_le                   (const guchar **ppv);

Reads a signed 16bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian signed 16bit integer in a memory buffer.
Returns : | The gint16 value read from the buffer.

Since 2.3

### gwy_get_gint16_be ()

    gint16              gwy_get_gint16_be                   (const guchar **ppv);

Reads a signed 16bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian signed 16bit integer in a memory buffer.
Returns : | The gint16 value read from the buffer.

Since 2.3

### gwy_get_guint16_le ()

    guint16             gwy_get_guint16_le                  (const guchar **ppv);

Reads an unsigned 16bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian unsigned 16bit integer in a memory buffer.
Returns : | The guint16 value read from the buffer.

Since 2.3

### gwy_get_guint16_be ()

    guint16             gwy_get_guint16_be                  (const guchar **ppv);

Reads an unsigned 16bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian unsigned 16bit integer in a memory buffer.
Returns : | The guint16 value read from the buffer.

Since 2.3

### gwy_get_gint32_le ()

    gint32              gwy_get_gint32_le                   (const guchar **ppv);

Reads a signed 32bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian signed 32bit integer in a memory buffer.
Returns : | The gint32 value read from the buffer.

Since 2.3

### gwy_get_gint32_be ()

    gint32              gwy_get_gint32_be                   (const guchar **ppv);

Reads a signed 32bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian signed 32bit integer in a memory buffer.
Returns : | The gint32 value read from the buffer.

Since 2.3

### gwy_get_guint32_le ()

    guint32             gwy_get_guint32_le                  (const guchar **ppv);

Reads an unsigned 32bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian unsigned 32bit integer in a memory buffer.
Returns : | The guint32 value read from the buffer.

Since 2.3

### gwy_get_guint32_be ()

    guint32             gwy_get_guint32_be                  (const guchar **ppv);

Reads an unsigned 32bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian unsigned 32bit integer in a memory buffer.
Returns : | The guint32 value read from the buffer.

Since 2.3

### gwy_get_gint64_le ()

    gint64              gwy_get_gint64_le                   (const guchar **ppv);

Reads a signed 64bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian signed 64bit integer in a memory buffer.
Returns : | The gint64 value read from the buffer.

Since 2.3

### gwy_get_gint64_be ()

    gint64              gwy_get_gint64_be                   (const guchar **ppv);

Reads a signed 64bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian signed 64bit integer in a memory buffer.
Returns : | The gint64 value read from the buffer.

Since 2.3

### gwy_get_guint64_le ()

    guint64             gwy_get_guint64_le                  (const guchar **ppv);

Reads an unsigned 64bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian unsigned 64bit integer in a memory buffer.
Returns : | The guint64 value read from the buffer.

Since 2.3

### gwy_get_guint64_be ()

    guint64             gwy_get_guint64_be                  (const guchar **ppv);

Reads an unsigned 64bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian unsigned 64bit integer in a memory buffer.
Returns : | The guint64 value read from the buffer.

Since 2.3

### gwy_get_gfloat_le ()

    gfloat              gwy_get_gfloat_le                   (const guchar **ppv);

Reads a single-precision IEEE float value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian single-precision IEEE float in a memory buffer.
Returns : | The gfloat value read from the buffer.

Since 2.3

### gwy_get_gfloat_be ()

    gfloat              gwy_get_gfloat_be                   (const guchar **ppv);

Reads a single-precision IEEE float value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian single-precision IEEE float in a memory buffer.
Returns : | The gfloat value read from the buffer.

Since 2.3

### gwy_get_gdouble_le ()

    gdouble             gwy_get_gdouble_le                  (const guchar **ppv);

Reads a double-precision IEEE float value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian double-precision IEEE float in a memory buffer.
Returns : | The gdouble value read from the buffer.

Since 2.3

### gwy_get_gdouble_be ()

    gdouble             gwy_get_gdouble_be                  (const guchar **ppv);

Reads a double-precision IEEE float value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian double-precision IEEE float in a memory buffer.
Returns : | The gdouble value read from the buffer.

Since 2.3

### gwy_get_pascal_real_le ()

    gdouble             gwy_get_pascal_real_le              (const guchar **ppv);

Reads a six-byte Pascale Real value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a little-endian six-byte Pascal Real in a memory buffer.
Returns : | The floating point value read from the buffer as a gdouble.

Since 2.3

### gwy_get_pascal_real_be ()

    gdouble             gwy_get_pascal_real_be              (const guchar **ppv);

Reads a six-byte Pascale Real value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.

`ppv` : | Pointer to a pointer to a big-endian six-byte Pascal Real in a memory buffer.
Returns : | The floating point value read from the buffer as a gdouble.

Since 2.3

### gwy_app_channel_check_nonsquare ()

    gboolean            gwy_app_channel_check_nonsquare     (GwyContainer *data,
                                                             gint id);

Sets `realsquare' for a channel highly non-square pixels.

The threshold for highly non-square is somewhat arbitrary. Fortunately, most files encoutered in practice have the measure ratio either very close to 1, larger or equal than 2.

`data` : | A data container.
`id` : | Data channel id.
Returns : | `TRUE` if the channel was found to have highly non-square pixels and `realsquare' was set (otherwise it was unset).

Since 2.3

### gwy_app_channel_title_fall_back ()

    gboolean            gwy_app_channel_title_fall_back     (GwyContainer *data,
                                                             gint id);

Adds a channel title based on data field units.

The guess is very simple, but probably better than `Unknown channel' in most cases. If there already is a title it is left intact, making use of this function as a fall-back easier.

`data` : | A data container.
`id` : | Data channel id.
Returns : | `TRUE` if the title was set (either by this function or before).

Since 2.3