The MeasureFormat is a formatter for Measure objects.

Required Header

#include <utils_i18n.h>

Overview

Functions
int	i18n_measure_format_create (const char language, const char country, i18n_umeasure_format_width_e width, i18n_measure_format_h *measure_format)
	Creates the measure format object using given locale.
int	i18n_measure_format_destroy (i18n_measure_format_h measure_format)
	Destroys the measure format object.
int	i18n_measure_format_clone (i18n_measure_format_h measure_format, i18n_format_h *clone)
	Creates a polymorphic clone of the given measure_format object.
int	i18n_measure_format_format (i18n_measure_format_h measure_format, i18n_formattable_h formattable, char **append_to, i18n_field_position_h field_position)
	Formats an object to produce a string.
int	i18n_measure_format_parse_object (i18n_measure_format_h measure_format, const char source, i18n_parse_position_h parse_position, i18n_formattable_h result)
	Parses a string to produce an object.
int	i18n_measure_format_create_currency_format_from_locale (const char language, const char country, i18n_measure_format_h *measure_format)
	Gets a formatter for currency amount objects in the given locale.
int	i18n_measure_format_create_currency_format (i18n_measure_format_h *measure_format)
	Gets a formatter for currency amount objects in the default locale.
int	i18n_measure_format_format_buff (const i18n_measure_format_h measure_format, const i18n_formattable_h formattable, i18n_field_position_h field_position, int32_t append_to_size, i18n_uchar append_to, int32_t output_length)
	Formats an object to produce a string.
int	i18n_measure_format_format_measures (const i18n_measure_format_h measure_format, const i18n_measure_h measures, int32_t measures_count, i18n_field_position_h field_position, int32_t append_to_size, i18n_uchar append_to, int32_t *output_length)
	Formats measure objects to produce a string.
int	i18n_measure_format_format_measure_per_unit (const i18n_measure_format_h measure_format, const i18n_measure_h measure, const i18n_measure_unit_h measure_unit, i18n_field_position_h field_position, int32_t append_to_size, i18n_uchar append_to, int32_t output_length)
	Formats a single measure per unit.
Typedefs
typedef void *	i18n_measure_format_h
	Handle to the object that represents a formatter for measure objects.

Typedef Documentation

typedef void* i18n_measure_format_h

Handle to the object that represents a formatter for measure objects.

Since :: 3.0

Enumeration Type Documentation

enum i18n_umeasure_format_width_e

Enumeration for various widths.

Since :: 3.0

Enumerator:

I18N_UMEASFMT_WIDTH_WIDE	Spell out measure units
I18N_UMEASFMT_WIDTH_SHORT	Abbreviate measure units
I18N_UMEASFMT_WIDTH_NARROW	Use symbols for measure units when possible
I18N_UMEASFMT_WIDTH_NUMERIC	Completely omit measure units when possible For example, format '5 hours, 37 minutes' as '5:37'
I18N_UMEASFMT_WIDTH_COUNT	Count of values in this enumeration

Function Documentation

int i18n_measure_format_clone	(	i18n_measure_format_h	measure_format,
		i18n_format_h *	clone
	)

Creates a polymorphic clone of the given measure_format object.

Since :: 2.3.2 and 3.0

Remarks:: The clone object should be released by the caller with the i18n_measure_format_destroy() function.

Parameters:

[in]	measure_format	The measure format object to be cloned
[out]	clone	The created measure 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_measure_format_create	(	const char *	language,
		const char *	country,
		i18n_umeasure_format_width_e	width,
		i18n_measure_format_h *	measure_format
	)

Creates the measure format object using given locale.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_measure_format_destroy() function.

Parameters:

[in]	language	The language of the locale
[in]	country	The country of the locale
[in]	width	The format width
[out]	measure_format	The created measure 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_measure_format_create_currency_format ( i18n_measure_format_h * measure_format )

Gets a formatter for currency amount objects in the default locale.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_measure_format_destroy() function.

Parameters:

[out] measure_format The measure 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_measure_format_create_currency_format_from_locale	(	const char *	language,
		const char *	country,
		i18n_measure_format_h *	measure_format
	)

Gets a formatter for currency amount objects in the given locale.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_measure_format_destroy() function.

Parameters:

[in]	language	The language of the locale
[in]	country	The country of the locale
[out]	measure_format	The measure 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_measure_format_destroy ( i18n_measure_format_h measure_format )

