Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Return B_ERROR if a locking error occurs in while locking the BLocale object, return B_BAD_VALUE if an ICU error occurs or the passed in value is NULL. Update BLocale API documentation to reflect this and also add some more documentation fixes. Closes #7901 pending confirmation.

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@43095 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
John Scipione 2011-11-02 06:02:36 +00:00
parent 8d15934d9b
commit 740ae7fef6
2 changed files with 100 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
docs/user/locale/Locale.dox
View File

@ -8,8 +8,8 @@
* Oliver Tappe, zooey@hirschkaefer.de. * Oliver Tappe, zooey@hirschkaefer.de.
* *
* Corresponds to: * Corresponds to:
* /trunk/headers/os/locale/Locale.h rev 42274 * /trunk/headers/os/locale/Locale.h rev 43095
* /trunk/src/kits/locale/Locale.cpp rev 42274 * /trunk/src/kits/locale/Locale.cpp rev 43095
*/ */
@ -129,6 +129,8 @@
const BFormattingConventions& conventions) const BFormattingConventions& conventions)
\brief Sets the formatting convention for this locale. \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. \param conventions The formatting convention to set.
*/ */
@ -137,6 +139,8 @@
\fn void BLocale::SetCollator(const BCollator& newCollator) \fn void BLocale::SetCollator(const BCollator& newCollator)
\brief Set the collator for this locale. \brief Set the collator for this locale.
If unable to lock the BLocale \a newCollator is left untouched.
\param newCollator The collator to set. \param newCollator The collator to set.
*/ */
@ -145,6 +149,8 @@
\fn void BLocale::SetLanguage(const BLanguage& newLanguage) \fn void BLocale::SetLanguage(const BLanguage& newLanguage)
\brief Set the language for this locale. \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. \param newLanguage The code of the language to set to locale to.
*/ */
@ -207,15 +213,16 @@
\param string The string buffer to fill with the formatted date. \param string The string buffer to fill with the formatted date.
\param fieldPositions ??? \param fieldPositions ???
\param fieldCount ??? \param fieldCount The number of fields.
\param time The time (in seconds since epoch) to format \param time The time (in seconds since epoch) to format
\param style Specify the long format (with day name, full \param style Specify the long format (with day name, full
month name) or the short format, 08/12/2010 or similar. month name) or the short format, 08/12/2010 or similar.
\returns A status code. \returns A status code.
\retval B_OK Everything went fine. \retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error formatting the date. \retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. \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, \sa BLocale::FormatTime(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BTimeFormatStyle style) const int& fieldCount, time_t time, BTimeFormatStyle style) const
@ -227,7 +234,7 @@
BDateFormatStyle style) const BDateFormatStyle style) const
\brief Get the type of each field in the date format of the locale. \brief Get the type of each field in the date format of the locale.
This function is most often used in combination with FormatDate(). This method is most often used in combination with FormatDate().
FormatDate() gives you the offset of each field in a formatted string, 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. and GetDateFields() gives you the type of the field at a given offset.
With these informations, you can handle the formatted date string as With these informations, you can handle the formatted date string as
@ -240,9 +247,9 @@
\returns A status code. \returns A status code.
\retval B_OK Everything went fine. \retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error getting the date \retval B_ERROR Unable to lock the BLocale.
fields.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. \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, \sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
BTimeFormatStyle style) const BTimeFormatStyle style) const
@ -250,14 +257,22 @@
/*! /*!
\fn int BLocale::StartOfWeek() const \fn status_t BLocale::GetStartOfWeek(BWeekday* startOfWeek) const
\brief Returns the number of the day used as start of week in this locale. \brief Returns the day used as the start of week in this locale.
\returns a flag that indicates the day of the week that the week starts or Possible values for \a startOfWeek include:
B_ERROR if there was an error. - \c B_WEEKDAY_SUNDAY
\retval B_ERROR Unable to lock the BLocale. - \c B_WEEKDAY_MONDAY
\retval B_WEEK_START_SUNDAY If the beginning of the week starts on Sunday. - \c B_WEEKDAY_TUESDAY
\retval B_WEEK_START_MONDAY If the beginning of the week starts on Monday. - \c B_WEEKDAY_WEDNESDAY
- \c B_WEEKDAY_THURSDAY
- \c B_WEEKDAY_THURSDAY
- \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.
*/ */
@ -373,8 +388,9 @@
\returns A status code. \returns A status code.
\retval B_OK Everything went fine. \retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error formatting the time. \retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. \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, \sa BLocale::FormatDate(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BDateFormatStyle style) const int& fieldCount, time_t time, BDateFormatStyle style) const
@ -386,10 +402,10 @@
BTimeFormatStyle style) const BTimeFormatStyle style) const
\brief Get the type of each field in the time format of the locale. \brief Get the type of each field in the time format of the locale.
This function is most often used in combination with FormatTime(). This method is used most often in combination with FormatTime().
FormatTime() gives you the offset of each field in a formatted string, 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. and GetTimeFields() gives you the type of the field at a given offset.
With these informations, you can handle the formatted date string as With this information you can handle the formatted date string as
a list of fields that you can split and alter at will. a list of fields that you can split and alter at will.
\param fields Pointer to the fields object. \param fields Pointer to the fields object.
@ -398,9 +414,9 @@
\returns A status code. \returns A status code.
\retval B_OK Everything went fine. \retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error getting the time \retval B_ERROR Unable to lock the BLocale.
fields.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. \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, \sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
BDateFormatStyle style) const BDateFormatStyle style) const
@ -417,8 +433,11 @@
\param maxSize The maximum of bytes to copy into \a string. \param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a formatted version of. \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 in \returns The length of the string created or an error status code.
the case of an error. \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, \sa BLocale::FormatNumber(char* string, size_t maxSize,
int32 value) const int32 value) const
@ -429,14 +448,18 @@
/*! /*!
\fn status_t BLocale::FormatNumber(BString* string, 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 \brief \brief Format the \c double \a value as a string and put the
into \a string in the current locale. result into \a string in the current locale.
\param string The string to put the formatted number into. \param string The string to put the formatted number into.
\param value The number that you want to get a formatted version of. \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 in \returns A status code.
the case of an error. \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::FormatNumber(BString* string, int32 value) const
\sa BLocale::FormatMonetary(BString* string, double value) const \sa BLocale::FormatMonetary(BString* string, double value) const
@ -453,8 +476,11 @@
\param maxSize The maximum of bytes to copy into \a string. \param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a formatted version of. \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 in \returns The length of the string created or an error status code.
the case of an error. \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, \sa BLocale::FormatNumber(char* string, size_t maxSize,
double value) const double value) const
@ -471,8 +497,12 @@
\param string The string to put the formatted number into. \param string The string to put the formatted number into.
\param value The number that you want to get a formatted version of. \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 in \returns A status code.
the case of an error. \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, double value) const
\sa BLocale::FormatMonetary(BString* string, double value) const \sa BLocale::FormatMonetary(BString* string, double value) const
@ -485,18 +515,18 @@
\brief Format the \c double \a value as a monetary string and put the \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. result into \a string up to \a maxSize bytes in the current locale.
\param string The string to put the monetary formatted number into. \param string The \a string to put the monetary formatted number into.
\param maxSize The maximum of bytes to copy into \a string. \param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a monetary formatted version \param value The number to format as a monetary \a value.
of.
\returns The length of the string created or an error status code in \returns The length of the string created or an error status code.
the case of an error. \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, \sa BLocale::FormatNumber(char* string, size_t maxSize, double value) const
double value) const \sa BLocale::FormatNumber(char* string, size_t maxSize, int32 value) const
\sa BLocale::FormatNumber(char* string, size_t maxSize,
int32 value) const
*/ */
@ -505,12 +535,15 @@
\brief \brief Format the \c double \a value as a monetary string and put \brief \brief Format the \c double \a value as a monetary string and put
the result into \a string in the current locale. the result into \a string in the current locale.
\param string The string to put the monetary formatted number into. \param string The \a string to put the monetary formatted number into.
\param value The number that you want to get a monetary formatted version \param value The number to format as a monetary \a value.
of.
\returns The length of the string created or an error status code in \returns A status code.
the case of an error. \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, double value) const
\sa BLocale::FormatNumber(BString* string, int32 value) const \sa BLocale::FormatNumber(BString* string, int32 value) const

48
src/kits/locale/Locale.cpp
View File

@ -109,7 +109,7 @@ BLocale::GetLanguage(BLanguage* language) const
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
*language = fLanguage; *language = fLanguage;
@ -125,7 +125,7 @@ BLocale::GetFormattingConventions(BFormattingConventions* conventions) const
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
*conventions = fConventions; *conventions = fConventions;
@ -194,7 +194,7 @@ BLocale::FormatDate(char* string, size_t maxSize, time_t time,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(style, format); fConventions.GetDateFormat(style, format);
@ -221,7 +221,7 @@ BLocale::FormatDate(BString *string, time_t time, BDateFormatStyle style,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(style, format); fConventions.GetDateFormat(style, format);
@ -254,7 +254,7 @@ BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(style, format); fConventions.GetDateFormat(style, format);
@ -270,7 +270,7 @@ BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount,
error); error);
if (error != U_ZERO_ERROR) if (error != U_ZERO_ERROR)
return B_ERROR; return B_BAD_VALUE;
icu::FieldPosition field; icu::FieldPosition field;
std::vector<int> fieldPosStorage; std::vector<int> fieldPosStorage;
@ -301,7 +301,7 @@ BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(style, format); fConventions.GetDateFormat(style, format);
@ -318,7 +318,7 @@ BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
&positionIterator, error); &positionIterator, error);
if (U_FAILURE(error)) if (U_FAILURE(error))
return B_ERROR; return B_BAD_VALUE;
icu::FieldPosition field; icu::FieldPosition field;
std::vector<int> fieldPosStorage; std::vector<int> fieldPosStorage;
@ -359,7 +359,7 @@ BLocale::GetStartOfWeek(BWeekday* startOfWeek) const
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
UErrorCode err = U_ZERO_ERROR; UErrorCode err = U_ZERO_ERROR;
ObjectDeleter<Calendar> calendar = Calendar::createInstance( ObjectDeleter<Calendar> calendar = Calendar::createInstance(
@ -395,7 +395,7 @@ BLocale::GetStartOfWeek(BWeekday* startOfWeek) const
*startOfWeek = B_WEEKDAY_SATURDAY; *startOfWeek = B_WEEKDAY_SATURDAY;
break; break;
default: default:
return B_BAD_DATA; return B_ERROR;
} }
return B_OK; return B_OK;
@ -408,7 +408,7 @@ BLocale::FormatDateTime(char* target, size_t maxSize, time_t time,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(dateStyle, format); fConventions.GetDateFormat(dateStyle, format);
@ -445,7 +445,7 @@ BLocale::FormatDateTime(BString* target, time_t time,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetDateFormat(dateStyle, format); fConventions.GetDateFormat(dateStyle, format);
@ -488,7 +488,7 @@ BLocale::FormatTime(char* string, size_t maxSize, time_t time,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetTimeFormat(style, format); fConventions.GetTimeFormat(style, format);
@ -515,7 +515,7 @@ BLocale::FormatTime(BString* string, time_t time, BTimeFormatStyle style,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetTimeFormat(style, format); fConventions.GetTimeFormat(style, format);
@ -548,7 +548,7 @@ BLocale::FormatTime(BString* string, int*& fieldPositions, int& fieldCount,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetTimeFormat(style, format); fConventions.GetTimeFormat(style, format);
@ -564,7 +564,7 @@ BLocale::FormatTime(BString* string, int*& fieldPositions, int& fieldCount,
error); error);
if (error != U_ZERO_ERROR) if (error != U_ZERO_ERROR)
return B_ERROR; return B_BAD_VALUE;
icu::FieldPosition field; icu::FieldPosition field;
std::vector<int> fieldPosStorage; std::vector<int> fieldPosStorage;
@ -594,7 +594,7 @@ BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
BString format; BString format;
fConventions.GetTimeFormat(style, format); fConventions.GetTimeFormat(style, format);
@ -611,7 +611,7 @@ BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
&positionIterator, error); &positionIterator, error);
if (error != U_ZERO_ERROR) if (error != U_ZERO_ERROR)
return B_ERROR; return B_BAD_VALUE;
icu::FieldPosition field; icu::FieldPosition field;
std::vector<int> fieldPosStorage; std::vector<int> fieldPosStorage;
@ -670,7 +670,7 @@ BLocale::FormatNumber(BString* string, double value) const
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
UErrorCode err = U_ZERO_ERROR; UErrorCode err = U_ZERO_ERROR;
ObjectDeleter<NumberFormat> numberFormatter(NumberFormat::createInstance( ObjectDeleter<NumberFormat> numberFormatter(NumberFormat::createInstance(
@ -680,7 +680,7 @@ BLocale::FormatNumber(BString* string, double value) const
if (numberFormatter.Get() == NULL) if (numberFormatter.Get() == NULL)
return B_NO_MEMORY; return B_NO_MEMORY;
if (U_FAILURE(err)) if (U_FAILURE(err))
return B_ERROR; return B_BAD_VALUE;
UnicodeString icuString; UnicodeString icuString;
numberFormatter->format(value, icuString); numberFormatter->format(value, icuString);
@ -710,7 +710,7 @@ BLocale::FormatNumber(BString* string, int32 value) const
{ {
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
UErrorCode err = U_ZERO_ERROR; UErrorCode err = U_ZERO_ERROR;
ObjectDeleter<NumberFormat> numberFormatter(NumberFormat::createInstance( ObjectDeleter<NumberFormat> numberFormatter(NumberFormat::createInstance(
@ -720,7 +720,7 @@ BLocale::FormatNumber(BString* string, int32 value) const
if (numberFormatter.Get() == NULL) if (numberFormatter.Get() == NULL)
return B_NO_MEMORY; return B_NO_MEMORY;
if (U_FAILURE(err)) if (U_FAILURE(err))
return B_ERROR; return B_BAD_VALUE;
UnicodeString icuString; UnicodeString icuString;
numberFormatter->format((int32_t)value, icuString); numberFormatter->format((int32_t)value, icuString);
@ -753,7 +753,7 @@ BLocale::FormatMonetary(BString* string, double value) const
BAutolock lock(fLock); BAutolock lock(fLock);
if (!lock.IsLocked()) if (!lock.IsLocked())
return B_WOULD_BLOCK; return B_ERROR;
UErrorCode err = U_ZERO_ERROR; UErrorCode err = U_ZERO_ERROR;
ObjectDeleter<NumberFormat> numberFormatter( ObjectDeleter<NumberFormat> numberFormatter(
@ -764,7 +764,7 @@ BLocale::FormatMonetary(BString* string, double value) const
if (numberFormatter.Get() == NULL) if (numberFormatter.Get() == NULL)
return B_NO_MEMORY; return B_NO_MEMORY;
if (U_FAILURE(err)) if (U_FAILURE(err))
return B_ERROR; return B_BAD_VALUE;
UnicodeString icuString; UnicodeString icuString;
numberFormatter->format(value, icuString); numberFormatter->format(value, icuString);