## utils

utils

## Synopsis

    void                gsf_init                            (void);
    void                gsf_shutdown                        (void);
    void                gsf_init_dynamic                    (GTypeModule *module);
    void                gsf_shutdown_dynamic                (GTypeModule *module);
    extern              int libgsf_major_version;
    extern              int libgsf_minor_version;
    extern              int libgsf_micro_version;

    #define             GSF_CLASS                           (name, prefix, class_init, instance_init, parent)
    #define             GSF_CLASS_FULL                      (name, prefix, base_init, base_finalize,
                                                             		       class_init, class_finalize, instance_init, parent_type,
                                                             		       abstract, interface_decl)
    #define             GSF_CLASS_ABSTRACT                  (name, prefix, class_init, instance_init, parent)
    #define             GSF_INTERFACE                       (init_func, iface_type)
    #define             GSF_INTERFACE_FULL                  (type, init_func, iface_type)
    #define             GSF_DYNAMIC_CLASS                   (name, prefix, class_init, instance_init, parent)
    #define             GSF_DYNAMIC_CLASS_FULL              (name, prefix, base_init, base_finalize,
                                                             				   class_init,  class_finalize, instance_init, parent_type,
                                                             			       abstract, interface_decl)
    #define             GSF_DYNAMIC_CLASS_ABSTRACT          (name, prefix, class_init, instance_init, parent)
    #define             GSF_DYNAMIC_INTERFACE               (init_func, iface_type, module)
    #define             GSF_DYNAMIC_INTERFACE_FULL          (type, init_func, iface_type, module)
    #define             GSF_PARAM_STATIC

    #define             GSF_ERROR
    enum                GsfError;
    GQuark              gsf_error_quark                     (void);

    void                gsf_mem_dump                        (guint8 const *ptr,
                                                             size_t len);
    void                gsf_input_dump                      (GsfInput *input,
                                                             gboolean dump_as_hex);

    #define             GSF_OFF_T_FORMAT
    typedef             gsf_off_t;
    char*               gsf_filename_to_utf8                (char const *filename,
                                                             gboolean quoted);
    void                gsf_iconv_close                     (GIConv handle);
    charconst *         gsf_extension_pointer               (char const *path);

    guint8*             gsf_base64_encode_simple            (guint8 const *data,
                                                             size_t len);
    size_t              gsf_base64_encode_close             (guint8 const *in,
                                                             size_t inlen,
                                                             gboolean break_lines,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);
    size_t              gsf_base64_encode_step              (guint8 const *in,
                                                             size_t len,
                                                             gboolean break_lines,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);
    size_t              gsf_base64_decode_simple            (guint8 *data,
                                                             size_t len);
    size_t              gsf_base64_decode_step              (guint8 const *in,
                                                             size_t len,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);
    #define             GSF_LE_GET_GINT8                    (p)
    #define             GSF_LE_GET_GUINT64                  (p)
    #define             GSF_LE_GET_GINT16                   (p)
    #define             GSF_LE_GET_GUINT8                   (p)
    #define             GSF_LE_GET_GINT32                   (p)
    #define             GSF_LE_GET_GUINT16                  (p)
    #define             GSF_LE_GET_GUINT32                  (p)
    #define             GSF_LE_GET_GINT64                   (p)
    guint64             gsf_le_get_guint64                  (void const *p);
    #define             GSF_LE_GET_FLOAT                    (p)
    float               gsf_le_get_float                    (void const *p);
    #define             GSF_LE_GET_DOUBLE                   (p)
    double              gsf_le_get_double                   (void const *p);
    #define             GSF_LE_SET_GUINT8                   (p, dat)
    #define             GSF_LE_SET_GUINT16                  (p, dat)
    #define             GSF_LE_SET_GUINT32                  (p, dat)
    #define             GSF_LE_SET_GINT8                    (p,dat)
    #define             GSF_LE_SET_GINT16                   (p,dat)
    #define             GSF_LE_SET_GINT32                   (p,dat)
    #define             GSF_LE_SET_GINT64                   (p,dat)
    #define             GSF_LE_SET_GUINT64                  (p, dat)
    #define             GSF_LE_SET_FLOAT                    (p,dat)
    #define             GSF_LE_SET_DOUBLE                   (p,dat)
    void                gsf_le_set_float                    (void *p,
                                                             float f);
    void                gsf_le_set_double                   (void *p,
                                                             double d);

                        GsfTimestamp;
    GsfTimestamp*       gsf_timestamp_copy                  (GsfTimestamp const *stamp);
    void                gsf_timestamp_free                  (GsfTimestamp *stamp);
    char*               gsf_timestamp_as_string             (GsfTimestamp const *stamp);
    int                 gsf_timestamp_parse                 (char const *spec,
                                                             GsfTimestamp *stamp);
    guint               gsf_timestamp_hash                  (GsfTimestamp const *stamp);
    gboolean            gsf_timestamp_equal                 (GsfTimestamp const *a,
                                                             GsfTimestamp const *b);
    void                gsf_value_set_timestamp             (GValue *value,
                                                             GsfTimestamp const *stamp);
    #define             VAL_IS_GSF_TIMESTAMP                (v)

    GValue*             gsf_doc_prop_swap_val               (GsfDocProp *prop,
                                                             GValue *val);
    void                gsf_property_settings_collect       (GType object_type,
                                                             GParameter **p_params,
                                                             size_t *p_n_params,
                                                             const gchar *first_property_name,
                                                             ...);
    void                gsf_property_settings_collect_valist
                                                            (GType object_type,
                                                             GParameter **p_params,
                                                             size_t *p_n_params,
                                                             const gchar *first_property_name,
                                                             va_list var_args);
    void                gsf_property_settings_free          (GParameter *params,
                                                             size_t n_params);

