## GoFormat

GoFormat —

## Synopsis

    enum        GOFormatFamily;
                GOFormatDetails;
                GOFormat;
    GOFormat*   go_format_new_from_XL           (char const *str,
                                                 gboolean delocalize);
    GOFormat*   go_format_new                   (GOFormatFamily family,
                                                 GOFormatDetails const *details);
    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_delocalize        (char const *str);
    char*       go_format_str_as_XL             (char const *str,
                                                 gboolean localized);
    char*       go_format_as_XL                 (GOFormat const *fmt,
                                                 gboolean localized);
    GOFormat*   go_format_ref                   (GOFormat *fmt);
    void        go_format_unref                 (GOFormat *fmt);
    #define     go_format_is_general            (fmt)
    #define     go_format_is_markup             (fmt)
    #define     go_format_is_text               (fmt)
    #define     go_format_is_var_width          (fmt)
    char*       go_format_value                 (GOFormat const *fmt,
                                                 double val);
    void        go_format_value_gstring         (GOFormat const *format,
                                                 GString *res,
                                                 double val,
                                                 int col_width,
                                                 GODateConventions const *date_conv);
    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);
    GOFormatFamily go_format_classify           (GOFormat const *fmt,
                                                 GOFormatDetails *details);
                GOFormatCurrency;
                GONumberFormat;
    void        go_render_number                (GString *result,
                                                 double number,
                                                 GONumberFormat const *info);
    void        go_render_numberl               (GString *result,
                                                 long double number,
                                                 GONumberFormat const *info);
    void        go_set_untranslated_bools       (void);
    charconst * go_setlocale                    (int category,
                                                 char const *val);
    GStringconst * format_get_currency          (gboolean *precedes,
                                                 gboolean *space_sep);
    gboolean    format_month_before_day         (void);
    char        format_get_arg_sep              (void);
    char        format_get_col_sep              (void);
    char        format_get_row_sep              (void);
    GStringconst * format_get_thousand          (void);
    GStringconst * format_get_decimal           (void);
    charconst * format_boolean                  (gboolean b);

## Description

## Details

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

### GOFormatDetails

    typedef struct {
    	gboolean thousands_sep;
    	int	 num_decimals;	/* 0 - 30 */
    	int	 negative_fmt;	/* 0 - 3 */
    	int	 currency_symbol_index;
    	int	 list_element;
    	gboolean date_has_days;
    	gboolean date_has_months;
    	int      fraction_denominator;
    	gboolean simplify_mantissa;
    	int	 exponent_step;
    	gboolean use_markup;
    } GOFormatDetails;

### GOFormat

    typedef struct {
    	int		 ref_count;
    	char		*format;
            GSList		*entries;	/* Of type GOFormatElement. */
    	GOFormatFamily	 family;
    	GOFormatDetails	 family_info;
    	gboolean	 is_var_width;
    	PangoAttrList	*markup;	/* only for GO_FORMAT_MARKUP */
    } GOFormat;

### go_format_new_from_XL ()

    GOFormat*   go_format_new_from_XL           (char const *str,
                                                 gboolean delocalize);

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

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

`str` : |
`delocalize` : |
Returns : |

### go_format_new ()

    GOFormat*   go_format_new                   (GOFormatFamily family,
                                                 GOFormatDetails const *details);

`family` : |
`details` : |
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_delocalize ()

    char*       go_format_str_delocalize        (char const *str);

`str` : |
Returns : |

### go_format_str_as_XL ()

    char*       go_format_str_as_XL             (char const *str,
                                                 gboolean localized);

The caller is responsible for freeing the resulting string.

`str` : | a format string
`localized` : | should the string be in cannonical or locale specific form.
Returns : | a newly allocated string.

### go_format_as_XL ()

    char*       go_format_as_XL                 (GOFormat const *fmt,
                                                 gboolean localized);

