Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
798a273725
haiku/docs/user/locale/Locale.dox
John Scipione edc845a323 Update Locale Kit docs. 
Add \since to each method. This was pretty easy to figure out since
the whole kit exists only in Haiku.
2014-06-11 16:48:17 -04:00

622 lines
20 KiB
Plaintext
Raw Blame History

/*
* 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:
* headers/os/locale/Locale.h rev 43095
* src/kits/locale/Locale.cpp rev 43095
*/
/*!
\file Locale.h
\ingroup locale
\ingroup libbe
\brief Provides the BLocale class, the base class of the Locale Kit.
*/
/*!
\class BLocale
\ingroup locale
\ingroup libbe
\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.
\since Haiku R1
*/
/*!
\fn BLocale::BLocale(const BLanguage* language,
const BFormattingConventions* conventions)
\brief Initializes a BLocale object corresponding to the passed in
\a language and \a conventions.
\since Haiku R1
*/
/*!
\fn BLocale::BLocale(const BLocale& other)
\brief Initializes a BLocale object as a copy of \a other.
\param other The BLocale object to initialize from.
\since Haiku R1
*/
/*!
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.
\since Haiku R1
*/
/*!
\fn BLocale& BLocale::operator=(const BLocale& other)
\brief Initializes a BLocale object as a copy of \a other by overloading
the = operator.
\param other The BLocale object to initialize from.
\since Haiku R1
*/
/*!
\fn BLocale::~BLocale()
\brief Destructor method.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\fn status_t BLocale::GetFormattingConventions(
BFormattingConventions* conventions) const
\brief Fills out \a conventions with 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.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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.
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\fn status_t BLocale::FormatNumber(BString* string, int32 value) const
\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
\since Haiku R1
*/
/*!
\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
\since Haiku R1
*/
/*!
\fn status_t BLocale::FormatMonetary(BString* string, double value) const
\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
\since Haiku R1
*/
Reference in New Issue View Git Blame Copy Permalink