Tizen Native API  5.0
MeasureFormat

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) TIZEN_DEPRECATED_API
 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) TIZEN_DEPRECATED_API
 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.
int i18n_measure_format_get_unit_display_name (const i18n_measure_format_h measure_format, const i18n_measure_unit_h measure_unit, int32_t buffer_size, i18n_uchar *buffer, int32_t *output_length)
 Gets the display name of the i18n_measure_unit_h corresponding to the current locale and format width.
int i18n_measure_format_create_from_locale_id (const char *locale_id, i18n_umeasure_format_width_e width, i18n_measure_format_h *measure_format)
 Creates the measure format object using given locale.
int i18n_measure_format_create_currency_format_from_locale_id (const char *locale_id, i18n_measure_format_h *measure_format)
 Gets a formatter for currency amount objects in the given locale.

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

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_formatThe measure format object to be cloned
[out]cloneThe created measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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.

Deprecated:
Deprecated since 5.0. Use i18n_measure_format_create_from_locale_id() instead.
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]languageThe language of the locale
[in]countryThe country of the locale
[in]widthThe format width
[out]measure_formatThe created measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

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_formatThe measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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.

Deprecated:
Deprecated since 5.0. Use i18n_measure_format_create_currency_format_from_locale_id() instead.
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]languageThe language of the locale
[in]countryThe country of the locale
[out]measure_formatThe measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
int i18n_measure_format_create_currency_format_from_locale_id ( const char *  locale_id,
i18n_measure_format_h measure_format 
)

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

Since :
5.0
Remarks:
The created object should be released by the caller with the i18n_measure_format_destroy() function.
Parameters:
[in]locale_idThe locale string containing language and country code
[out]measure_formatThe measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
int i18n_measure_format_create_from_locale_id ( const char *  locale_id,
i18n_umeasure_format_width_e  width,
i18n_measure_format_h measure_format 
)

Creates the measure format object using given locale.

Since :
5.0
Remarks:
The created object should be released by the caller with the i18n_measure_format_destroy() function.
Parameters:
[in]locale_idThe locale string containing language and country code
[in]widthThe format width
[out]measure_formatThe created measure format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

Destroys the measure format object.

Since :
2.3.2 and 3.0
Parameters:
[in]measure_formatThe measure format object to destroy
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_formatThe format object
[in]formattableThe object to format
[in,out]append_toInput/output parameter to receive the result. The result is appended to the existing contents.
[in]field_positionThe i18n_field_position_h object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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_formatThe format object
[in]formattableThe object to format
[in]field_positionThe i18n_field_position_h object
[in]append_to_sizeThe 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_toThe buffer to which formatted string will be appended. Can be NULL if append_to_size <= 0. Otherwise must be NULL terminated.
[out]output_lengthThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer 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_formatThe format object
[in]measureThe i18n_measure_h object to format
[in]measure_unitThe i18n_measure_unit_h object
[in]field_positionThe i18n_field_position_h object
[in]append_to_sizeThe 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_toThe buffer to which formatted string will be appended. Can be NULL if append_to_size <= 0. Otherwise must be NULL terminated.
[out]output_lengthThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer 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_formatThe format object
[in]measuresThe array of the i18n_measure_h objects to format
[in]measures_countThe number of the i18n_measure_h objects in the measures array
[in]field_positionThe i18n_field_position_h object
[in]append_to_sizeThe 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_toThe buffer to which formatted string will be appended. Can be NULL if append_to_size <= 0. Otherwise must be NULL terminated.
[out]output_lengthThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer overflow
int i18n_measure_format_get_unit_display_name ( const i18n_measure_format_h  measure_format,
const i18n_measure_unit_h  measure_unit,
int32_t  buffer_size,
i18n_uchar buffer,
int32_t *  output_length 
)

Gets the display name of the i18n_measure_unit_h corresponding to the current locale and format width.

Since :
5.0
Parameters:
[in]measure_formatThe measure format object
[in]measure_unitThe unit for which to get the display name
[in]buffer_sizeThe size of the buffer. If buffer_size <= 0 then the output string is not inserted to the buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[out]bufferThe buffer to which the formatted string will be inserted. Can be NULL if buffer_size <= 0.
[out]output_lengthThe length of the output string
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer 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_formatThe format object
[in]sourceThe string to be parsed into an object
[out]parse_positionThe 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]resultThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory