## 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_new             (GDate const *date,
                                                 glong seconds,
                                                 char const *tz);
    GsfTimestamp* gsf_timestamp_new_now         (void);
    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;

### libgsf_minor_version

    extern int libgsf_minor_version;

### libgsf_micro_version

    extern int libgsf_micro_version;

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

`parent_type` :

@\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ 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_finalize` : |
`instance_init` : |

`parent_type` :

@\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ abstract: @\ 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);

`handle` : |

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

`p` : |

### GSF_LE_GET_GUINT64()

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

`p` : |

### GSF_LE_GET_GINT16()

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

`p` : |

### GSF_LE_GET_GUINT8()

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

`p` : |

### GSF_LE_GET_GINT32()

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

`p` : |

### GSF_LE_GET_GUINT16()

    #define     GSF_LE_GET_GUINT16(p)

`p` : |

### GSF_LE_GET_GUINT32()

    #define     GSF_LE_GET_GUINT32(p)

`p` : |

### GSF_LE_GET_GINT64()

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

`p` : |

### gsf_le_get_guint64 ()

    guint64     gsf_le_get_guint64              (void const *p);

`p` : |
Returns : |

### GSF_LE_GET_FLOAT()

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

`p` : |

### gsf_le_get_float ()

    float       gsf_le_get_float                (void const *p);

`p` : |
Returns : |

### GSF_LE_GET_DOUBLE()

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

`p` : |

### gsf_le_get_double ()

    double      gsf_le_get_double               (void const *p);

`p` : |
Returns : |

### GSF_LE_SET_GUINT8()

    #define     GSF_LE_SET_GUINT8(p, dat)

`p` : |
`dat` : |

### GSF_LE_SET_GUINT16()

    #define     GSF_LE_SET_GUINT16(p, dat)

`p` : |
`dat` : |

### GSF_LE_SET_GUINT32()

    #define     GSF_LE_SET_GUINT32(p, dat)

`p` : |
`dat` : |

### GSF_LE_SET_GINT8()

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

`p` : |
`dat` : |

### GSF_LE_SET_GINT16()

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

`p` : |
`dat` : |

### GSF_LE_SET_GINT32()

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

`p` : |
`dat` : |

### GSF_LE_SET_GINT64()

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

`p` : |
`dat` : |

### GSF_LE_SET_GUINT64()

    #define     GSF_LE_SET_GUINT64(p, dat)

`p` : |
`dat` : |

### GSF_LE_SET_FLOAT()

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

`p` : |
`dat` : |

### GSF_LE_SET_DOUBLE()

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

`p` : |
`dat` : |

### gsf_le_set_float ()

    void        gsf_le_set_float                (void *p,
                                                 float f);

`p` : |
`f` : |

### gsf_le_set_double ()

    void        gsf_le_set_double               (void *p,
                                                 double d);

`p` : |
`d` : |

### GsfTimestamp

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

    	guint32	  timet;
    } GsfTimestamp;

### gsf_timestamp_new ()

    GsfTimestamp* gsf_timestamp_new             (GDate const *date,
                                                 glong seconds,
                                                 char const *tz);

`date` : |
`seconds` : |
`tz` : |
Returns : |

### gsf_timestamp_new_now ()

    GsfTimestamp* gsf_timestamp_new_now         (void);

Returns : |

### gsf_timestamp_copy ()

    GsfTimestamp* gsf_timestamp_copy            (GsfTimestamp const *stamp);

`stamp` : |
Returns : |

### gsf_timestamp_free ()

    void        gsf_timestamp_free              (GsfTimestamp *stamp);

`stamp` : |

### gsf_timestamp_as_string ()

    char*       gsf_timestamp_as_string         (GsfTimestamp const *stamp);

`stamp` : |
Returns : |

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

`a` : |
`b` : |
Returns : |

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