551 lines
19 KiB
Plaintext
551 lines
19 KiB
Plaintext
/*
|
|
* Copyright 2011, Haiku, Inc. All Rights Reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Axel Dörfler, axeld@pinc-software.de.
|
|
* John Scipione, jscipione@gmail.com
|
|
* Oliver Tappe, zooey@hirschkaefer.de.
|
|
*
|
|
* Corresponds to:
|
|
* /trunk/headers/os/locale/Locale.h rev 43095
|
|
* /trunk/src/kits/locale/Locale.cpp rev 43095
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Locale.h
|
|
\brief Provides the BLocale class.
|
|
*/
|
|
|
|
|
|
/*! \class BLocale
|
|
\ingroup locale
|
|
\brief 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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLocale::BLocale(const BLanguage* language,
|
|
const BFormattingConventions* conventions)
|
|
\brief Initializes a BLocale object corresponding to the passed in
|
|
\a language and \a conventions.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLocale::BLocale(const BLocale& other)
|
|
\brief Initializes a BLocale object.
|
|
*/
|
|
|
|
|
|
/*!
|
|
status_t BLocale::GetCollator(BCollator* collator) const
|
|
\brief Gets the collator associated to this locale.
|
|
|
|
Returns the collator in use for this locale, allowing you to use it
|
|
to sort a set of strings.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLocale& BLocale::operator=(const BLocale& other)
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLocale::~BLocale()
|
|
\brief Destructor method.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetCollator(BCollator* collator) const
|
|
\brief Sets \a collator object to the default collator for the BLocale.
|
|
|
|
\param collator A pointer to a BCollator object to fill out.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went well.
|
|
\retval B_BAD_VALUE \c NULL \a collator object passed in.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetLanguage(BLanguage* language) const
|
|
\brief Sets \a language object to the default language for the BLocale.
|
|
|
|
\param language A pointer to a BLanguage object to fill out.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went well.
|
|
\retval B_BAD_VALUE \c NULL \a language object passed in.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetFormattingConventions(
|
|
BFormattingConventions* conventions) const
|
|
\brief Sets \a conventions object to the default formatting conventions
|
|
for the BLocale.
|
|
|
|
\param conventions A pointer to a BFormattingConventions object to fill out.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went well.
|
|
\retval B_BAD_VALUE \c NULL \a conventions object passed in.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BLocale::GetString(uint32 id) const
|
|
\brief Gets the language string for the locale.
|
|
|
|
\param id The locale \a id to get the language of.
|
|
|
|
\internal Assumes a certain order of the string bases.
|
|
|
|
\returns a blank string in the case of an error or the string "UTF-8"
|
|
if there is \a id is set to \a B_CODESET.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLocale::SetFormattingConventions(
|
|
const BFormattingConventions& conventions)
|
|
\brief Sets the formatting convention for this locale.
|
|
|
|
If unable to lock the BLocale \a conventions is left untouched.
|
|
|
|
\param conventions The formatting convention to set.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLocale::SetCollator(const BCollator& newCollator)
|
|
\brief Set the collator for this locale.
|
|
|
|
If unable to lock the BLocale \a newCollator is left untouched.
|
|
|
|
\param newCollator The collator to set.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLocale::SetLanguage(const BLanguage& newLanguage)
|
|
\brief Set the language for this locale.
|
|
|
|
If unable to lock the BLocale \a newLanguage is left untouched.
|
|
|
|
\param newLanguage The code of the language to set to locale to.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time,
|
|
BDateFormatStyle style) const
|
|
\brief Fills in \a string with a formatted date up to \a maxSize bytes for
|
|
the given \a time and \a style for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted date.
|
|
\param maxSize The size of the buffer.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param 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.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
|
|
|
|
\sa BLocale::FormatDateTime(char* target, size_t maxSize,
|
|
time_t time, BDateFormatStyle dateStyle,
|
|
BTimeFormatStyle timeStyle) const
|
|
\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
|
|
BTimeFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatDate(BString *string, time_t time,
|
|
BDateFormatStyle style, const BTimeZone* timeZone) const
|
|
\brief Fills in \a string with a formatted date for the given
|
|
\a time, \a style, and \a timeZone for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted date.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param style Specify the long format (with day name, full
|
|
month name) or the short format, 08/12/2010 or similar.
|
|
\param timeZone The time zone.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
|
|
\sa BLocale::FormatDateTime(BString* target, time_t time,
|
|
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
|
|
const BTimeZone* timeZone) const
|
|
\sa status_t BLocale::FormatTime(BString* string, time_t time,
|
|
BTimeFormatStyle style, const BTimeZone* timeZone) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions,
|
|
int& fieldCount, time_t time, BDateFormatStyle style) const
|
|
\brief Fills in \a string with a formatted date for the given
|
|
\a time and \a style for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted date.
|
|
\param fieldPositions ???
|
|
\param fieldCount The number of fields.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param style Specify the long format (with day name, full
|
|
month name) or the short format, 08/12/2010 or similar.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE An error occurred while performing the date formatting.
|
|
|
|
\sa BLocale::FormatTime(BString* string, int*& fieldPositions,
|
|
int& fieldCount, time_t time, BTimeFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
|
|
BDateFormatStyle style) const
|
|
\brief 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.
|
|
|
|
\param fields Pointer to the fields object.
|
|
\param fieldCount The number of fields.
|
|
\param style Specify the long format (with day name, full
|
|
month name) or the short format, 08/12/2010 or similar.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE An error occurred while getting the date fields.
|
|
|
|
\sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
|
|
BTimeFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetStartOfWeek(BWeekday* startOfWeek) const
|
|
\brief Returns the day used as the start of week in this locale.
|
|
|
|
Possible values for \a startOfWeek include:
|
|
- \c B_WEEKDAY_SUNDAY
|
|
- \c B_WEEKDAY_MONDAY
|
|
- \c B_WEEKDAY_TUESDAY
|
|
- \c B_WEEKDAY_WEDNESDAY
|
|
- \c B_WEEKDAY_THURSDAY
|
|
- \c B_WEEKDAY_FRIDAY
|
|
- \c B_WEEKDAY_SATURDAY
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_BAD_VALUE \a startOfWeek is \c NULL.
|
|
\retval B_ERROR Unable to lock the BLocale or another error occurred.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize,
|
|
time_t time, BDateFormatStyle dateStyle,
|
|
BTimeFormatStyle timeStyle) const
|
|
\brief Fills in \a string with a formatted datetime up to \a maxSize bytes
|
|
for the given \a time and \a style for the locale.
|
|
|
|
\param target The string buffer to fill with the formatted datetime.
|
|
\param maxSize The size of the buffer.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param dateStyle Specify the long format or the short format of the date.
|
|
\param timeStyle Specify the long format or the short format of the time.
|
|
|
|
\returns The number of bytes written during the datetime formatting.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
|
|
|
|
\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
|
|
BDateFormatStyle style) const
|
|
\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
|
|
BTimeFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatDateTime(BString* target, time_t time,
|
|
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
|
|
const BTimeZone* timeZone) const
|
|
\brief Fills in \a string with a formatted datetime for the given
|
|
\a time, \a timeStyle, and \a timeZone for the locale.
|
|
|
|
\param target The string buffer to fill with the formatted date.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param dateStyle Specify the long format or the short format of the date.
|
|
\param timeStyle Specify the long format or the short format of the time.
|
|
\param timeZone The time zone.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
|
|
\sa BLocale::FormatDate(BString *string, time_t time,
|
|
BDateFormatStyle style, const BTimeZone* timeZone) const
|
|
\sa status_t BLocale::FormatTime(BString* string, time_t time,
|
|
BTimeFormatStyle style, const BTimeZone* timeZone) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time,
|
|
BTimeFormatStyle style) const
|
|
\brief Fills in \a string with a formatted date up to \a maxSize bytes for
|
|
the given \a time and \a style for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted time.
|
|
\param maxSize The size of the buffer.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param style Specify the long format or the short format.
|
|
|
|
\returns The number of bytes written during the time formatting.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
|
|
|
|
\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
|
|
BDateFormatStyle style) const
|
|
\sa BLocale::FormatDateTime(char* target, size_t maxSize,
|
|
time_t time, BDateFormatStyle dateStyle,
|
|
BTimeFormatStyle timeStyle) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatTime(BString* string, time_t time,
|
|
BTimeFormatStyle style, const BTimeZone* timeZone) const
|
|
\brief Fills in \a string with a formatted time for the given
|
|
\a time, \a style, and \a timeZone for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted date.
|
|
\param time The time (in seconds since epoch) to format
|
|
\param style Specify the long format or the short format.
|
|
\param timeZone The time zone.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
|
|
\sa BLocale::FormatDate(BString *string, time_t time,
|
|
BDateFormatStyle style, const BTimeZone* timeZone) const
|
|
\sa BLocale::FormatDateTime(BString* target, time_t time,
|
|
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
|
|
const BTimeZone* timeZone) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions,
|
|
int& fieldCount, time_t time, BTimeFormatStyle style) const
|
|
\brief Fills in \a string with a formatted time for the given
|
|
\a time and \a style for the locale.
|
|
|
|
\param string The string buffer to fill with the formatted time.
|
|
\param fieldPositions ???
|
|
\param fieldCount ???
|
|
\param time The time (in seconds since epoch) to format.
|
|
\param style Specify the long format or the short format.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE An error occurred during time formatting.
|
|
|
|
\sa BLocale::FormatDate(BString* string, int*& fieldPositions,
|
|
int& fieldCount, time_t time, BDateFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
|
|
BTimeFormatStyle style) const
|
|
\brief 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.
|
|
|
|
\param fields Pointer to the fields object.
|
|
\param fieldCount The number of fields.
|
|
\param style Specify the long format or the short format.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
|
|
\retval B_BAD_VALUE An error occurred while getting the time fields.
|
|
|
|
\sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
|
|
BDateFormatStyle style) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
|
|
double value) const
|
|
\brief Format the \c double \a value as a string and put the result
|
|
into \a string up to \a maxSize bytes in the current locale.
|
|
|
|
\param string The string to put the formatted number into.
|
|
\param maxSize The maximum of bytes to copy into \a string.
|
|
\param value The number that you want to get a formatted version of.
|
|
|
|
\returns The length of the string created or an error status code.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(char* string, size_t maxSize,
|
|
int32 value) const
|
|
\sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
|
|
double value) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatNumber(BString* string, double value) const
|
|
\brief \brief Format the \c double \a value as a string and put the
|
|
result into \a string in the current locale.
|
|
|
|
\param string The string to put the formatted number into.
|
|
\param value The number that you want to get a formatted version of.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(BString* string, int32 value) const
|
|
\sa BLocale::FormatMonetary(BString* string, double value) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
|
|
int32 value) const
|
|
\brief Format the \c int32 \a value as a string and put the result
|
|
into \a string up to \a maxSize bytes in the current locale.
|
|
|
|
\param string The string to put the formatted number into.
|
|
\param maxSize The maximum of bytes to copy into \a string.
|
|
\param value The number that you want to get a formatted version of.
|
|
|
|
\returns The length of the string created or an error status code.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(char* string, size_t maxSize,
|
|
double value) const
|
|
\sa BLocale::FormatMonetary(char* string, size_t maxSize,
|
|
double value) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatNumber(BString* string, int32 value) const
|
|
\brief \brief Format the \c int32 \a value as a string and put the result
|
|
into \a string in the current locale.
|
|
|
|
\param string The string to put the formatted number into.
|
|
\param value The number that you want to get a formatted version of.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(BString* string, double value) const
|
|
\sa BLocale::FormatMonetary(BString* string, double value) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
|
|
double value) const
|
|
\brief Format the \c double \a value as a monetary string and put the
|
|
result into \a string up to \a maxSize bytes in the current locale.
|
|
|
|
\param string The \a string to put the monetary formatted number into.
|
|
\param maxSize The maximum of bytes to copy into \a string.
|
|
\param value The number to format as a monetary \a value.
|
|
|
|
\returns The length of the string created or an error status code.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(char* string, size_t maxSize, double value) const
|
|
\sa BLocale::FormatNumber(char* string, size_t maxSize, int32 value) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLocale::FormatMonetary(BString* string, double value) const
|
|
\brief \brief Format the \c double \a value as a monetary string and put
|
|
the result into \a string in the current locale.
|
|
|
|
\param string The \a string to put the monetary formatted number into.
|
|
\param value The number to format as a monetary \a value.
|
|
|
|
\returns A status code.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_ERROR Unable to lock the BLocale.
|
|
\retval B_NO_MEMORY Ran out of memory while creating the NumberFormat
|
|
object.
|
|
\retval B_BAD_VALUE An error occurred while formatting the number.
|
|
|
|
\sa BLocale::FormatNumber(BString* string, double value) const
|
|
\sa BLocale::FormatNumber(BString* string, int32 value) const
|
|
*/
|