go-format

## go-format go-format |

## Synopsis

                        GOFormat;
    enum                GOFormatFamily;
    enum                GOFormatNumberError;
    int                 (*GOFormatMeasure)                  (const GString *str,
                                                             PangoLayout *layout);
    void                go_number_format_init               (void);
    void                go_number_format_shutdown           (void);
    int                 go_format_measure_zero              (const GString *str,
                                                             PangoLayout *layout);
    int                 go_format_measure_pango             (const GString *str,
                                                             PangoLayout *layout);
    int                 go_format_measure_strlen            (const GString *str,
                                                             PangoLayout *layout);
    GOFormat*           go_format_empty                     (void);
    gboolean            go_format_has_hour                  (GOFormat const *fmt);
    int                 go_format_month_before_day          (GOFormat const *fmt);
    GtkWidget*          go_format_sel_new_full              (gboolean use_markup);
    const GOFormat*     go_format_specialize                (GOFormat const *fmt,
                                                             double val,
                                                             char type,
                                                             gboolean *inhibit_minus);
    const GOFormat*     go_format_specializel               (GOFormat const *fmt,
                                                             long double val,
                                                             char type,
                                                             gboolean *inhibit_minus);
    GOFormat*           go_format_new_from_XL               (char const *str);
    GOFormat*           go_format_new_markup                (PangoAttrList *markup,
                                                             gboolean add_ref);
    GOFormat*           go_format_general                   (void);
    GOFormat*           go_format_default_date              (void);
    GOFormat*           go_format_default_time              (void);
    GOFormat*           go_format_default_date_time         (void);
    GOFormat*           go_format_default_percentage        (void);
    GOFormat*           go_format_default_money             (void);
    char*               go_format_str_localize              (char const *str);
    char*               go_format_str_delocalize            (char const *str);
    const char*         go_format_as_XL                     (GOFormat const *fmt);
    GOFormat*           go_format_ref                       (GOFormat *fmt);
    void                go_format_unref                     (GOFormat *fmt);
    gboolean            go_format_is_general                (GOFormat const *fmt);
    gboolean            go_format_is_markup                 (GOFormat const *fmt);
    gboolean            go_format_is_text                   (GOFormat const *fmt);
    gboolean            go_format_is_var_width              (GOFormat const *fmt);
    int                 go_format_is_date                   (GOFormat const *fmt);
    GOFormatFamily      go_format_get_family                (GOFormat const *fmt);
    const PangoAttrList* go_format_get_markup               (GOFormat const *fmt);
    gboolean            go_format_is_simple                 (GOFormat const *fmt);
    GOFormatNumberError go_format_value_gstring             (PangoLayout *layout,
                                                             GString *str,
                                                             const GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             GOFormat const *fmt,
                                                             double val,
                                                             char type,
                                                             const char *sval,
                                                             GOColor *go_color,
                                                             int col_width,
                                                             GODateConventions const *date_conv,
                                                             gboolean unicode_minus);
    char*               go_format_value                     (GOFormat const *fmt,
                                                             double val);
    GOFormatNumberError go_format_value_gstringl            (PangoLayout *layout,
                                                             GString *str,
                                                             const GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             GOFormat const *fmt,
                                                             long double val,
                                                             char type,
                                                             const char *sval,
                                                             GOColor *go_color,
                                                             int col_width,
                                                             GODateConventions const *date_conv,
                                                             gboolean unicode_minus);
    char*               go_format_valuel                    (GOFormat const *fmt,
                                                             long double val);
    gboolean            go_format_eq                        (GOFormat const *a,
                                                             GOFormat const *b);
    GOFormat*           go_format_inc_precision             (GOFormat const *fmt);
    GOFormat*           go_format_dec_precision             (GOFormat const *fmt);
    GOFormat*           go_format_toggle_1000sep            (GOFormat const *fmt);
    void                go_render_general                   (PangoLayout *layout,
                                                             GString *str,
                                                             GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             double val,
                                                             int col_width,
                                                             gboolean unicode_minus);
    void                go_render_generall                  (PangoLayout *layout,
                                                             GString *str,
                                                             GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             long double val,
                                                             int col_width,
                                                             gboolean unicode_minus);
                        GOFormatCurrency;
    void                go_currency_date_format_init        (void);
    void                go_currency_date_format_shutdown    (void);

## Description

## Details

### GOFormat

    typedef struct _GOFormat GOFormat;

