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

### gsf_init_dynamic ()

    void        gsf_init_dynamic                (GTypeModule *module);

`module` : |

### gsf_shutdown_dynamic ()

    void        gsf_shutdown_dynamic            (GTypeModule *module);

`module` : |

### libgsf_major_version

    extern int libgsf_major_version;

The major version number of the GSF library. (e.g. in GSF version 1.2.5 this is 1.)

This variable is in the library and thus represents the GSF library you have linked against (which may be different from the version of the GSF library from which you have included the headers).

### libgsf_minor_version

    extern int libgsf_minor_version;

The minor version number of the GLib library. (e.g. in GLib version 1.2.5 this is 2.)

This variable is in the library and thus represents the GSF library you have linked against (which may be different from the version of the GSF library from which you have included the headers).

### libgsf_micro_version

    extern int libgsf_micro_version;

The micro version number of the GSF library. (e.g. in GSF version 1.2.5 this is 5.)

This variable is in the library and thus represents the GSF library you have linked against (which may be different from the version of the GSF library from which you have included the headers).

### GSF_CLASS()

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

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

### 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_init: @\ class_init:
`class_finalize` : |
`instance_init` : |
`parent_type` : | @\ abstract: @\ abstract: @\ 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_init: @\ class_init:
`class_finalize` : |
`instance_init` : |
`parent_type` : | @\ abstract: @\ abstract: @\ 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 ())

This convenience macro simply calls `gsf_error_quark()`. You can use it in calls to `g_error_matches()`, for example. The macro returns the GQuark that is used to identify errors from libgsf functions. Specific error codes come from the GsfError enumeration.

### enum GsfError

    typedef enum {
    	GSF_ERROR_OUT_OF_MEMORY,
    	GSF_ERROR_INVALID_DATA
    } GsfError;

Error codes that can be returned from libgsf functions in GError structures.

`GSF_ERROR_OUT_OF_MEMORY` | Not enough memory could be allocated to hold a structure or object.
`GSF_ERROR_INVALID_DATA` | A file being read contained invalid or inconsistent data.

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

Returns : | A GQuark.

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

### gsf_off_t

    typedef gint64 gsf_off_t;

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

`data` : |
`len` : |
Returns : |

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

`in` : |
`inlen` : |
`break_lines` : |
`out` : |
`state` : |
`save` : |
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);

`in` : |
`len` : |
`break_lines` : |
`out` : |
`state` : |
`save` : |
Returns : |

### gsf_base64_decode_simple ()

    size_t      gsf_base64_decode_simple        (guint8 *data,
                                                 size_t len);

`data` : |
`len` : |
Returns : |

### 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 data as an 8 bit integer value in little endian order.

`p` : | Pointer to storage

### GSF_LE_GET_GUINT64()

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

Interpret data as a 64 bit unsigned integer value 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 data as a 16 bit integer value in little endian order.

`p` : | Pointer to storage

### GSF_LE_GET_GUINT8()

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

Interpret data as an 8 bit unsigned integer value 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 data as a 32 bit integer value in little endian order.

`p` : | Pointer to storage

### GSF_LE_GET_GUINT16()

    #define     GSF_LE_GET_GUINT16(p)

Interpret data as a 16 bit unsigned integer value in little endian order.

`p` : | Pointer to storage

### GSF_LE_GET_GUINT32()

    #define     GSF_LE_GET_GUINT32(p)

Interpret data as a 32 bit unsigned integer value 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 data as a 64 bit integer value 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 data as a float value 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 data as a double value 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 an 8 bit unsigned integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GUINT16()

    #define     GSF_LE_SET_GUINT16(p, dat)

Store a 16 bit unsigned integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GUINT32()

    #define     GSF_LE_SET_GUINT32(p, dat)

Store a 32 bit unsigned integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GINT8()

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

Store an 8 bit integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GINT16()

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

Store a 16 bit integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GINT32()

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

Store a 32 bit integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GINT64()

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

Store a 64 bit integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_GUINT64()

    #define     GSF_LE_SET_GUINT64(p, dat)

Store a 64 bit unsigned integer value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_FLOAT()

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

Store a float value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value to be stored

### GSF_LE_SET_DOUBLE()

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

Store a double value in memory in little endian order.

`p` : | Pointer to storage
`dat` : | Value 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;

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

`spec` : |
`stamp` : |
Returns : |

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