## Description

## Details

### gsf_init ()

    void                gsf_init                            (void);

Initializes the GSF library

### gsf_shutdown ()

    void                gsf_shutdown                        (void);

De-intializes the GSF library from a type module. Currently does nothing.

### gsf_init_dynamic ()

    void                gsf_init_dynamic                    (GTypeModule *module);

Initializes the GSF library and associates it with a type module `mod`.

`module` : | GTypeModule.

### gsf_shutdown_dynamic ()

    void                gsf_shutdown_dynamic                (GTypeModule *module);

`module` : |

### libgsf_major_version

    extern int libgsf_major_version;

Major version number of libgsf, indicating the ABI version.

### libgsf_minor_version

    extern int libgsf_minor_version;

Minor (secondary) version number of libgsf, indicating the API version.

### libgsf_micro_version

    extern int libgsf_micro_version;

Micro (tertiary) version number of libgsf, indicating bug fixes.

### GSF_CLASS()

    #define             GSF_CLASS(name, prefix, class_init, instance_init, parent)

Set up a GSF class.

`name` : | (string) Name of the class.
`prefix` : | (string) Prefix designating the namespace to be used for implementing the class.
`class_init` : | (GClassInitFunc) Initialisation function for the class.
`instance_init` : | (GInstanceInitFunc) Initialisation (constructor) function for an instance of the class.
`parent` : | Parent class to this class.

### GSF_CLASS_FULL()

    #define             GSF_CLASS_FULL(name, prefix, base_init, base_finalize, \
                		       class_init, class_finalize, instance_init, parent_type, \
                		       abstract, interface_decl)

`name` : |
`prefix` : |
`base_init` : |
`base_finalize` : |
`class_init` : |
`class_finalize` : |
`instance_init` : |
`parent_type` : |
`abstract` : |
`interface_decl` : |

### GSF_CLASS_ABSTRACT()

    #define             GSF_CLASS_ABSTRACT(name, prefix, class_init, instance_init, parent)

`name` : |
`prefix` : |
`class_init` : |
`instance_init` : |
`parent` : |

### GSF_INTERFACE()

    #define             GSF_INTERFACE(init_func, iface_type)

`init_func` : |
`iface_type` : |

### GSF_INTERFACE_FULL()

    #define             GSF_INTERFACE_FULL(type, init_func, iface_type)

`type` : |
`init_func` : |
`iface_type` : |

### GSF_DYNAMIC_CLASS()

    #define             GSF_DYNAMIC_CLASS(name, prefix, class_init, instance_init, parent)

`name` : |
`prefix` : |
`class_init` : |
`instance_init` : |
`parent` : |

### GSF_DYNAMIC_CLASS_FULL()

    #define             GSF_DYNAMIC_CLASS_FULL(name, prefix, base_init, base_finalize, \
                				   class_init,  class_finalize, instance_init, parent_type, \
                			       abstract, interface_decl)

`name` : |
`prefix` : |
`base_init` : |
`base_finalize` : |
`class_init` : |
`class_finalize` : |
`instance_init` : |
`parent_type` : |
`abstract` : |
`interface_decl` : |

