GOFormat: GOffice Reference Manual

## GOFormat GOFormat |

## Functions

int | (*GOFormatMeasure) ()
gboolean | go_format_allow_ee_markup ()
gboolean | go_format_allow_pi_slash ()
gboolean | go_format_allow_si ()
const char * | go_format_as_XL ()
GOFormat * | go_format_dec_precision ()
GOFormat * | go_format_default_accounting ()
GOFormat * | go_format_default_date ()
GOFormat * | go_format_default_date_time ()
GOFormat * | go_format_default_money ()
GOFormat * | go_format_default_percentage ()
GOFormat * | go_format_default_time ()
void | go_format_details_finalize ()
void | go_format_details_free ()
void | go_format_details_init ()
GOFormatDetails * | go_format_details_new ()
GOFormat * | go_format_empty ()
gboolean | go_format_eq ()
void | go_format_foreach ()
GOFormat * | go_format_general ()
void | go_format_generate_number_str ()
void | go_format_generate_str ()
void | go_format_get_details ()
GOFormatFamily | go_format_get_family ()
GOFormatMagic | go_format_get_magic ()
const PangoAttrList * | go_format_get_markup ()
gboolean | go_format_has_day ()
gboolean | go_format_has_hour ()
gboolean | go_format_has_minute ()
gboolean | go_format_has_month ()
gboolean | go_format_has_year ()
GOFormat * | go_format_inc_precision ()
int | go_format_is_date ()
gboolean | go_format_is_general ()
gboolean | go_format_is_invalid ()
gboolean | go_format_is_markup ()
gboolean | go_format_is_simple ()
gboolean | go_format_is_text ()
int | go_format_is_time ()
gboolean | go_format_is_var_width ()
GOFormatCurrency const * | go_format_locale_currency ()
int | go_format_measure_pango ()
int | go_format_measure_strlen ()
int | go_format_measure_zero ()
int | go_format_month_before_day ()
GOFormat * | go_format_new_from_XL ()
GOFormat * | go_format_new_magic ()
GOFormat * | go_format_new_markup ()
char * | go_format_odf_style_map ()
gboolean | go_format_output_to_odf ()
GOColor | go_format_palette_color_of_index ()
int | go_format_palette_index_from_color ()
char * | go_format_palette_name_of_index ()
GOFormat * | go_format_ref ()
const GOFormat * | go_format_specialize ()
const GOFormat * | go_format_specializel ()
char * | go_format_str_delocalize ()
char * | go_format_str_localize ()
GOFormat * | go_format_toggle_1000sep ()
void | go_format_unref ()
char * | go_format_value ()
GOFormatNumberError | go_format_value_gstring ()
GOFormatNumberError | go_format_value_gstringl ()
char * | go_format_valuel ()
void | go_render_general ()
void | go_render_generall ()

## Types and Values

#define | GO_SUBSCRIPT_RISE
#define | GO_SUBSCRIPT_SCALE
#define | GO_SUPERSCRIPT_RISE
#define | GO_SUPERSCRIPT_SCALE
| GOFormat
| GOFormatCurrency
| GOFormatDetails
enum | GOFormatFamily
enum | GOFormatMagic
enum | GOFormatNumberError

## Object Hierarchy

        GBoxed
        ├── GOFormat
        ├── GOFormatCurrency
        ╰── GOFormatDetails

## Description

## Functions

### GOFormatMeasure ()

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

### go_format_allow_ee_markup ()

    gboolean
    go_format_allow_ee_markup (void);

### go_format_allow_pi_slash ()

    gboolean
    go_format_allow_pi_slash (void);

### go_format_allow_si ()

    gboolean
    go_format_allow_si (void);

### go_format_as_XL ()

    const char *
    go_format_as_XL (GOFormat const *fmt);

#### Parameters

fmt | a GOFormat |

#### Returns

the XL style format strint.

### go_format_dec_precision ()

    GOFormat *
    go_format_dec_precision (GOFormat const *fmt);

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

#### Parameters

fmt | GOFormat |

#### Returns

NULL if the new format would not change things

### go_format_default_accounting ()

    GOFormat *
    go_format_default_accounting (void);

#### Returns

the default accounting format.

[transfer none]

### go_format_default_date ()

    GOFormat *
    go_format_default_date (void);