`fmt` : | a GOFormat
`localized` : | should the string be in cannonical or locale specific form.
Returns : | a string which the caller is responsible for freeing.

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

    #define	  go_format_is_general(fmt)	((fmt)->family == GO_FORMAT_GENERAL)

`fmt` : |

### go_format_is_markup()

    #define   go_format_is_markup(fmt)	((fmt)->family == GO_FORMAT_MARKUP)

`fmt` : |

### go_format_is_text()

    #define   go_format_is_text(fmt)	((fmt)->family == GO_FORMAT_TEXT)

`fmt` : |

### go_format_is_var_width()

    #define   go_format_is_var_width(fmt)	((fmt)->is_var_width)

`fmt` : |

### go_format_value ()

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

Converts `value` into a string using format specified by `format`.

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

### go_format_value_gstring ()

    void        go_format_value_gstring         (GOFormat const *format,
                                                 GString *res,
                                                 double val,
                                                 int col_width,
                                                 GODateConventions const *date_conv);

`format` : |
`res` : |
`val` : |
`col_width` : |
`date_conv` : |

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

`fmt` : | GOFormat Scans `fmt` for the decimal character and when it finds it, it adds a zero after it to force the rendering of the number with one more digit of decimal precision.
Returns : | NULL if the new format would not change things

### go_format_dec_precision ()

    GOFormat*   go_format_dec_precision         (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_format_toggle_1000sep ()

    GOFormat*   go_format_toggle_1000sep        (GOFormat const *fmt);

`fmt` : |
Returns : |

### go_format_classify ()

    GOFormatFamily go_format_classify           (GOFormat const *fmt,
                                                 GOFormatDetails *details);

`fmt` : |
`details` : |
Returns : |

### GOFormatCurrency

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

### GONumberFormat

    typedef struct {
    	int  right_optional, right_spaces, right_req, right_allowed;
    	int  left_optional, left_spaces, left_req;
    	float scale;
    	gboolean rendered;
    	gboolean decimal_separator_seen;
    	gboolean group_thousands;
    	gboolean has_fraction;

    	gboolean exponent_seen;

    	int exponent_digit_nbr;
    	gboolean exponent_show_sign;
    	gboolean exponent_lower_e;

    	gboolean use_markup;
    } GONumberFormat;

### go_render_number ()

    void        go_render_number                (GString *result,
                                                 double number,
                                                 GONumberFormat const *info);

`result` : |
`number` : |
`info` : |

### go_render_numberl ()

    void        go_render_numberl               (GString *result,
                                                 long double number,
                                                 GONumberFormat const *info);

`result` : |
`number` : |
`info` : |

### go_set_untranslated_bools ()

    void        go_set_untranslated_bools       (void);

Short circuit the current locale so that we can import files and still produce error messages in the current LC_MESSAGE

### go_setlocale ()

    charconst * go_setlocale                    (int category,
                                                 char const *val);

`category` : |
`val` : |
Returns : |

### format_get_currency ()

    GStringconst * format_get_currency          (gboolean *precedes,
                                                 gboolean *space_sep);

Play with the default logic so that things come out nicely for the default case.

`precedes` : | a pointer to a boolean which is set to TRUE if the currency should precede
`space_sep` : | a pointer to a boolean which is set to TRUE if the currency should have a space separating it from the the value
Returns : |

### format_month_before_day ()

    gboolean    format_month_before_day         (void);

Returns : |

### format_get_arg_sep ()

    char        format_get_arg_sep              (void);

Returns : |

### format_get_col_sep ()

    char        format_get_col_sep              (void);

Returns : |

### format_get_row_sep ()

    char        format_get_row_sep              (void);

Returns : |

### format_get_thousand ()

    GStringconst * format_get_thousand          (void);

Returns : |

### format_get_decimal ()

    GStringconst * format_get_decimal           (void);

Returns : |

### format_boolean ()

    charconst * format_boolean                  (gboolean b);

`b` : |
Returns : |