### GSF_DYNAMIC_CLASS_ABSTRACT()

    #define             GSF_DYNAMIC_CLASS_ABSTRACT(name, prefix, class_init, instance_init, parent)

`name` : |
`prefix` : |
`class_init` : |
`instance_init` : |
`parent` : |

### GSF_DYNAMIC_INTERFACE()

    #define             GSF_DYNAMIC_INTERFACE(init_func, iface_type, module)

`init_func` : |
`iface_type` : |
`module` : |

### GSF_DYNAMIC_INTERFACE_FULL()

    #define             GSF_DYNAMIC_INTERFACE_FULL(type, init_func, iface_type, module)

`type` : |
`init_func` : |
`iface_type` : |
`module` : |

### GSF_PARAM_STATIC

    #define             GSF_PARAM_STATIC

### GSF_ERROR

    #define GSF_ERROR (gsf_error_quark ())

### enum GsfError

    typedef enum {
    	GSF_ERROR_OUT_OF_MEMORY,
    	GSF_ERROR_INVALID_DATA
    } GsfError;

### gsf_error_quark ()

    GQuark              gsf_error_quark                     (void);

Returns : | the GQuark used to identify libgsf errors in GError structures. Specific error codes come from the GsfError enumeration.

### gsf_mem_dump ()

    void                gsf_mem_dump                        (guint8 const *ptr,
                                                             size_t len);

Dump `len` bytes from the memory location given by `ptr`.

`ptr` : | memory area to be dumped.
`len` : | how many bytes will be dumped.

### gsf_input_dump ()

    void                gsf_input_dump                      (GsfInput *input,
                                                             gboolean dump_as_hex);

Dumps `input`'s contents to STDOUT, optionally in hex format.

`input` : | a GsfInput
`dump_as_hex` : | If `TRUE`, dump in hexidecmal format

### GSF_OFF_T_FORMAT

    #define GSF_OFF_T_FORMAT	G_GINT64_FORMAT

The printf(3) conversion specifier to be used for printing values of type gsf_off_t.

### gsf_off_t

    typedef gint64 gsf_off_t;

Data type to represent offsets (positions) within a data stream.

FIXME: gsf_off_t is really supposed to be the widest type off_t can be configured to on the platform

### gsf_filename_to_utf8 ()

    char*               gsf_filename_to_utf8                (char const *filename,
                                                             gboolean quoted);

A utility wrapper to make sure filenames are valid utf8. Caller must g_free the result.

`filename` : | file name suitable for open(2).
`quoted` : | if `TRUE`, the resulting utf8 file name will be quoted (unless it is invalid).
Returns : | `filename` using utf-8 encoding for display

### gsf_iconv_close ()

    void                gsf_iconv_close                     (GIConv handle);

A utility wrapper to safely close an iconv handle.

`handle` : | handle to be closed.

### gsf_extension_pointer ()

    charconst *         gsf_extension_pointer               (char const *path);

Extracts the extension from the end of a filename (the part after the final '.' in the filename).

`path` : | A filename or file path.
Returns : | A pointer to the extension part of the filename, or a pointer to the end of the string if the filename does not have an extension.

### gsf_base64_encode_simple ()

    guint8*             gsf_base64_encode_simple            (guint8 const *data,
                                                             size_t len);

Encodes data from `data` back into `data` using base64 encoding.

`data` : | data stream
`len` : | max length of data to encode
Returns : | the number of bytes encoded

### gsf_base64_encode_close ()

    size_t              gsf_base64_encode_close             (guint8 const *in,
                                                             size_t inlen,
                                                             gboolean break_lines,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);

This funcion should be called to when finished encoding everything, to flush off the last little bit.

`in` : | Data to be encoded
`inlen` : | Length of data to be encoded
`break_lines` : | Whether to use line breaks
`out` : | Encoded data.
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : |

### gsf_base64_encode_step ()

    size_t              gsf_base64_encode_step              (guint8 const *in,
                                                             size_t len,
                                                             gboolean break_lines,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);

Performs an 'encode step', only encodes blocks of 3 characters from `in` into the output `out` at a time, saves left-over state in `state` and `save` (initialise to 0 on first invocation).

`in` : | input stream
`len` : | max length of data to decode
`break_lines` : | Whether to use line breaks
`out` : | output stream
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : | the number of bytes encoded

### gsf_base64_decode_simple ()

    size_t              gsf_base64_decode_simple            (guint8 *data,
                                                             size_t len);

Decodes a chunk of base64 encoded data from `data` back into `data`.

