## GwyEnum

GwyEnum — String-integer value pair

## Synopsis

    #include <libgwyddion/gwyddion.h>

    #define             GWY_TYPE_ENUM
                        GwyEnum;
    GType               gwy_enum_get_type                   (void);
    gint                gwy_string_to_enum                  (const gchar *str,
                                                             const GwyEnum *enum_table,
                                                             gint n);
    const gchar*        gwy_enum_to_string                  (gint enumval,
                                                             const GwyEnum *enum_table,
                                                             gint n);
    gchar*              gwy_enuml_to_string                 (gint enumval,
                                                             ...);
    gint                gwy_string_to_flags                 (const gchar *str,
                                                             const GwyEnum *enum_table,
                                                             gint n,
                                                             const gchar *delimiter);
    gchar*              gwy_flags_to_string                 (gint enumval,
                                                             const GwyEnum *enum_table,
                                                             gint n,
                                                             const gchar *glue);
    gint                gwy_enum_sanitize_value             (gint enumval,
                                                             GType enum_type);
    void                gwy_enum_freev                      (GwyEnum *enum_table);
    GwyInventory*       gwy_enum_inventory_new              (const GwyEnum *enum_table,
                                                             gint n);

## Description

GwyEnum is a simple association of a string and integer enum value used in various places in Gwyddion. An enum table can be easily used as a constant GwyInventory base with `gwy_enum_inventory_new()`.

## Details

### GWY_TYPE_ENUM

    #define GWY_TYPE_ENUM                  (gwy_enum_get_type())

### GwyEnum

    typedef struct {
        const gchar *name;
        gint value;
    } GwyEnum;

Enumerated type with named values.

const gchar *`name`; | Value name.
gint `value`; | The (integer) enum value.

### gwy_enum_get_type ()

    GType               gwy_enum_get_type                   (void);

Returns : |

### gwy_string_to_enum ()

    gint                gwy_string_to_enum                  (const gchar *str,
                                                             const GwyEnum *enum_table,
                                                             gint n);

Creates an integer representation of a string enum value `str`.

`str` : | A string containing one of `enum_table` string values.
`enum_table` : | A table of corresponding string-integer pairs.
`n` : | The number of elements in `enum_table`, may be -1 when `enum_table` is terminated by a NULL name.
Returns : | The integer enum value (NOT index in the table), or -1 if `str` was not found.

### gwy_enum_to_string ()

    const gchar*        gwy_enum_to_string                  (gint enumval,
                                                             const GwyEnum *enum_table,
                                                             gint n);

Creates a string representation of an integer enum value `enumval`.

`enumval` : | A one integer value from `enum_table`.
`enum_table` : | A table of corresponding string-integer pairs.
`n` : | The number of elements in `enum_table`, may be -1 when `enum_table` is terminated by a NULL name.
Returns : | The name as a string from `enum_table`, thus it generally should not be modified or freed, unless `enum_table` is supposed to be modified too. If the value is not found, an empty string is returned.

### gwy_enuml_to_string ()

    gchar*              gwy_enuml_to_string                 (gint enumval,
                                                             ...);

Creates a string representation of an integer enum value `enumval`.

`enumval` : | Integer value to find.
`...` : | First enum name, first value, second enum name, second value, etc. Terminated with `NULL`.
Returns : | The corresponding enum name string argument if `enumval` matches some of them. Otherwise `NULL` is returned (this is different from `gwy_enum_to_string()` which returns an empty string).

Since 2.5

### gwy_string_to_flags ()

    gint                gwy_string_to_flags                 (const gchar *str,
                                                             const GwyEnum *enum_table,
                                                             gint n,
                                                             const gchar *delimiter);

Creates an integer flag combination of its string representation `str`.

`str` : | A string containing one of `enum_table` string values.
`enum_table` : | A table of corresponding string-integer pairs.
`n` : | The number of elements in `enum_table`, may be -1 when `enum_table` is terminated by a NULL name.
`delimiter` : | A delimiter to split `str` on, when NULL space is used.
Returns : | All the flags present in `str`, bitwise ORer.

### gwy_flags_to_string ()

    gchar*              gwy_flags_to_string                 (gint enumval,
                                                             const GwyEnum *enum_table,
                                                             gint n,
                                                             const gchar *glue);

Creates a string representation of integer flag combination `enumval`.

`enumval` : | Some ORed integer flags from `enum_table`.
`enum_table` : | A table of corresponding string-integer pairs.
`n` : | The number of elements in `enum_table`, may be -1 when `enum_table` is terminated by a NULL name.
`glue` : | A glue to join string values with, when NULL space is used.
Returns : | The string representation as a newly allocated string. It should be freed when no longer used.

### gwy_enum_sanitize_value ()

    gint                gwy_enum_sanitize_value             (gint enumval,
                                                             GType enum_type);

Makes sure an enum value is valid.

`enumval` : | An enum value.
`enum_type` : | GType of a registered enum type.
Returns : | Either `enumval` itself if it's valid, or some valid enum value. When `enumval` is invalid and larger than all valid values the largest valid value is returned. Likewise if it's smaller the smallest valid value is returned. If it's in range but invalid, the first enum value is returned.

### gwy_enum_freev ()

    void                gwy_enum_freev                      (GwyEnum *enum_table);

Frees a dynamically allocated enum.

More precisely, it frees all names of a GwyEnum and then frees the enum itself.

`enum_table` : | A `NULL`-name-terminated, dynamically allocated enum table.

### gwy_enum_inventory_new ()

    GwyInventory*       gwy_enum_inventory_new              (const GwyEnum *enum_table,
                                                             gint n);

Convenience function to create a constant inventory from a GwyEnum.

The enum table is directly used and therefore must exist during the lifetime of the inventory.

`enum_table` : | A table of corresponding string-integer pairs.
`n` : | The number of elements in `enum_table`, may be -1 when `enum_table` is terminated by a NULL name.
Returns : | The newly created constant inventory.

## See Also

GwyInventory