### enum GOFormatFamily

    typedef enum {
    	GO_FORMAT_UNKNOWN	= -1,

    	GO_FORMAT_GENERAL	= 0,
    	GO_FORMAT_NUMBER	= 1,
    	GO_FORMAT_CURRENCY	= 2,
    	GO_FORMAT_ACCOUNTING	= 3,
    	GO_FORMAT_DATE		= 4,
    	GO_FORMAT_TIME		= 5,
    	GO_FORMAT_PERCENTAGE	= 6,
    	GO_FORMAT_FRACTION	= 7,
    	GO_FORMAT_SCIENTIFIC	= 8,
    	GO_FORMAT_TEXT		= 9,
    	GO_FORMAT_SPECIAL	= 10,

    	GO_FORMAT_MARKUP	= 11	/* Internal use only */
    } GOFormatFamily;

### enum GOFormatNumberError

    typedef enum {
    	GO_FORMAT_NUMBER_OK = 0,
    	GO_FORMAT_NUMBER_INVALID_FORMAT,
    	GO_FORMAT_NUMBER_DATE_ERROR
    } GOFormatNumberError;

### GOFormatMeasure ()

    int                 (*GOFormatMeasure)                  (const GString *str,
                                                             PangoLayout *layout);

`str` : |
`layout` : |
Returns : |

### go_number_format_init ()

    void                go_number_format_init               (void);

### go_number_format_shutdown ()

    void                go_number_format_shutdown           (void);

### go_format_measure_zero ()

    int                 go_format_measure_zero              (const GString *str,
                                                             PangoLayout *layout);

`str` : |
`layout` : |
Returns : |

### go_format_measure_pango ()

    int                 go_format_measure_pango             (const GString *str,
                                                             PangoLayout *layout);

`str` : |
`layout` : |
Returns : |

### go_format_measure_strlen ()

    int                 go_format_measure_strlen            (const GString *str,
                                                             PangoLayout *layout);

`str` : |
`layout` : |
Returns : |

### go_format_empty ()

    GOFormat*           go_format_empty                     (void);

Returns : |