`data` : | data stream
`len` : | max length of data to decode
Returns : | the number of bytes converted

### gsf_base64_decode_step ()

    size_t              gsf_base64_decode_step              (guint8 const *in,
                                                             size_t len,
                                                             guint8 *out,
                                                             int *state,
                                                             guint *save);

Decodes a chunk of base64 encoded data

`in` : | input stream
`len` : | max length of data to decode
`out` : | output stream
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : | the number of bytes converted

### GSF_LE_GET_GINT8()

    #define GSF_LE_GET_GINT8(p) ((gint8)GSF_LE_GET_GUINT8(p))

Interpret binary data as a signed 8-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GUINT64()

    #define GSF_LE_GET_GUINT64(p) (gsf_le_get_guint64 (p))

Interpret binary data as an unsigned 64-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GINT16()

    #define GSF_LE_GET_GINT16(p) ((gint16)GSF_LE_GET_GUINT16(p))

Interpret binary data as a signed 16-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GUINT8()

    #define GSF_LE_GET_GUINT8(p) (*(guint8 const *)(p))

Interpret binary data as an unsigned 8-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GINT32()

    #define GSF_LE_GET_GINT32(p) ((gint32)GSF_LE_GET_GUINT32(p))

Interpret binary data as a signed 32-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GUINT16()

    #define             GSF_LE_GET_GUINT16(p)

Interpret binary data as an unsigned 16-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GUINT32()

    #define             GSF_LE_GET_GUINT32(p)

Interpret binary data as an unsigned 32-bit integer in little endian order.

`p` : | pointer to storage

### GSF_LE_GET_GINT64()

    #define GSF_LE_GET_GINT64(p) ((gint64)GSF_LE_GET_GUINT64(p))

Interpret binary data as a signed 64-bit integer in little endian order.

`p` : | pointer to storage

### gsf_le_get_guint64 ()

    guint64             gsf_le_get_guint64                  (void const *p);

Interpret binary data as a guint64 (8 byte unsigned integer type) in little endian order.

`p` : | pointer to storage
Returns : | interpreted data

### GSF_LE_GET_FLOAT()

    #define GSF_LE_GET_FLOAT(p) (gsf_le_get_float (p))

Interpret binary data as a float in little endian order.

`p` : | pointer to storage

### gsf_le_get_float ()

    float               gsf_le_get_float                    (void const *p);

Interpret binary data as a float in little endian order.

`p` : | pointer to storage
Returns : | interpreted data

### GSF_LE_GET_DOUBLE()

    #define GSF_LE_GET_DOUBLE(p) (gsf_le_get_double (p))

Interpret binary data as a double in little endian order.

`p` : | pointer to storage

### gsf_le_get_double ()

    double              gsf_le_get_double                   (void const *p);

Interpret binary data as a double in little endian order.

`p` : | pointer to storage
Returns : | interpreted data

### GSF_LE_SET_GUINT8()

    #define             GSF_LE_SET_GUINT8(p, dat)

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 8-bit unsigned integer

### GSF_LE_SET_GUINT16()

    #define             GSF_LE_SET_GUINT16(p, dat)

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 16-bit unsigned integer

### GSF_LE_SET_GUINT32()

    #define             GSF_LE_SET_GUINT32(p, dat)

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 32-bit unsigned integer

### GSF_LE_SET_GINT8()

    #define GSF_LE_SET_GINT8(p,dat) GSF_LE_SET_GUINT8((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 8-bit signed integer

### GSF_LE_SET_GINT16()

    #define GSF_LE_SET_GINT16(p,dat) GSF_LE_SET_GUINT16((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 16-bit signed integer

### GSF_LE_SET_GINT32()

    #define GSF_LE_SET_GINT32(p,dat) GSF_LE_SET_GUINT32((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 32-bit signed integer

### GSF_LE_SET_GINT64()

    #define GSF_LE_SET_GINT64(p,dat) GSF_LE_SET_GUINT64((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 64-bit signed integer

### GSF_LE_SET_GUINT64()

    #define             GSF_LE_SET_GUINT64(p, dat)

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | 64-bit unsigned integer

### GSF_LE_SET_FLOAT()

    #define GSF_LE_SET_FLOAT(p,dat) gsf_le_set_float((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | float to be stored

### GSF_LE_SET_DOUBLE()

    #define GSF_LE_SET_DOUBLE(p,dat) gsf_le_set_double((p),(dat))

Store `dat` in little endian order in memory pointed to by `p`.

