docs/user/locale/DateFormat.dox

   1 /*
   2  * Copyright 2011-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.ath.cx
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/locale/DateFormat.h  hrev48439
  11  *              src/kits/locale/DateFormat.cpp  hrev48439
  12  */
  13
  14
  15 /*!
  16         \file DateFormat.h
  17         \ingroup locale
  18         \ingroup libbe
  19         \brief Contains BDateFormat class, a date formatter and parser.
  20 */
  21
  22
  23 /*!
  24         \class BDateFormat
  25         \ingroup locale
  26         \ingroup libbe
  27         \brief Formatter for dates.
  28
  29         \since Haiku R1
  30 */
  31
  32
  33 /*!
  34         \fn BDateFormat::BDateFormat(const BLocale* locale)
  35         \brief Locale constructor.
  36
  37         \param locale The locale to use, can be \c NULL for the default locale.
  38
  39         \since Haiku R1
  40 */
  41
  42
  43 /*!
  44         \fn BDateFormat::BDateFormat(const BLanguage& language,
  45                 const BFormattingConventions& format);
  46         \brief Language and formatting convention constructor.
  47
  48         \param language The \a language to use.
  49         \param format The formatting convention to use.
  50
  51         \since Haiku R1
  52 */
  53
  54
  55 /*!
  56         \fn BDateFormat::BDateFormat(const BDateFormat& other)
  57         \brief Copy Constructor.
  58
  59         \param other The BDateFormat object to copy from.
  60
  61         \since Haiku R1
  62 */
  63
  64
  65 /*!
  66         \fn BDateFormat::~BDateFormat()
  67         \brief Destructor.
  68
  69         \since Haiku R1
  70 */
  71
  72
  73 /*!
  74         \fn ssize_t BDateFormat::Format(char* string, const size_t maxSize,
  75                 const time_t time, const BDateFormatStyle style) const
  76         \brief Fills in \a string with a formatted date up to \a maxSize bytes for
  77                the given \a time and \a style for the locale.
  78
  79         \param string The string buffer to fill with the formatted date.
  80         \param maxSize The size of the buffer.
  81         \param time The time (in seconds since epoch) to format
  82         \param style Specify the long format (with day name, full
  83                month name) or the short format, 08/12/2010 or similar.
  84
  85         \returns The number of bytes written during the date formatting.
  86         \retval B_ERROR Unable to lock the BLocale.
  87         \retval B_NO_MEMORY Ran out of memory while creating the object.
  88         \retval B_BAD_VALUE There was not enough space to store the result.
  89
  90         \since Haiku R1
  91 */
  92
  93
  94 /*!
  95         \fn status_t BDateFormat::Format(BString& string, const time_t time,
  96                 const BDateFormatStyle style, const BTimeZone* timeZone) const
  97         \brief Fills in \a string with a formatted date for the given
  98                \a time, \a style, and \a timeZone for the locale.
  99
 100         \param string The string buffer to fill with the formatted date.
 101         \param time The time (in seconds since epoch) to format
 102         \param style Specify the long format (with day name, full
 103                 month name) or the short format, 08/12/2010 or similar.
 104         \param timeZone Specifies the time zone to use, if \c NULL, use the
 105                system default time zone (usually UTC).
 106
 107         \returns A status code.
 108         \retval B_OK Everything went fine.
 109         \retval B_ERROR Unable to lock the BLocale.
 110         \retval B_NO_MEMORY Ran out of memory while creating the object.
 111
 112         \since Haiku R1
 113 */
 114
 115
 116 /*!
 117         \fn status_t BDateFormat::Format(BString& string,
 118                 int*& fieldPositions, int& fieldCount, const time_t time,
 119                 const BDateFormatStyle style) const
 120         \brief Fills in \a string with a custom formatted date according to the
 121                given parameters for the locale and fills out an array of
 122                \a fieldPositions which must be freed by the caller and a
 123                \a fieldCount which contains the number of positions.
 124
 125         The positions are offsets in the string at which each element of the date
 126         (day, month, year, etc) and the separator starting positions. These
 127         can be used, for example, to split the string into parts to use in a
 128         locale-aware set of BMenuFields to edit the date in the local format.
 129
 130         \param string The string buffer to fill with the formatted date.
 131         \param fieldPositions An array of date field positions to be filled out.
 132         \param fieldCount The number of \a fields in \a fieldPositions to be
 133                filled out.
 134         \param time The time (in seconds since epoch) to format
 135         \param style Specify the long format (with day name, full
 136                 month name) or the short format, 08/12/2010 or similar.
 137
 138         \returns A status code.
 139         \retval B_OK Everything went fine.
 140         \retval B_ERROR Unable to lock the BLocale.
 141         \retval B_NO_MEMORY Ran out of memory while creating the \a string buffer
 142                 or \a fieldPositions array.
 143         \retval B_BAD_VALUE There was not enough space to store the result.
 144
 145         \since Haiku R1
 146 */
 147
 148
 149 /*!
 150         \fn status_t BDateFormat::GetFields(BDateElement*& fields, int& fieldCount,
 151                 BDateFormatStyle style) const
 152         \brief Get the type of each field in the date format of the locale.
 153
 154         This method is most often used in combination with the version of Format()
 155         that takes a fieldPositions parameter. Format() gives you the offset of
 156         each field in a formatted string, and GetFields() gives you the type of
 157         the field at a given offset. With these informations, you can handle the
 158         formatted date string as a list of fields that you can split and alter at
 159         will.
 160
 161         \param fields Pointer to the array of BDateElement objects.
 162         \param fieldCount The number of fields in \a fields.
 163         \param style Specify the long format (with day name, full month name)
 164                or the short format, "08/12/2010" or similar.
 165
 166         \returns A status code.
 167         \retval B_OK Everything went fine.
 168         \retval B_ERROR Unable to lock the BLocale.
 169         \retval B_NO_MEMORY Ran out of memory while creating the object.
 170         \retval B_BAD_VALUE Bad or invalid \a fields data.
 171
 172         \sa BDateFormat::GetFields(BDateElement*&, int&, BTimeFormatStyle) const
 173         \sa BDateFormat::Format(BString&, int*&, int&, const time_t,
 174                 const BDateFormatStyle) const
 175
 176         \since Haiku R1
 177 */
 178
 179
 180 /*!
 181         \fn status_t BDateFormat::GetStartOfWeek(BWeekday* startOfWeek) const
 182         \brief Returns the day used as the start of week in this locale.
 183
 184         Possible values for \a startOfWeek include:
 185                 - \c B_WEEKDAY_SUNDAY
 186                 - \c B_WEEKDAY_MONDAY
 187                 - \c B_WEEKDAY_TUESDAY
 188                 - \c B_WEEKDAY_WEDNESDAY
 189                 - \c B_WEEKDAY_THURSDAY
 190                 - \c B_WEEKDAY_FRIDAY
 191                 - \c B_WEEKDAY_SATURDAY
 192
 193         \returns A status code.
 194         \retval B_OK Everything went fine.
 195         \retval B_BAD_VALUE \a startOfWeek is \c NULL.
 196         \retval B_ERROR Unable to lock the BLocale or another error occurred.
 197
 198         \since Haiku R1
 199 */