GwyEnum

GwyEnum — String-integer value pair

Synopsis




#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);
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_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