a8081885d2
This version generates some warnings and identified some problems in our documentation. It is also a bit more vigilant about undocumented elements, so these are now decorated with a brief description. In the BNotification docs I used a stray \p to create some whitespace between code and an image. This is now fixed in the CSS instead.
167 lines
4.9 KiB
Plaintext
167 lines
4.9 KiB
Plaintext
/*
|
|
* 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/TimeFormat.h hrev48439
|
|
* src/kits/locale/TimeFormat.cpp hrev48439
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file TimeFormat.h
|
|
\ingroup locale
|
|
\ingroup libbe
|
|
\brief Contains BTimeFormat class, a time formatter and parser.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BTimeFormat
|
|
\ingroup locale
|
|
\ingroup libbe
|
|
\brief Formatter for times.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BTimeFormat::BTimeFormat()
|
|
\brief Default Constructor. The current system locale is used.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 time 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 midnight) 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 object.
|
|
\retval B_BAD_VALUE There was not enough space to store the result.
|
|
|
|
\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, \a style, and \a timeZone 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 Specifies whether to use the long format or short format.
|
|
\param timeZone Specifies the time zone to use, if \c NULL, use the
|
|
system default time zone (usually UTC).
|
|
|
|
\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 object.
|
|
\retval B_BAD_VALUE There was not enough space to store the result.
|
|
|
|
\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 custom formatted date according to the
|
|
given parameters for the locale and fills out an array of
|
|
\a fieldPositions which must be freed by the caller and a
|
|
\a fieldCount which contains the number of positions.
|
|
|
|
The positions are offsets in the string at which each element of the time
|
|
(hour, minute, second, etc) and the separator starting positions. These
|
|
can be used, for example, to split the string in parts to use in a
|
|
locale-aware set of BMenuFields to edit the time in the local format.
|
|
|
|
\param string The string buffer to fill with the formatted time.
|
|
\param fieldPositions An array of time field positions to be filled out.
|
|
\param fieldCount The number of \a fields in \a fieldPositions to be
|
|
filled out.
|
|
\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 object.
|
|
\retval B_BAD_VALUE There was not enough space to store the result.
|
|
|
|
\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 time 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 object.
|
|
\retval B_BAD_VALUE Bad or invalid \a fields data.
|
|
|
|
\since Haiku R1
|
|
*/
|