GwyEnum (HEAD)

GwyEnum — String-integer value pair

Functions

gint	gwy_string_to_enum ()
const gchar *	gwy_enum_to_string ()
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 ()

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

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.

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

Since: 2.59

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