Class for representing a locale and its settings. More...

Public Member Functions
	BLocale (const BLanguage language=NULL, const BFormattingConventions conventions=NULL)
	Initializes a BLocale object corresponding to the passed in language and conventions.
	BLocale (const BLocale &other)
	Initializes a BLocale object.
	~BLocale ()
	Destructor method.
ssize_t	FormatDate (char *string, size_t maxSize, time_t time, BDateFormatStyle style) const
	Fills in string with a formatted date up to maxSize bytes for the given time and style for the locale.
status_t	FormatDate (BString string, time_t time, BDateFormatStyle style, const BTimeZone timeZone=NULL) const
	Fills in string with a formatted date for the given time, style, and timeZone for the locale.
status_t	FormatDate (BString string, int &fieldPositions, int &fieldCount, time_t time, BDateFormatStyle style) const
	Fills in string with a formatted date for the given time and style for the locale.
ssize_t	FormatDateTime (char *target, size_t maxSize, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle) const
	Fills in string with a formatted datetime up to maxSize bytes for the given time and style for the locale.
status_t	FormatDateTime (BString buffer, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, const BTimeZone timeZone=NULL) const
	Fills in string with a formatted datetime for the given time, timeStyle, and timeZone for the locale.
ssize_t	FormatMonetary (char *string, size_t maxSize, double value) const
	Format the `double` value as a monetary string and put the result into string up to maxSize bytes in the current locale.
status_t	FormatMonetary (BString *string, double value) const
	Format the `double` value as a monetary string and put the result into string in the current locale.
ssize_t	FormatNumber (char *string, size_t maxSize, double value) const
	Format the `double` value as a string and put the result into string up to maxSize bytes in the current locale.
status_t	FormatNumber (BString *string, double value) const
	Format the `double` value as a string and put the result into string in the current locale.
ssize_t	FormatNumber (char *string, size_t maxSize, int32 value) const
	Format the `int32` value as a string and put the result into string up to maxSize bytes in the current locale.
status_t	FormatNumber (BString *string, int32 value) const
	Format the `int32` value as a string and put the result into string in the current locale.
ssize_t	FormatTime (char *string, size_t maxSize, time_t time, BTimeFormatStyle style) const
	Fills in string with a formatted date up to maxSize bytes for the given time and style for the locale.
status_t	FormatTime (BString string, time_t time, BTimeFormatStyle style, const BTimeZone timeZone=NULL) const
	Fills in string with a formatted time for the given time, style, and timeZone for the locale.
status_t	FormatTime (BString string, int &fieldPositions, int &fieldCount, time_t time, BTimeFormatStyle style) const
	Fills in string with a formatted time for the given time and style for the locale.
status_t	GetCollator (BCollator *collator) const
	Sets collator object to the default collator for the BLocale.
status_t	GetDateFields (BDateElement *&fields, int &fieldCount, BDateFormatStyle style) const
	Get the type of each field in the date format of the locale.
status_t	GetFormattingConventions (BFormattingConventions *conventions) const
	Sets conventions object to the default formatting conventions for the BLocale.
status_t	GetLanguage (BLanguage *language) const
	Sets language object to the default language for the BLocale.
status_t	GetStartOfWeek (BWeekday *weekday) const
	Returns the day used as the start of week in this locale.
const char *	GetString (uint32 id) const
	Gets the language string for the locale.
status_t	GetTimeFields (BDateElement *&fields, int &fieldCount, BTimeFormatStyle style) const
	Get the type of each field in the time format of the locale.
BLocale &	operator= (const BLocale &other)
	Gets the collator associated to this locale.
void	SetCollator (const BCollator &newCollator)
	Set the collator for this locale.
void	SetFormattingConventions (const BFormattingConventions &conventions)
	Sets the formatting convention for this locale.
void	SetLanguage (const BLanguage &newLanguage)
	Set the language for this locale.

Detailed Description

Class for representing a locale and its settings.

A locale is defined by the combination of a country and a language. Using these two informations, it is possible to determine the format to use for date, time, and number formatting. The BLocale class also provide collators, which allows you to sort a list of strings properly depending on a set of rules about accented chars and other special cases that vary over the different locales.