#### Returns

the default date format.

[transfer none]

### go_format_default_date_time ()

    GOFormat *
    go_format_default_date_time (void);

#### Returns

the default date-and-time format.

[transfer none]

### go_format_default_money ()

    GOFormat *
    go_format_default_money (void);

#### Returns

the default monetary format.

[transfer none]

### go_format_default_percentage ()

    GOFormat *
    go_format_default_percentage (void);

#### Returns

the default percentage format.

[transfer none]

### go_format_default_time ()

    GOFormat *
    go_format_default_time (void);

#### Returns

the default time format.

[transfer none]

### go_format_details_finalize ()

    void
    go_format_details_finalize (GOFormatDetails *details);

### go_format_details_free ()

    void
    go_format_details_free (GOFormatDetails *details);

### go_format_details_init ()

    void
    go_format_details_init (GOFormatDetails *details,
                            GOFormatFamily family);

### go_format_details_new ()

    GOFormatDetails *
    go_format_details_new (GOFormatFamily family);

### go_format_empty ()

    GOFormat *
    go_format_empty (void);

#### Returns

the empty format.

[transfer none]

### go_format_eq ()

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

### go_format_foreach ()

    void
    go_format_foreach (GHFunc func,
                       gpointer user_data);

Executes `func` for each registered GOFormat

#### Parameters

func | function to execute for each known format. | [scope call]
user_data | user data for `func` |

### go_format_general ()

    GOFormat *
    go_format_general (void);

#### Returns

the general format.

[transfer none]

### go_format_generate_number_str ()

    void
    go_format_generate_number_str (GString *dst,
                                   int min_digits,
                                   int num_decimals,
                                   gboolean thousands_sep,
                                   gboolean negative_red,
                                   gboolean negative_paren,
                                   const char *prefix,
                                   const char *postfix);

Generates a format string for a number format with the given parameters and appends it to `dst` .

#### Parameters

dst | GString to append format string to. |
min_digits | minimum number of digits before decimal separator. |
num_decimals | number of decimals |
thousands_sep | if true, use a thousands separator. |
negative_red | if true, make negative values red. |
negative_paren | if true, enclose negative values in parentheses. |
prefix | optional string to place before number part of the format |
postfix | optional string to place after number part of the format |

### go_format_generate_str ()

    void
    go_format_generate_str (GString *dst,
                            GOFormatDetails const *details);

### go_format_get_details ()

    void
    go_format_get_details (GOFormat const *fmt,
                           GOFormatDetails *dst,
                           gboolean *exact);

#### Parameters

fmt | Format to quert |
dst | GOFormatDetails. | [out]
exact | whether `dst` describes `fmt` exactly. | [out][optional]

### go_format_get_family ()

    GOFormatFamily
    go_format_get_family (GOFormat const *fmt);

