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_hour ()
gboolean	go_format_has_minute ()
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);

Returns

go_format_allow_ee_markup ()

gboolean
go_format_allow_ee_markup (void);

Returns

go_format_allow_pi_slash ()

gboolean
go_format_allow_pi_slash (void);

Returns

go_format_allow_si ()

gboolean
go_format_allow_si (void);

Returns

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

go_format_default_date ()

GOFormat *
go_format_default_date (void);

Returns

go_format_default_date_time ()

GOFormat *
go_format_default_date_time (void);

Returns

go_format_default_money ()

GOFormat *
go_format_default_money (void);

Returns

go_format_default_percentage ()

GOFormat *
go_format_default_percentage (void);

Returns

go_format_default_time ()

GOFormat *
go_format_default_time (void);

Returns

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

Returns

go_format_empty ()

GOFormat *
go_format_empty (void);

Returns

go_format_eq ()

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

Returns

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

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

go_format_get_family ()

GOFormatFamily
go_format_get_family (GOFormat const *fmt);

Returns

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

Returns

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_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 Returns FALSE otherwise.

go_format_is_simple ()

gboolean
go_format_is_simple (GOFormat const *fmt);

Returns

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 Returns 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. Returns FALSE otherwise.

go_format_locale_currency ()

GOFormatCurrency const *
go_format_locale_currency (void);

Returns

go_format_measure_pango ()

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

Returns

go_format_measure_strlen ()

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

Returns

go_format_measure_zero ()

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

Returns

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

Returns

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

Returns

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

Returns

go_format_palette_color_of_index ()

GOColor
go_format_palette_color_of_index (int i);

Returns

go_format_palette_index_from_color ()

int
go_format_palette_index_from_color (GOColor c);

Parameters

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

Returns

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

Returns

go_format_specializel ()

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

Returns

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

Returns

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

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

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,
                   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 pango units. -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 pango units. -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.