`p` : | pointer to storage
`dat` : | double to be stored

### gsf_le_set_float ()

    void                gsf_le_set_float                    (void *p,
                                                             float f);

Store a value of type float in memory in little endian order.

`p` : | pointer to storage
`f` : | float to be stored

### gsf_le_set_double ()

    void                gsf_le_set_double                   (void *p,
                                                             double d);

Store a value of type double in memory in little endian order

`p` : | pointer to storage
`d` : | double to be stored

### GsfTimestamp

    typedef struct {
    	GDate	  date;			/* In local timezone */
    	glong     seconds;		/* time of day */
    	GString	  time_zone;		/* possibly blank */

    	guint32	  timet;
    } GsfTimestamp;

Class representing a point in time.

### gsf_timestamp_copy ()

    GsfTimestamp*       gsf_timestamp_copy                  (GsfTimestamp const *stamp);

Copies a timestamp.

`stamp` : | timestamp to be copied
Returns : | a separate copy of `stamp`.

### gsf_timestamp_free ()

    void                gsf_timestamp_free                  (GsfTimestamp *stamp);

Releases the memory in use for `stamp` (if any).

`stamp` : | timestamp to be freed

### gsf_timestamp_as_string ()

    char*               gsf_timestamp_as_string             (GsfTimestamp const *stamp);

Produce a string representation (ISO 8601 format) of `stamp`.

`stamp` : | timestamp to be converted.
Returns : | a string representation of `stamp`. When `stamp` is `NULL`, the representation is "<invalid>".

### gsf_timestamp_parse ()

    int                 gsf_timestamp_parse                 (char const *spec,
                                                             GsfTimestamp *stamp);

Very simple parser for time stamps. Currently requires a format of 'YYYY-MM-DDThh:mm:ss' and does no bounds checking.

ICK ICK ICK This routine should be called _from_sting.

`spec` : | The string to parse
`stamp` : | GsfTimestamp
Returns : | `TRUE` on success

### gsf_timestamp_hash ()

    guint               gsf_timestamp_hash                  (GsfTimestamp const *stamp);

`stamp` : |
Returns : |

### gsf_timestamp_equal ()

    gboolean            gsf_timestamp_equal                 (GsfTimestamp const *a,
                                                             GsfTimestamp const *b);

Compare timestamps `a` and `b`.

`a` : | a timestamp
`b` : | another timestamp
Returns : | true if `a` and `b` represent the same point in time; false otherwise.

### gsf_value_set_timestamp ()

    void                gsf_value_set_timestamp             (GValue *value,
                                                             GsfTimestamp const *stamp);

`value` : |
`stamp` : |

### VAL_IS_GSF_TIMESTAMP()

    #define VAL_IS_GSF_TIMESTAMP(v) (G_TYPE_CHECK_VALUE_TYPE((v), GSF_TIMESTAMP_TYPE))

`v` : |

### gsf_doc_prop_swap_val ()

    GValue*             gsf_doc_prop_swap_val               (GsfDocProp *prop,
                                                             GValue *val);

`prop` : | GsfDocProp
`val` : | GValue
Returns : | the current value of `prop`, and replaces it with `val` Caller is responsible for unsetting and freeing the result.

### gsf_property_settings_collect ()

    void                gsf_property_settings_collect       (GType object_type,
                                                             GParameter **p_params,
                                                             size_t *p_n_params,
                                                             const gchar *first_property_name,
                                                             ...);

`object_type` : |
`p_params` : |
`p_n_params` : |
`first_property_name` : |
`...` : |

### gsf_property_settings_collect_valist ()

    void                gsf_property_settings_collect_valist
                                                            (GType object_type,
                                                             GParameter **p_params,
                                                             size_t *p_n_params,
                                                             const gchar *first_property_name,
                                                             va_list var_args);

This function builds a GParameter array suitable for g_object_newv.

`object_type` : | the GType for which the properties are being set.
`p_params` : | a pointer to the GParameter array that holds the properties. (Used for both input and output. This may point to a `NULL` pointer if there are no properties collected yet.)
`p_n_params` : | a pointer to the number of properties collected. (Used for both input and output.)
`first_property_name` : | the name of the first property being set, or NULL.
`var_args` : | a va_list holding the remainder of the property names and values, terminated by a `NULL`.

### gsf_property_settings_free ()

    void                gsf_property_settings_free          (GParameter *params,
                                                             size_t n_params);

`params` : |
`n_params` : |