BLocale is also the class to use when you want to perform formatting or parsing of dates, times, and numbers, in the natural language of the user.

Member Function Documentation

ssize_t BLocale::FormatDate	(	char *	string,
		size_t	maxSize,
		time_t	time,
		BDateFormatStyle	style
	)		const

Fills in string with a formatted date up to maxSize bytes for the given time and style for the locale.

Parameters:

string	The string buffer to fill with the formatted date.
maxSize	The size of the buffer.
time	The time (in seconds since epoch) to format
style	Specify the long format (with day name, full month name) or the short format, 08/12/2010 or similar.

Returns:: The number of bytes written during the date formatting.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	CheckedArrayByteSink overflowed.

See also:: BLocale::FormatDateTime(char* target, size_t maxSize, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle) const; BLocale::FormatTime(char* string, size_t maxSize, time_t time, BTimeFormatStyle style) const

status_t BLocale::FormatDate	(	BString *	string,
		time_t	time,
		BDateFormatStyle	style,
		const BTimeZone *	timeZone = `NULL`
	)		const

Fills in string with a formatted date for the given time, style, and timeZone for the locale.

Parameters:

string	The string buffer to fill with the formatted date.
time	The time (in seconds since epoch) to format
style	Specify the long format (with day name, full month name) or the short format, 08/12/2010 or similar.
timeZone	The time zone.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.

See also:: BLocale::FormatDateTime(BString* target, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, const BTimeZone* timeZone) const; status_t BLocale::FormatTime(BString* string, time_t time, BTimeFormatStyle style, const BTimeZone* timeZone) const

status_t BLocale::FormatDate	(	BString *	string,
		int *&	fieldPositions,
		int &	fieldCount,
		time_t	time,
		BDateFormatStyle	style
	)		const

Fills in string with a formatted date for the given time and style for the locale.

Parameters:

string	The string buffer to fill with the formatted date.
fieldPositions	???
fieldCount	The number of fields.
time	The time (in seconds since epoch) to format
style	Specify the long format (with day name, full month name) or the short format, 08/12/2010 or similar.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	An error occurred while performing the date formatting.

See also:: BLocale::FormatTime(BString* string, int*& fieldPositions, int& fieldCount, time_t time, BTimeFormatStyle style) const

ssize_t BLocale::FormatDateTime	(	char *	target,
		size_t	maxSize,
		time_t	time,
		BDateFormatStyle	dateStyle,
		BTimeFormatStyle	timeStyle
	)		const

Fills in string with a formatted datetime up to maxSize bytes for the given time and style for the locale.

Parameters:

target	The string buffer to fill with the formatted datetime.
maxSize	The size of the buffer.
time	The time (in seconds since epoch) to format
dateStyle	Specify the long format or the short format of the date.
timeStyle	Specify the long format or the short format of the time.

Returns:: The number of bytes written during the datetime formatting.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	CheckedArrayByteSink overflowed.

See also:: BLocale::FormatDate(char* string, size_t maxSize, time_t time, BDateFormatStyle style) const; BLocale::FormatTime(char* string, size_t maxSize, time_t time, BTimeFormatStyle style) const

status_t BLocale::FormatDateTime	(	BString *	target,
		time_t	time,
		BDateFormatStyle	dateStyle,
		BTimeFormatStyle	timeStyle,
		const BTimeZone *	timeZone = `NULL`
	)		const

Fills in string with a formatted datetime for the given time, timeStyle, and timeZone for the locale.

Parameters:

target	The string buffer to fill with the formatted date.
time	The time (in seconds since epoch) to format
dateStyle	Specify the long format or the short format of the date.
timeStyle	Specify the long format or the short format of the time.
timeZone	The time zone.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.

See also:: BLocale::FormatDate(BString *string, time_t time, BDateFormatStyle style, const BTimeZone* timeZone) const; status_t BLocale::FormatTime(BString* string, time_t time, BTimeFormatStyle style, const BTimeZone* timeZone) const

ssize_t BLocale::FormatMonetary	(	char *	string,
		size_t	maxSize,
		double	value
	)		const

Format the double value as a monetary string and put the result into string up to maxSize bytes in the current locale.

Parameters:

string	The string to put the monetary formatted number into.
maxSize	The maximum of bytes to copy into string.
value	The number to format as a monetary value.