### go_format_get_magic ()

    GOFormatMagic
    go_format_get_magic (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

a non-zero magic code for certain formats, such as system date.

### go_format_get_markup ()

    const PangoAttrList *
    go_format_get_markup (GOFormat const *fmt);

### go_format_has_day ()

    gboolean
    go_format_has_day (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if format is a number format with a day-of-month specifier FALSE otherwise.

### go_format_has_hour ()

    gboolean
    go_format_has_hour (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if format is a number format with an hour specifier FALSE otherwise.

### go_format_has_minute ()

    gboolean
    go_format_has_minute (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if format is a number format with a minute specifier FALSE otherwise.

### go_format_has_month ()

    gboolean
    go_format_has_month (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if format is a number format with a year specifier FALSE otherwise.

### go_format_has_year ()

    gboolean
    go_format_has_year (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if format is a number format with a year specifier FALSE otherwise.

### go_format_inc_precision ()

    GOFormat *
    go_format_inc_precision (GOFormat const *fmt);

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

#### Parameters

fmt | GOFormat |

#### Returns

NULL if the new format would not change things

### go_format_is_date ()

    int
    go_format_is_date (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

+2 if the format is a date format with time +1 if the format is any other date format. 0 if the format is not a date format. -1 if the format is inconsistent.

### go_format_is_general ()

    gboolean
    go_format_is_general (GOFormat const *fmt);

#### Parameters

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

    gboolean
    go_format_is_invalid (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

TRUE if, and if only, the format is invalid

### go_format_is_markup ()

    gboolean
    go_format_is_markup (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

`TRUE` if the format is a markup format and `FALSE` otherwise.

### go_format_is_simple ()

    gboolean
    go_format_is_simple (GOFormat const *fmt);

### go_format_is_text ()

    gboolean
    go_format_is_text (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

`TRUE` if the format is a text format and `FALSE` otherwise.

### go_format_is_time ()

    int
    go_format_is_time (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

+2 if the format is a time format with elapsed hour/minute/second +1 if the format is any other time format 0 if the format is not a time format -1 if the format is inconsistent.

### go_format_is_var_width ()

    gboolean
    go_format_is_var_width (GOFormat const *fmt);

#### Parameters

fmt | Format to query |

#### Returns

`TRUE` if the format is variable width, i.e., can stretch.

### go_format_locale_currency ()

    GOFormatCurrency const *
    go_format_locale_currency (void);

#### Returns

The GOFormatCurrency matches the current locale.

[transfer none]

### go_format_measure_pango ()

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

### go_format_measure_strlen ()

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

### go_format_measure_zero ()

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

### go_format_month_before_day ()

    int
    go_format_month_before_day (GOFormat const *fmt);

#### Parameters

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

    GOFormat *
    go_format_new_from_XL (char const *str);

#### Parameters

str | XL descriptor in UTF-8 encoding. |

#### Returns

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

### go_format_new_magic ()

    GOFormat *
    go_format_new_magic (GOFormatMagic m);

### go_format_new_markup ()

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

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

#### Parameters

markup | PangoAttrList |
add_ref | boolean |

#### Returns

A new format.

### go_format_odf_style_map ()

    char *
    go_format_odf_style_map (GOFormat const *fmt,
                             int cond_part);

### go_format_output_to_odf ()

    gboolean
    go_format_output_to_odf (GsfXMLOut *xout,
                             GOFormat const *fmt,
                             int cond_part,
                             char const *name,
                             gboolean with_extension);

### go_format_palette_color_of_index ()

    GOColor
    go_format_palette_color_of_index (int i);

### go_format_palette_index_from_color ()

    int
    go_format_palette_index_from_color (GOColor c);

#### Parameters

c | color |

#### Returns

the index of the color closest to the argument color in some sense.

### go_format_palette_name_of_index ()

    char *
    go_format_palette_name_of_index (int i);

### go_format_ref ()

    GOFormat *
    go_format_ref (GOFormat const *fmt);

Adds a reference to a GOFormat.

#### Parameters

fmt | a GOFormat |

#### Returns

`gf`

### go_format_specialize ()

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

#### Parameters

fmt | the format to specialize |
val | the value to use |
type | the type of value; 'F' for numeric, 'B' for boolean, 'S' for string. |
inhibit_minus | set to `TRUE` if the format dictates that a minus should be inhibited when rendering negative values. | [out]

#### Returns

`fmt` format, presumably a conditional format, specialized to `value` of `type` .

[transfer none]

### go_format_specializel ()

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

#### Parameters

fmt | the format to specialize |
val | the value to use |
type | the type of value; 'F' for numeric, 'B' for boolean, 'S' for string. |
inhibit_minus | set to `TRUE` if the format dictates that a minus should be inhibited when rendering negative values. | [out]

#### Returns

`fmt` format, presumably a conditional format, specialized to `value` of `type` .

[transfer none]

### go_format_str_delocalize ()

    char *
    go_format_str_delocalize (char const *str);

De-localizes the given format string, i.e., changes locale's decimal separators to dots and performs other such transformations.

#### Parameters

str | A *valid* localized format string |

#### Returns

a non-local format string, or `NULL` if the format was not valid.

### go_format_str_localize ()

    char *
    go_format_str_localize (char const *str);

Localizes the given format string, i.e., changes decimal dots to the locale's notion of that and performs other such transformations.

#### Parameters

str | A *valid* format string |

#### Returns

a localized format string, or `NULL` if the format was not valid.

### go_format_toggle_1000sep ()

    GOFormat *
    go_format_toggle_1000sep (GOFormat const *fmt);

### go_format_unref ()

    void
    go_format_unref (GOFormat const *fmt);

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

#### Parameters

fmt | a GOFormat. | [transfer full][nullable]

### go_format_value ()

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

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

#### Parameters

fmt | a GOFormat |
val | value to format |

#### Returns

a newly allocated string containing formated value.

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

Render a floating-point value into `layout` in such a way that the layouting width does not needlessly exceed `col_width` . Optionally use unicode minus instead of hyphen.

#### Parameters

layout | Optional PangoLayout, probably preseeded with font attribute. |
str | a GString to store (not append!) the resulting string in. |
measure | Function to measure width of string/layout. | [scope call]
metrics | Font metrics corresponding to `mesaure` . |
fmt | GOFormat |
val | floating-point value. Must be finite. |
type | a format character |
sval | a string to append to `str` after `val` |
go_color | a color to rende |
col_width | intended max width of layout in pango units. -1 means no restriction. |
date_conv | GODateConventions |
unicode_minus | Use unicode minuses, not hyphens. |

#### Returns

a GOFormatNumberError

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

Render a floating-point value into `layout` in such a way that the layouting width does not needlessly exceed `col_width` . Optionally use unicode minus instead of hyphen.

#### Parameters

layout | Optional PangoLayout, probably preseeded with font attribute. |
str | a GString to store (not append!) the resulting string in. |
measure | Function to measure width of string/layout. | [scope call]
metrics | Font metrics corresponding to `mesaure` . |
fmt | GOFormat |
val | floating-point value. Must be finite. |
type | a format character |
sval | a string to append to `str` after `val` |
go_color | a color to rende |
col_width | intended max width of layout in pango units. -1 means no restriction. |
date_conv | GODateConventions |
unicode_minus | Use unicode minuses, not hyphens. |

#### Returns

a GOFormatNumberError

### go_format_valuel ()

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

### go_render_general ()

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

Render a floating-point value into `layout` in such a way that the layouting width does not needlessly exceed `col_width` . Optionally use unicode minus instead of hyphen.

#### Parameters

layout | Optional PangoLayout, probably preseeded with font attribute. |
str | a GString to store (not append!) the resulting string in. |
measure | Function to measure width of string/layout. | [scope call]
metrics | Font metrics corresponding to `measure` . |
val | floating-point value. Must be finite. |
col_width | intended max width of layout in the units that `measure` uses. A width of -1 means no restriction. |
unicode_minus | Use unicode minuses, not hyphens. |
numeral_shape | numeral shape identifier. |
custom_shape_flags | flags for using `numeral_shape` . |

### 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,
                        guint numeral_shape,
                        guint custom_shape_flags);

Render a floating-point value into `layout` in such a way that the layouting width does not needlessly exceed `col_width` . Optionally use unicode minus instead of hyphen.

#### Parameters

layout | Optional PangoLayout, probably preseeded with font attribute. |
str | a GString to store (not append!) the resulting string in. |
measure | Function to measure width of string/layout. | [scope call]
metrics | Font metrics corresponding to `mesaure` . |
val | floating-point value. Must be finite. |
col_width | intended max width of layout in the units that `measure` uses. A width of -1 means no restriction. |
unicode_minus | Use unicode minuses, not hyphens. |
numeral_shape | numeral shape identifier. |
custom_shape_flags | flags for using `numeral_shape` . |

## Types and Values

### GO_SUBSCRIPT_RISE

    #define GO_SUBSCRIPT_RISE -5000

### GO_SUBSCRIPT_SCALE

    #define GO_SUBSCRIPT_SCALE PANGO_SCALE_SMALL

### GO_SUPERSCRIPT_RISE

    #define GO_SUPERSCRIPT_RISE 5000

### GO_SUPERSCRIPT_SCALE

    #define GO_SUPERSCRIPT_SCALE PANGO_SCALE_SMALL

### GOFormat

    typedef struct _GOFormat GOFormat;

### GOFormatCurrency

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

#### Members

gchar const *`symbol`; | currency symbol. |
gchar const *`description`; | description. |
gboolean `precedes`; | whether the symbol precedes the amount. |
gboolean `has_space`; | whether to add a space between amount and symbol. |

### GOFormatDetails

    typedef struct {
    	GOFormatFamily family;
    	GOFormatMagic magic;

    	/* NUMBER, SCIENTIFIC, CURRENCY, ACCOUNTING, FRACTION, PERCENTAGE: */
    	int min_digits;
    	int num_decimals;

    	/* NUMBER, CURRENCY, ACCOUNTING, PERCENTAGE: */
    	gboolean thousands_sep;

    	/* NUMBER, CURRENCY, ACCOUNTING, PERCENTAGE: */
    	gboolean negative_red;
    	gboolean negative_paren;

    	/* CURRENCY, ACCOUNTING: */
    	GOFormatCurrency const *currency;

    	/* CURRENCY: */
    	gboolean force_quoted;

    	/* SCIENTIFIC: */
    	int exponent_step;
    	int exponent_digits;
    	gboolean exponent_sign_forced;
    	gboolean use_markup;
    	gboolean simplify_mantissa;
    	gboolean append_SI;
    	gchar *appended_SI_unit;
    	int scale;

    	/* FRACTION: */
    	gboolean automatic_denominator;
    	gboolean split_fraction;
    	gboolean pi_scale;
    	int numerator_min_digits;
    	int denominator_min_digits;
    	int denominator_max_digits;
    	int denominator;
    } GOFormatDetails;

#### Members

GOFormatFamily `family`; | GOFormatFamily. |
GOFormatMagic `magic`; | GOFormatMagic. |
int `min_digits`; | minimum digits number. |
int `num_decimals`; | decimals number. |
gboolean `thousands_sep`; | thousands separator. |
gboolean `negative_red`; | display negative number using red ink. |
gboolean `negative_paren`; | uses parenthersis around negative numbers. |
GOFormatCurrency const *`currency`; | GOFormatCurrency. |
gboolean `force_quoted`; | force quotes use. |
int `exponent_step`; | steps between allowed exponents in scientific notation. |
int `exponent_digits`; | digits number in exponent. |
gboolean `exponent_sign_forced`; | whether the sign in the exponent is always shown. |
gboolean `use_markup`; | whether to use a markup. |
gboolean `simplify_mantissa`; | simplify the mantissa. |
gboolean `append_SI`; | append an SI unit. |
gchar *`appended_SI_unit`; | the SI unit to append. |
int `scale`; | scale. |
gboolean `automatic_denominator`; | use an automatic denominator for fractions. |
gboolean `split_fraction`; | split the fraction. |
gboolean `pi_scale`; | use multiples of pi for fractions, e.g. 1/2*pi. |
int `numerator_min_digits`; | minimum digits number for the numerator. |
int `denominator_min_digits`; | minimum digits number for the denominator. |
int `denominator_max_digits`; | minimum digits number for the denominator. |
int `denominator`; | fixed denominator. |

### enum GOFormatFamily

#### Members

GO_FORMAT_UNKNOWN | unknown ,should not occur. |
GO_FORMAT_GENERAL | general. |
GO_FORMAT_NUMBER | number. |
GO_FORMAT_CURRENCY | currency. |
GO_FORMAT_ACCOUNTING | accounting. |
GO_FORMAT_DATE | date. |
GO_FORMAT_TIME | tipe. |
GO_FORMAT_PERCENTAGE | percentage. |
GO_FORMAT_FRACTION | fraction. |
GO_FORMAT_SCIENTIFIC | scientific. |
GO_FORMAT_TEXT | text. |
GO_FORMAT_SPECIAL | custom. |

### enum GOFormatMagic

#### Members

GO_FORMAT_MAGIC_NONE | none. |
GO_FORMAT_MAGIC_LONG_DATE | long date (Official). |
GO_FORMAT_MAGIC_MEDIUM_DATE | medium date. |
GO_FORMAT_MAGIC_SHORT_DATE | short date. |
GO_FORMAT_MAGIC_SHORT_DATETIME | short date with time. |
GO_FORMAT_MAGIC_LONG_TIME | long time (Official). |
GO_FORMAT_MAGIC_MEDIUM_TIME | medium time. |
GO_FORMAT_MAGIC_SHORT_TIME | short time. |

### enum GOFormatNumberError

#### Members

GO_FORMAT_NUMBER_OK | no error. |
GO_FORMAT_NUMBER_INVALID_FORMAT | invalid format. |
GO_FORMAT_NUMBER_DATE_ERROR | date error. |