Field Position is a simple type used by the Format module and its submodules to identify fields in formatted output.

Required Header

#include <utils_i18n.h>

Overview

Fields are identified by constants defined in *_format_field_e enumerations. The only fields currently supported are the fields accepted by the date formatter, see i18n_udate_format_field_e. Field position keeps track of the position of the field within the formatted output with two indices: the index of the first character of the field and the index of the last character of the field. One version of the format function in the various Format modules requires a Field Position object as an argument. You use this format function to perform partial formatting or to get information about the formatted output (such as the position of a field).

Functions
int	i18n_field_position_create (i18n_field_position_h *field_position)
	Creates a field position object with a non-specified field.
int	i18n_field_position_create_for_field (int32_t field, i18n_field_position_h *field_position)
	Creates a field position object for the given field.
int	i18n_field_position_destroy (i18n_field_position_h field_position)
	Destroys the field position object.
int	i18n_field_position_clone (i18n_field_position_h field_position, i18n_field_position_h *clone)
	Creates a clone of the given field_position object.
int	i18n_field_position_get_field (i18n_field_position_h field_position, int32_t *field)
	Retrieves the field identifier.
int	i18n_field_position_get_begin_index (i18n_field_position_h field_position, int32_t *begin_index)
	Retrieves the index of the first character in the requested field.
int	i18n_field_position_get_end_index (i18n_field_position_h field_position, int32_t *end_index)
	Retrieves the index of the character following the last character in the requested field.
int	i18n_field_position_set_field (i18n_field_position_h field_position, int32_t field)
	Sets the field.
int	i18n_field_position_set_begin_index (i18n_field_position_h field_position, int32_t begin_index)
	Sets the begin index.
int	i18n_field_position_set_end_index (i18n_field_position_h field_position, int32_t end_index)
	Sets the end index.
Typedefs
typedef void *	i18n_field_position_h
	Handle to the object of class used by the i18n_format_h and its subclasses to identify fields in a formatted output.

Typedef Documentation

typedef void* i18n_field_position_h

Handle to the object of class used by the i18n_format_h and its subclasses to identify fields in a formatted output.

Since :: 3.0

Enumeration Type Documentation

enum i18n_field_position_dont_care_e

DONT_CARE may be specified as the field to indicate that the caller doesn't need to specify a field.

Since :: 3.0

Function Documentation

int i18n_field_position_clone	(	i18n_field_position_h	field_position,
		i18n_field_position_h *	clone
	)

Creates a clone of the given field_position object.

Since :: 2.3.2

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

Parameters:

[in]	field_position	The field position object to be cloned
[out]	clone	The created field position 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_field_position_create ( i18n_field_position_h * field_position )

Creates a field position object with a non-specified field.

Since :: 2.3.2

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

Parameters:

[out] field_position The created field position 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_field_position_create_for_field	(	int32_t	field,
		i18n_field_position_h *	field_position
	)

Creates a field position object for the given field.

The only fields currently supported are the fields accepted by the date formatter, see i18n_udate_format_field_e.

Since :: 2.3.2

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

Parameters:

[in]	field	The field value
[out]	field_position	The created field position 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_field_position_destroy ( i18n_field_position_h field_position )

Destroys the field position object.

Since :: 2.3.2

Parameters:

[in] field_position The field position 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_field_position_get_begin_index	(	i18n_field_position_h	field_position,
		int32_t *	begin_index
	)

Retrieves the index of the first character in the requested field.

Since :: 2.3.2

Parameters:

[in]	field_position	The field position object
[out]	begin_index	The index of the first character in the requested field

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_field_position_get_end_index	(	i18n_field_position_h	field_position,
		int32_t *	end_index
	)

Retrieves the index of the character following the last character in the requested field.

Since :: 2.3.2

Parameters:

[in]	field_position	The field position object
[out]	end_index	The index of the character following the last character in the requested field

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_field_position_get_field	(	i18n_field_position_h	field_position,
		int32_t *	field
	)

Retrieves the field identifier.

Since :: 2.3.2

Parameters:

[in]	field_position	The field_position object
[out]	field	The field identifier

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_field_position_set_begin_index	(	i18n_field_position_h	field_position,
		int32_t	begin_index
	)

Sets the begin index.

Since :: 2.3.2

Parameters:

[in]	field_position	The field_position object
[in]	begin_index	The new value of the begin index

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_field_position_set_end_index	(	i18n_field_position_h	field_position,
		int32_t	end_index
	)

Sets the end index.

Since :: 2.3.2

Parameters:

[in]	field_position	The field_position object
[in]	end_index	The new value of the end index

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

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_field_position_set_field	(	i18n_field_position_h	field_position,
		int32_t	field
	)

Sets the field.

Since :: 2.3.2

Parameters:

[in]	field_position	The field_position object
[in]	field	The new value of the field

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

Enumeration Type Documentation

Function Documentation