Returns:: The length of the string created or an error status code.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(char* string, size_t maxSize, double value) const; BLocale::FormatNumber(char* string, size_t maxSize, int32 value) const

status_t BLocale::FormatMonetary	(	BString *	string,
		double	value
	)		const

Format the double value as a monetary string and put the result into string in the current locale.

Parameters:

string	The string to put the monetary formatted number into.
value	The number to format as a monetary value.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(BString* string, double value) const; BLocale::FormatNumber(BString* string, int32 value) const

ssize_t BLocale::FormatNumber	(	char *	string,
		size_t	maxSize,
		double	value
	)		const

Format the double value as a string and put the result into string up to maxSize bytes in the current locale.

Parameters:

string	The string to put the formatted number into.
maxSize	The maximum of bytes to copy into string.
value	The number that you want to get a formatted version of.

Returns:: The length of the string created or an error status code.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(char* string, size_t maxSize, int32 value) const; ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, double value) const

status_t BLocale::FormatNumber	(	BString *	string,
		double	value
	)		const

Format the double value as a string and put the result into string in the current locale.

Parameters:

string	The string to put the formatted number into.
value	The number that you want to get a formatted version of.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(BString* string, int32 value) const; BLocale::FormatMonetary(BString* string, double value) const

ssize_t BLocale::FormatNumber	(	char *	string,
		size_t	maxSize,
		int32	value
	)		const

Format the int32 value as a string and put the result into string up to maxSize bytes in the current locale.

Parameters:

string	The string to put the formatted number into.
maxSize	The maximum of bytes to copy into string.
value	The number that you want to get a formatted version of.

Returns:: The length of the string created or an error status code.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(char* string, size_t maxSize, double value) const; BLocale::FormatMonetary(char* string, size_t maxSize, double value) const

status_t BLocale::FormatNumber	(	BString *	string,
		int32	value
	)		const

Format the int32 value as a string and put the result into string in the current locale.

Parameters:

string	The string to put the formatted number into.
value	The number that you want to get a formatted version of.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the NumberFormat object.
B_BAD_VALUE	An error occurred while formatting the number.

See also:: BLocale::FormatNumber(BString* string, double value) const; BLocale::FormatMonetary(BString* string, double value) const

ssize_t BLocale::FormatTime	(	char *	string,
		size_t	maxSize,
		time_t	time,
		BTimeFormatStyle	style
	)		const

Fills in string with a formatted date up to maxSize bytes for the given time and style for the locale.

Parameters:

string	The string buffer to fill with the formatted time.
maxSize	The size of the buffer.
time	The time (in seconds since epoch) to format
style	Specify the long format or the short format.

Returns:: The number of bytes written during the time formatting.

Return values:

B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	CheckedArrayByteSink overflowed.

See also:: BLocale::FormatDate(char* string, size_t maxSize, time_t time, BDateFormatStyle style) const; BLocale::FormatDateTime(char* target, size_t maxSize, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle) const

status_t BLocale::FormatTime	(	BString *	string,
		time_t	time,
		BTimeFormatStyle	style,
		const BTimeZone *	timeZone = `NULL`
	)		const

Fills in string with a formatted time for the given time, style, and timeZone for the locale.

Parameters:

string	The string buffer to fill with the formatted date.
time	The time (in seconds since epoch) to format
style	Specify the long format or the short format.
timeZone	The time zone.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.

See also:: BLocale::FormatDate(BString *string, time_t time, BDateFormatStyle style, const BTimeZone* timeZone) const; BLocale::FormatDateTime(BString* target, time_t time, BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, const BTimeZone* timeZone) const

status_t BLocale::FormatTime	(	BString *	string,
		int *&	fieldPositions,
		int &	fieldCount,
		time_t	time,
		BTimeFormatStyle	style
	)		const

Fills in string with a formatted time for the given time and style for the locale.

Parameters:

string	The string buffer to fill with the formatted time.
fieldPositions	???
fieldCount	???
time	The time (in seconds since epoch) to format.
style	Specify the long format or the short format.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	An error occurred during time formatting.

See also:: BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount, time_t time, BDateFormatStyle style) const

status_t BLocale::GetCollator ( BCollator * collator ) const

Sets collator object to the default collator for the BLocale.

Parameters:

collator A pointer to a BCollator object to fill out.

Returns:: A status code.

Return values:

B_OK	Everything went well.
B_BAD_VALUE	`NULL` collator object passed in.
B_ERROR	Unable to lock the BLocale.

status_t BLocale::GetDateFields	(	BDateElement *&	fields,
		int &	fieldCount,
		BDateFormatStyle	style
	)		const

Get the type of each field in the date format of the locale.

This method is most often used in combination with FormatDate(). FormatDate() gives you the offset of each field in a formatted string, and GetDateFields() gives you the type of the field at a given offset. With these informations, you can handle the formatted date string as a list of fields that you can split and alter at will.

Parameters:

fields	Pointer to the fields object.
fieldCount	The number of fields.
style	Specify the long format (with day name, full month name) or the short format, 08/12/2010 or similar.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	An error occurred while getting the date fields.

See also:: BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, BTimeFormatStyle style) const

status_t BLocale::GetFormattingConventions ( BFormattingConventions * conventions ) const

Sets conventions object to the default formatting conventions for the BLocale.

Parameters:

conventions A pointer to a BFormattingConventions object to fill out.

Returns:: A status code.

Return values:

B_OK	Everything went well.
B_BAD_VALUE	`NULL` conventions object passed in.
B_ERROR	Unable to lock the BLocale.

status_t BLocale::GetLanguage ( BLanguage * language ) const

Sets language object to the default language for the BLocale.

Parameters:

language A pointer to a BLanguage object to fill out.

Returns:: A status code.

Return values:

B_OK	Everything went well.
B_BAD_VALUE	`NULL` language object passed in.
B_ERROR	Unable to lock the BLocale.

status_t BLocale::GetStartOfWeek ( BWeekday * startOfWeek ) const

Returns the day used as the start of week in this locale.

Possible values for startOfWeek include:

B_WEEKDAY_SUNDAY
B_WEEKDAY_MONDAY
B_WEEKDAY_TUESDAY
B_WEEKDAY_WEDNESDAY
B_WEEKDAY_THURSDAY
B_WEEKDAY_FRIDAY
B_WEEKDAY_SATURDAY

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_BAD_VALUE	startOfWeek is `NULL`.
B_ERROR	Unable to lock the BLocale or another error occurred.

const char * BLocale::GetString ( uint32 id ) const

Gets the language string for the locale.

Parameters:

id	The locale id to get the language of.

status_t BLocale::GetTimeFields	(	BDateElement *&	fields,
		int &	fieldCount,
		BTimeFormatStyle	style
	)		const

Get the type of each field in the time format of the locale.

This method is used most often in combination with FormatTime(). FormatTime() gives you the offset of each field in a formatted string, and GetTimeFields() gives you the type of the field at a given offset. With this information you can handle the formatted date string as a list of fields that you can split and alter at will.

Parameters:

fields	Pointer to the fields object.
fieldCount	The number of fields.
style	Specify the long format or the short format.

Returns:: A status code.

Return values:

B_OK	Everything went fine.
B_ERROR	Unable to lock the BLocale.
B_NO_MEMORY	Ran out of memory while creating the DateFormat object.
B_BAD_VALUE	An error occurred while getting the time fields.

See also:: BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, BDateFormatStyle style) const

BLocale & BLocale::operator= ( const BLocale & other )

Gets the collator associated to this locale.

status_t BLocale::GetCollator(BCollator* collator) const Returns the collator in use for this locale, allowing you to use it to sort a set of strings.

void BLocale::SetCollator ( const BCollator & newCollator )

Set the collator for this locale.

If unable to lock the BLocale newCollator is left untouched.

Parameters:

newCollator The collator to set.

void BLocale::SetFormattingConventions ( const BFormattingConventions & conventions )

Sets the formatting convention for this locale.

If unable to lock the BLocale conventions is left untouched.

Parameters:

conventions The formatting convention to set.

void BLocale::SetLanguage ( const BLanguage & newLanguage )

Set the language for this locale.

If unable to lock the BLocale newLanguage is left untouched.

Parameters:

newLanguage The code of the language to set to locale to.

Public Member Functions

Detailed Description

Member Function Documentation