### go_format_has_hour ()

    gboolean            go_format_has_hour                  (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if format is a number format with an hour specifier FALSE otherwise.

### go_format_month_before_day ()

    int                 go_format_month_before_day          (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | 0, if format is a date format with day and month in that order 1, if format is a date format with month and day in that order, unless 2, if format is a date with year before month before day -1, otherwise.

### go_format_sel_new_full ()

    GtkWidget*          go_format_sel_new_full              (gboolean use_markup);

Creates a format selector widget, with general format selected by default. When `use_markup` is set to `TRUE`, it shows additional widgets for editing properties of formats using pango markup (e.g. scientific format with superscripted exponent).

`use_markup` : | enable formats using pango markup
Returns : | a format selector widget.

### go_format_specialize ()

    const GOFormat*     go_format_specialize                (GOFormat const *fmt,
                                                             double val,
                                                             char type,
                                                             gboolean *inhibit_minus);

`fmt` : |
`val` : |
`type` : |
`inhibit_minus` : |
Returns : |

### go_format_specializel ()

    const GOFormat*     go_format_specializel               (GOFormat const *fmt,
                                                             long double val,
                                                             char type,
                                                             gboolean *inhibit_minus);

`fmt` : |
`val` : |
`type` : |
`inhibit_minus` : |
Returns : |

### go_format_new_from_XL ()

    GOFormat*           go_format_new_from_XL               (char const *str);

Looks up and potentially creates a GOFormat from the supplied string in XL format.

`descriptor_string`: XL descriptor in UTF-8 encoding.

`str` : |
Returns : |

### go_format_new_markup ()

    GOFormat*           go_format_new_markup                (PangoAttrList *markup,
                                                             gboolean add_ref);

Create a MARKUP format. If `add_ref` is FALSE absorb the reference to `markup`, otherwise add a reference.

`markup` : | PangoAttrList
`add_ref` : |
Returns : |

### go_format_general ()

    GOFormat*           go_format_general                   (void);

Returns : |

### go_format_default_date ()

    GOFormat*           go_format_default_date              (void);

Returns : |

### go_format_default_time ()

    GOFormat*           go_format_default_time              (void);

Returns : |

### go_format_default_date_time ()

    GOFormat*           go_format_default_date_time         (void);

Returns : |

### go_format_default_percentage ()

    GOFormat*           go_format_default_percentage        (void);

Returns : |

### go_format_default_money ()

    GOFormat*           go_format_default_money             (void);

Returns : |

### go_format_str_localize ()

    char*               go_format_str_localize              (char const *str);

`str` : |
Returns : |

### go_format_str_delocalize ()

    char*               go_format_str_delocalize            (char const *str);

`str` : |
Returns : |

### go_format_as_XL ()

    const char*         go_format_as_XL                     (GOFormat const *fmt);

`fmt` : | a GOFormat
Returns : | the XL style format strint.

### go_format_ref ()

    GOFormat*           go_format_ref                       (GOFormat *fmt);

Adds a reference to a GOFormat.

`fmt` : | a GOFormat
Returns : |

### go_format_unref ()

    void                go_format_unref                     (GOFormat *fmt);

Removes a reference to `fmt`, freeing when it goes to zero.

`fmt` : | a GOFormat

### go_format_is_general ()

    gboolean            go_format_is_general                (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if the format is "General", possibly with condition, color, and/or locale. ("xGeneral" is thus not considered to be General for the purpose of this function.) Returns FALSE otherwise.

### go_format_is_markup ()

    gboolean            go_format_is_markup                 (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if the format is a markup format Returns FALSE otherwise.

### go_format_is_text ()

    gboolean            go_format_is_text                   (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if the format is a text format Returns FALSE otherwise.

### go_format_is_var_width ()

    gboolean            go_format_is_var_width              (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if the format is variable width, i.e., can stretch. Returns FALSE otherwise.

### go_format_is_date ()

    int                 go_format_is_date                   (GOFormat const *fmt);

`fmt` : | Format to query
Returns : | TRUE if the format is a date format. Returns FALSE if the format is not a date format. Returns -1 if the format is inconsistent.

### go_format_get_family ()

    GOFormatFamily      go_format_get_family                (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_format_get_markup ()

    const PangoAttrList* go_format_get_markup               (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_format_is_simple ()

    gboolean            go_format_is_simple                 (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_format_value_gstring ()

    GOFormatNumberError go_format_value_gstring             (PangoLayout *layout,
                                                             GString *str,
                                                             const GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             GOFormat const *fmt,
                                                             double val,
                                                             char type,
                                                             const char *sval,
                                                             GOColor *go_color,
                                                             int col_width,
                                                             GODateConventions const *date_conv,
                                                             gboolean unicode_minus);

`layout` : |
`str` : |
`measure` : |
`metrics` : |
`fmt` : |
`val` : |
`type` : |
`sval` : |
`go_color` : |
`col_width` : |
`date_conv` : |
`unicode_minus` : |
Returns : |

### go_format_value ()

    char*               go_format_value                     (GOFormat const *fmt,
                                                             double val);

Converts `val` into a string using format specified by `fmt`.

`fmt` : | a GOFormat
`val` : | value to format
Returns : | a newly allocated string containing formated value.

### go_format_value_gstringl ()

    GOFormatNumberError go_format_value_gstringl            (PangoLayout *layout,
                                                             GString *str,
                                                             const GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             GOFormat const *fmt,
                                                             long double val,
                                                             char type,
                                                             const char *sval,
                                                             GOColor *go_color,
                                                             int col_width,
                                                             GODateConventions const *date_conv,
                                                             gboolean unicode_minus);

`layout` : |
`str` : |
`measure` : |
`metrics` : |
`fmt` : |
`val` : |
`type` : |
`sval` : |
`go_color` : |
`col_width` : |
`date_conv` : |
`unicode_minus` : |
Returns : |

### go_format_valuel ()

    char*               go_format_valuel                    (GOFormat const *fmt,
                                                             long double val);

`fmt` : |
`val` : |
Returns : |

### go_format_eq ()

    gboolean            go_format_eq                        (GOFormat const *a,
                                                             GOFormat const *b);

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

### go_format_inc_precision ()

    GOFormat*           go_format_inc_precision             (GOFormat const *fmt);

Increaseds the displayed precision for `fmt` by one digit.

`fmt` : | GOFormat
Returns : | NULL if the new format would not change things

### go_format_dec_precision ()

    GOFormat*           go_format_dec_precision             (GOFormat const *fmt);

Decreases the displayed precision for `fmt` by one digit.

`fmt` : | GOFormat
Returns : | NULL if the new format would not change things

### go_format_toggle_1000sep ()

    GOFormat*           go_format_toggle_1000sep            (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_render_general ()

    void                go_render_general                   (PangoLayout *layout,
                                                             GString *str,
                                                             GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             double val,
                                                             int col_width,
                                                             gboolean unicode_minus);

`layout` : |
`str` : |
`measure` : |
`metrics` : |
`val` : |
`col_width` : |
`unicode_minus` : |

### go_render_generall ()

    void                go_render_generall                  (PangoLayout *layout,
                                                             GString *str,
                                                             GOFormatMeasure measure,
                                                             const GOFontMetrics *metrics,
                                                             long double val,
                                                             int col_width,
                                                             gboolean unicode_minus);

`layout` : |
`str` : |
`measure` : |
`metrics` : |
`val` : |
`col_width` : |
`unicode_minus` : |

### GOFormatCurrency

    typedef struct {
    	gchar const *symbol;
    	gchar const *description;
    	gboolean precedes;
    	gboolean has_space;
    } GOFormatCurrency;

### go_currency_date_format_init ()

    void                go_currency_date_format_init        (void);

### go_currency_date_format_shutdown ()

    void                go_currency_date_format_shutdown    (void);