GwyEnum: Gwyddion Library Reference Manual

## GwyEnum GwyEnum — String-integer value pair |

## Functions

gint | gwy_string_to_enum ()
const gchar * | gwy_enum_to_string ()
const gchar * | gwy_enuml_to_string ()
gint | gwy_string_to_flags ()
gchar * | gwy_flags_to_string ()
gint | gwy_enum_sanitize_value ()
void | gwy_enum_freev ()
GwyInventory * | gwy_enum_inventory_new ()
GwyEnum * | gwy_enum_fill_from_struct ()

## Types and Values

| GwyEnum

## Object Hierarchy

        gpointer
        ╰── GwyEnum

## Includes

    #include <libgwyddion/gwyddion.h>

## 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()`.

## Functions

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

#### Parameters

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

#### Parameters

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()

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

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

#### Parameters

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 a const empty string is returned.

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

The inventory will have two traits, "name" and "value".

#### Parameters

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.

[transfer full]

### gwy_enum_fill_from_struct()

    GwyEnum *
    gwy_enum_fill_from_struct (GwyEnum *enum_table,
                               gint n,
                               gconstpointer items,
                               guint item_size,
                               gint name_offset,
                               gint value_offset);

Fills an enum definition from another struct.

Use `G_STRUCT_OFFSET()` to obtain `name_offset` and `value_offset` .

If `value_offset` is -1 the enum values are made equal to `items` array indices from 0 to `n` -1. Otherwise they values are taken from `items` and can be arbitrary.

If `enum_table` is not `NULL` and its value fields are filled (i.e. not all zeros), the function just fills the corresponding names according to `items` . This allows reordering `enum_table` with respect to `items` .

In all other cases both names and values are filled in the same order as in `items` .

The string names are not duplicated; they are only copied as pointers.

#### Parameters

enum_table | A table of string-integer pairs to fill, possibly `NULL` to allocate a new one. | [nullable]
n | The number of elements in `enum_table` . It must not be -1. |
items | Struct items containing the names and values at given offsets. |
item_size | Size of one item in `items` , in bytes. |
name_offset | Offset of the name field (of gchar* type) in the struct, in bytes. |
value_offset | Offset of the value field (of 32bit integer type) in the struct, in bytes. Pass -1 if values are just item indices. |

#### Returns

Either `enum_table` itself, or a newly allocated enum table if it was `NULL`.

## Types and Values

### GwyEnum

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

Enumerated type with named values.

#### Members

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

## See Also

GwyInventory