Destroys the measure format object.

Since :: 2.3.2 and 3.0

Parameters:

[in] measure_format The measure 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_measure_format_format	(	i18n_measure_format_h	measure_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 obtained append_to string is actually a concatenation of the given input string and the result of the function (appended to the string). Actually, the append_to buffer is being reallocated inside the function which means that the buffer is not at the same place in memory as it was on the input. Please note that the append_to buffer should be released by the caller with the free() function. append_to buffer should be allocated on the heap.

Parameters:

[in]	measure_format	The format object
[in]	formattable	The object to format
[in,out]	append_to	Input/output parameter to receive the result. The result is appended to the existing contents.
[in]	field_position	The i18n_field_position_h 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_measure_format_format_buff	(	const i18n_measure_format_h	measure_format,
		const i18n_formattable_h	formattable,
		i18n_field_position_h	field_position,
		int32_t	append_to_size,
		i18n_uchar *	append_to,
		int32_t *	output_length
	)

Formats an object to produce a string.

Since :: 4.0

Remarks:: If output_length is lower than append_to_size then formatted string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned. Otherwise the obtained append_to string is a concatenation of the given input string and formatted string. If output_length is equal to append_to_size then output string is not NULL terminated.

Parameters:

[in]	measure_format	The format object
[in]	formattable	The object to format
[in]	field_position	The i18n_field_position_h object
[in]	append_to_size	The size of the append_to buffer. If `append_to_size <= 0` then output string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[in,out]	append_to	The buffer to which formatted string will be appended. Can be NULL if `append_to_size <= 0`. Otherwise must be NULL terminated.
[out]	output_length	The length of the output string, which is the string in append_to buffer with formatted string.

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	Buffer overflow

int i18n_measure_format_format_measure_per_unit	(	const i18n_measure_format_h	measure_format,
		const i18n_measure_h	measure,
		const i18n_measure_unit_h	measure_unit,
		i18n_field_position_h	field_position,
		int32_t	append_to_size,
		i18n_uchar *	append_to,
		int32_t *	output_length
	)

Formats a single measure per unit.

Since :: 4.0

Remarks:: If output_length is lower than append_to_size then formatted string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned. Otherwise the obtained append_to string is a concatenation of the given input string and formatted string. If output_length is equal to append_to_size then output string is not NULL terminated.

Parameters:

[in]	measure_format	The format object
[in]	measure	The i18n_measure_h object to format
[in]	measure_unit	The i18n_measure_unit_h object
[in]	field_position	The i18n_field_position_h object
[in]	append_to_size	The size of the append_to buffer. If `append_to_size <= 0` then output string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[in,out]	append_to	The buffer to which formatted string will be appended. Can be NULL if `append_to_size <= 0`. Otherwise must be NULL terminated.
[out]	output_length	The length of the output string, which is the string in append_to buffer with formatted string.

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	Buffer overflow

int i18n_measure_format_format_measures	(	const i18n_measure_format_h	measure_format,
		const i18n_measure_h *	measures,
		int32_t	measures_count,
		i18n_field_position_h	field_position,
		int32_t	append_to_size,
		i18n_uchar *	append_to,
		int32_t *	output_length
	)

Formats measure objects to produce a string.

i18n_measure_h objects appear in the formatted string in the same order they appear in the measures array.

Since :: 4.0

Remarks:: If output_length is lower than append_to_size then formatted string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned. Otherwise the obtained append_to string is a concatenation of the given input string and formatted string. If output_length is equal to append_to_size then output string is not NULL terminated.

Parameters:

[in]	measure_format	The format object
[in]	measures	The array of the i18n_measure_h objects to format
[in]	measures_count	The number of the i18n_measure_h objects in the measures array
[in]	field_position	The i18n_field_position_h object
[in]	append_to_size	The size of the append_to buffer. If `append_to_size <= 0` then output string is not appended to the append_to buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[in,out]	append_to	The buffer to which formatted string will be appended. Can be NULL if `append_to_size <= 0`. Otherwise must be NULL terminated.
[out]	output_length	The length of the output string, which is the string in append_to buffer with formatted string.

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	Buffer overflow

int i18n_measure_format_parse_object	(	i18n_measure_format_h	measure_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 object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	measure_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
I18N_ERROR_OUT_OF_MEMORY	Out of memory

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation