The Format module represents the base module for all formats.

Required Header

#include <utils_i18n.h>

Overview

The Format module specifies the protocol for classes which convert other objects or values,
such as numeric values and dates, and their string representations.
In some cases these representations may be localized or contain localized characters or strings.
Please note, that there is no function for creating an i18n_format_h object as this module uses a mechanism similar to inheritance, known in object-oriented languages. All of the functions that take the i18n_format_h handle as a parameter can actually take the handle to the more specific format object related to the corresponding derived classes. Please also note that at this point the only derived class that is supported by the base-utils i18n module is the ICU's MeasureFormat class, which is why it is possible to use handles of type i18n_measure_format_h in place of the parameters of type i18n_format_h.

Functions
int	i18n_format_destroy (i18n_format_h format)
	Destroys the format object.
int	i18n_format_clone (i18n_format_h format, i18n_format_h *clone)
	Creates a polymorphic clone of the given format object.
int	i18n_format_format (i18n_format_h format, i18n_formattable_h formattable, char **append_to)
	Formats an object to produce a string.
int	i18n_format_format_with_field_position (i18n_format_h format, i18n_formattable_h formattable, char **append_to, i18n_field_position_h field_position)
	Formats an object to produce a string.
int	i18n_format_parse_object (i18n_format_h format, const char source, i18n_formattable_h result)
	Parses a string to produce an object.
int	i18n_format_parse_object_with_parse_position (i18n_format_h format, const char source, i18n_parse_position_h parse_position, i18n_formattable_h result)
	Parses a string to produce an object.
int	i18n_format_get_locale (i18n_format_h format, i18n_ulocale_data_locale_type_e type, char language, char country)
	Gets the locale for the given format object.
Typedefs
typedef void *	i18n_format_h
	Handle to the object of base class for all formats.

Typedef Documentation

typedef void* i18n_format_h

Handle to the object of base class for all formats.

Since :: 3.0

Function Documentation

int i18n_format_clone	(	i18n_format_h	format,
		i18n_format_h *	clone
	)

Creates a polymorphic clone of the given format object.

Since :: 2.3.2 and 3.0

Remarks:: The cloned object should be released by the caller with the i18n_format_destroy() function.

Parameters:

[in]	format	The format object to be cloned
[out]	clone	The clone of the given format object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_format_destroy ( i18n_format_h format )

Destroys the format object.

Since :: 2.3.2 and 3.0

Parameters:

[in] format The format object to destroy

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_format_format	(	i18n_format_h	format,
		i18n_formattable_h	formattable,
		char **	append_to
	)

Formats an object to produce a string.

Since :: 2.3.2 and 3.0

Remarks:: The append_to parameter should be released by the caller with the free() function.

Parameters:

[in]	format	The format object
[in]	formattable	The object to format
[out]	append_to	An input/output parameter to receive the result. The result is appended to the existing contents.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_format_format_with_field_position	(	i18n_format_h	format,
		i18n_formattable_h	formattable,
		char **	append_to,
		i18n_field_position_h	field_position
	)

Formats an object to produce a string.

Since :: 2.3.2 and 3.0

Remarks:: The append_to parameter should be released by the caller with the free() function.

Parameters:

[in]	format	The format object
[in]	formattable	The object to format
[out]	append_to	Input/output parameter to receive the result. The result is appended to the existing contents.
[out]	field_position	On input: an alignment field, if desired. On output: the offsets of the alignment field.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_format_get_locale	(	i18n_format_h	format,
		i18n_ulocale_data_locale_type_e	type,
		char **	language,
		char **	country
	)

Gets the locale for the given format object.

You can choose between valid and actual locale.

Since :: 2.3.2 and 3.0

Remarks:: Both language and country should be released by the caller with the free() function.

Parameters:

[in]	format	The format object
[in]	type	The type of the locale we're looking for (valid or actual)
[out]	language	The obtained locale's ISO-639 language code
[out]	country	The obtained locale's ISO-3166 country code

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_format_parse_object	(	i18n_format_h	format,
		const char *	source,
		i18n_formattable_h *	result
	)

Parses a string to produce an object.

Since :: 2.3.2 and 3.0

Remarks:: The obtained result formattable object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	format	The format object
[in]	source	The string to be parsed into an object
[out]	result	The formattable object to be set to the parse result. If parse fails, return contents are undefined.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_format_parse_object_with_parse_position	(	i18n_format_h	format,
		const char *	source,
		i18n_parse_position_h	parse_position,
		i18n_formattable_h *	result
	)

Parses a string to produce an object.

Since :: 2.3.2 and 3.0

Remarks:: The obtained result formattable object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	format	The format object
[in]	source	The string to be parsed into an object
[out]	parse_position	The position to start parsing at. Upon return this parameter is set to the position after the last character successfully parsed. If the source is not parsed successfully, this parameter will remain unchanged.
[out]	result	The formattable object to be set to the parse result. If parse fails, return contents are undefined.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation