diff --git a/docs/user/locale/DateFormat.dox b/docs/user/locale/DateFormat.dox new file mode 100644 index 0000000000..fe9a9f8772 --- /dev/null +++ b/docs/user/locale/DateFormat.dox @@ -0,0 +1,183 @@ +/* + * Copyright 2011-2014 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/locale/DateFormat.h hrev48439 + * src/kits/locale/DateFormat.cpp hrev48439 + */ + + +/*! + \file DateFormat.h + \ingroup locale + \ingroup libbe + \brief Contains BDateFormat class, a date formatter. +*/ + + +/*! + \class BDateFormat + \ingroup locale + \ingroup libbe + \brief Formatter for dates. + + \since Haiku R1 +*/ + + +/*! + \fn BDateFormat::BDateFormat(const BLocale* locale) + \brief Locale constructor. + + \param locale The locale to use, can be \c NULL for the default locale. +*/ + + +/*! + \fn BDateFormat::BDateFormat(const BLanguage& language, + const BFormattingConventions& format); + \brief Language and formatting convention constructor. + + \param language The \a language to use. + \param format The formatting convention to use. +*/ + + +/*! + \fn BDateFormat::BDateFormat(const BDateFormat& other) + \brief Copy Constructor. + + \param other The BDateFormat object to copy from. + + \since Haiku R1 +*/ + + +/*! + \fn BDateFormat::~BDateFormat() + \brief Destructor. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BDateFormat::Format(char* string, const size_t maxSize, + const time_t time, const 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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BDateFormat::Format(BString& string, const time_t time, + const 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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BDateFormat::Format(BString& string, + int*& fieldPositions, int& fieldCount, const time_t time, + const 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 An array of date field positions to use. + \param fieldCount The number of \a fields in \a fieldPositions. + \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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BDateFormat::GetFields(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 BDateFormat::GetTimeFields(BDateElement*& fields, int& fieldCount, + BTimeFormatStyle style) const + + \since Haiku R1 +*/ + + +/*! + \fn status_t BDateFormat::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 +*/ diff --git a/docs/user/locale/DateTimeFormat.dox b/docs/user/locale/DateTimeFormat.dox new file mode 100644 index 0000000000..d3a2cf39c0 --- /dev/null +++ b/docs/user/locale/DateTimeFormat.dox @@ -0,0 +1,110 @@ +/* + * Copyright 2011-2014 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/locale/DateFormat.h hrev48439 + * src/kits/locale/DateFormat.cpp hrev48439 + */ + + +/*! + \file DateFormat.h + \ingroup locale + \ingroup libbe + \brief Contains BDateTimeFormat class, a date formatter. +*/ + + +/*! + \class BDateTimeFormat + \ingroup locale + \ingroup libbe + \brief Formatter for dates. + + \since Haiku R1 +*/ + + +/*! + \fn BDateTimeFormat::BDateTimeFormat(const BLocale* locale) + \brief Locale constructor. + + \param locale The locale to use, can be \c NULL for the default locale. +*/ + + +/*! + \fn BDateTimeFormat::BDateTimeFormat(const BLanguage& language, + const BFormattingConventions& format); + \brief Language and formatting convention constructor. + + \param language The \a language to use. + \param format The formatting convention to use. +*/ + + +/*! + \fn BDateTimeFormat::BDateTimeFormat(const BDateTimeFormat& other) + \brief Copy Constructor. + + \param other The BDateTimeFormat object to copy from. + + \since Haiku R1 +*/ + + +/*! + \fn BDateTimeFormat::~BDateTimeFormat() + \brief Destructor. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BDateTimeFormat::Format(char* target, const size_t maxSize, + const 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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BDateTimeFormat::Format(BString& buffer, const 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 buffer 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. + + \since Haiku R1 +*/ diff --git a/docs/user/locale/DurationFormat.dox b/docs/user/locale/DurationFormat.dox index bcdf0f0e61..33ed7b4c66 100644 --- a/docs/user/locale/DurationFormat.dox +++ b/docs/user/locale/DurationFormat.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -7,8 +7,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/locale/DurationFormat.h hrev45084 - * src/kits/locale/DurationFormat.cpp hrev45084 + * headers/os/locale/DurationFormat.h hrev48439 + * src/kits/locale/DurationFormat.cpp hrev48439 */ @@ -65,18 +65,6 @@ */ -/*! - \fn BDurationFormat& BDurationFormat::operator=(const BDurationFormat& other) - \brief Assignment overload. - - \param other The BDurationFormat object to copy from. - - \returns The resulting BDurationFormat object. - - \since Haiku R1 -*/ - - /*! \fn void BDurationFormat::SetSeparator(const BString& separator) \brief Replace the separator for this formatter. @@ -87,18 +75,6 @@ */ -/*! - \fn status_t BDurationFormat::SetLocale(const BLocale* locale) - \brief Sets the locale for this formatter. - - \param locale The BLocale object to set. - - \returns A status code, \c B_OK on success or an error code on error. - - \since Haiku R1 -*/ - - /*! \fn status_t BDurationFormat::SetTimeZone(const BTimeZone* timeZone) \brief Sets the timezone for this formatter. diff --git a/docs/user/locale/Locale.dox b/docs/user/locale/Locale.dox index 5b6343c04b..ec99166834 100644 --- a/docs/user/locale/Locale.dox +++ b/docs/user/locale/Locale.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Oliver Tappe, zooey@hirschkaefer.de. * * Corresponds to: - * headers/os/locale/Locale.h rev 43095 - * src/kits/locale/Locale.cpp rev 43095 + * headers/os/locale/Locale.h hrev48439 + * src/kits/locale/Locale.cpp hrev48439 */ @@ -190,432 +190,3 @@ \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 -*/ diff --git a/docs/user/locale/NumberFormat.dox b/docs/user/locale/NumberFormat.dox new file mode 100644 index 0000000000..199a4492e1 --- /dev/null +++ b/docs/user/locale/NumberFormat.dox @@ -0,0 +1,190 @@ +/* + * Copyright 2011-2014 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/locale/NumberFormat.h hrev48439 + * src/kits/locale/NumberFormat.cpp hrev48439 + */ + + +/*! + \file NumberFormat.h + \ingroup locale + \ingroup libbe + \brief Contains BNumberFormat class, a number formatter. +*/ + + +/*! + \class BNumberFormat + \ingroup locale + \ingroup libbe + \brief Formatter for numbers and monetary values. + + \since Haiku R1 +*/ + + +/*! + \fn BNumberFormat::BNumberFormat(const BNumberFormat& other) + \brief Copy Constructor. + + \param other The BNumberFormat object to copy from. + + \since Haiku R1 +*/ + + +/*! + \fn BNumberFormat::~BNumberFormat() + \brief Destructor. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BNumberFormat::Format(char* string, size_t maxSize, + const 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 BNumberFormat. + \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 BNumberFormat::Format(char* string, size_t maxSize, + int32 value) const + \sa ssize_t BNumberFormat::FormatMonetary(char* string, size_t maxSize, + double value) const + + \since Haiku R1 +*/ + + +/*! + \fn status_t BNumberFormat::Format(BString& string, + const 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 BNumberFormat. + \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 BNumberFormat::Format(BString* string, int32 value) const + \sa BNumberFormat::FormatMonetary(BString* string, double value) const + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BNumberFormat::Format(char* string, size_t maxSize, + const 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 BNumberFormat. + \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 BNumberFormat::Format(char* string, size_t maxSize, + double value) const + \sa BNumberFormat::FormatMonetary(char* string, size_t maxSize, + double value) const + + \since Haiku R1 +*/ + + +/*! + \fn status_t BNumberFormat::Format(BString& string, + const 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 BNumberFormat. + \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 BNumberFormat::Format(BString* string, double value) const + \sa BNumberFormat::FormatMonetary(BString* string, double value) const + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BNumberFormat::FormatMonetary(char* string, size_t maxSize, + const 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 BNumberFormat. + \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 BNumberFormat::Format(char* string, size_t maxSize, double value) const + \sa BNumberFormat::Format(char* string, size_t maxSize, int32 value) const + + \since Haiku R1 +*/ + + +/*! + \fn status_t BNumberFormat::FormatMonetary(BString& string, + const 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 BNumberFormat. + \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 BNumberFormat::Format(BString* string, double value) const + \sa BNumberFormat::Format(BString* string, int32 value) const + + \since Haiku R1 +*/ diff --git a/docs/user/locale/TimeFormat.dox b/docs/user/locale/TimeFormat.dox new file mode 100644 index 0000000000..7e914ca26b --- /dev/null +++ b/docs/user/locale/TimeFormat.dox @@ -0,0 +1,179 @@ +/* + * Copyright 2011-2014 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/locale/DateFormat.h hrev48439 + * src/kits/locale/DateFormat.cpp hrev48439 + */ + + +/*! + \file DateFormat.h + \ingroup locale + \ingroup libbe + \brief Contains BTimeFormat class, a date formatter. +*/ + + +/*! + \class BTimeFormat + \ingroup locale + \ingroup libbe + \brief Formatter for dates. + + \since Haiku R1 +*/ + + +/*! + \fn BTimeFormat::BTimeFormat() + \brief Constructor. +*/ + + +/*! + \fn BTimeFormat::BTimeFormat(const BLanguage& language, + const BFormattingConventions& format); + \brief Language and formatting convention constructor. + + \param language The \a language to use. + \param format The formatting convention to use. +*/ + + +/*! + \fn BTimeFormat::BTimeFormat(const BTimeFormat& other) + \brief Copy Constructor. + + \param other The BTimeFormat object to copy from. + + \since Haiku R1 +*/ + + +/*! + \fn BTimeFormat::~BTimeFormat() + \brief Destructor. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t BTimeFormat::Format(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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BTimeFormat::Format(char* string, size_t maxSize, + time_t time, BTimeFormatStyle style) 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. + + \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, + BTimeFormatStyle style, const BTimeZone* timeZone) const + \sa BLocale::FormatDateTime(BString* target, time_t time, + BTimeFormatStyle dateStyle, BTimeFormatStyle timeStyle, + const BTimeZone* timeZone) const + + \since Haiku R1 +*/ + + +/*! + \fn status_t BTimeFormat::Format(BString& string, const time_t time, + const BTimeFormatStyle style, const BTimeZone* timeZone) 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 time The time (in seconds since epoch) to format. + \param style Specify the long format or the short format. + \param timeZone The time zone to use, if \c NULL, uses the one set by the + locale. + + \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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BTimeFormat::Format(BString& string, + int*& fieldPositions, int& fieldCount, + time_t time, BTimeFormatStyle style) const + \brief Fills in \a string with a formatted time for the given parameters. + + \param string The string buffer to fill with the formatted date. + \param fieldPositions An array of date field positions to use. + \param fieldCount The number of \a fields in \a fieldPositions. + \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. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BTimeFormat::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. + + \since Haiku R1 +*/ diff --git a/headers/os/locale/NumberFormat.h b/headers/os/locale/NumberFormat.h index 98906a4805..ed39e75e36 100644 --- a/headers/os/locale/NumberFormat.h +++ b/headers/os/locale/NumberFormat.h @@ -19,9 +19,9 @@ enum BNumberElement { class BNumberFormat : public BFormat { public: - BNumberFormat(); - BNumberFormat(const BNumberFormat &other); - ~BNumberFormat(); + BNumberFormat(); + BNumberFormat(const BNumberFormat &other); + ~BNumberFormat(); // formatting