docs/user/locale/TimeFormat.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/TimeFormat.h  hrev48439
  11  *              src/kits/locale/TimeFormat.cpp  hrev48439
  12  */
  13
  14
  15 /*!
  16         \file TimeFormat.h
  17         \ingroup locale
  18         \ingroup libbe
  19         \brief Contains BTimeFormat class, a time formatter and parser.
  20 */
  21
  22
  23 /*!
  24         \class BTimeFormat
  25         \ingroup locale
  26         \ingroup libbe
  27         \brief Formatter for times.
  28
  29         \since Haiku R1
  30 */
  31
  32
  33 /*!
  34         \fn BTimeFormat::BTimeFormat()
  35         \brief Default Constructor. The current system locale is used.
  36
  37         \since Haiku R1
  38 */
  39
  40
  41 /*!
  42         \fn BTimeFormat::BTimeFormat(const BLanguage& language,
  43                 const BFormattingConventions& format);
  44         \brief Language and formatting convention constructor.
  45
  46         \param language The \a language to use.
  47         \param format The formatting convention to use.
  48
  49         \since Haiku R1
  50 */
  51
  52
  53 /*!
  54         \fn BTimeFormat::BTimeFormat(const BTimeFormat& other)
  55         \brief Copy Constructor.
  56
  57         \param other The BTimeFormat object to copy from.
  58
  59         \since Haiku R1
  60 */
  61
  62
  63 /*!
  64         \fn BTimeFormat::~BTimeFormat()
  65         \brief Destructor.
  66
  67         \since Haiku R1
  68 */
  69
  70
  71 /*!
  72         \fn ssize_t BTimeFormat::Format(char* string, size_t maxSize, time_t time,
  73                 BTimeFormatStyle style) const
  74         \brief Fills in \a string with a formatted time up to \a maxSize bytes for
  75                the given \a time and \a style for the locale.
  76
  77         \param string The string buffer to fill with the formatted time.
  78         \param maxSize The size of the buffer.
  79         \param time The time (in seconds since midnight) to format.
  80         \param style Specify the long format or the short format.
  81
  82         \returns The number of bytes written during the time formatting.
  83         \retval B_ERROR Unable to lock the BLocale.
  84         \retval B_NO_MEMORY Ran out of memory while creating the object.
  85         \retval B_BAD_VALUE There was not enough space to store the result.
  86
  87         \since Haiku R1
  88 */
  89
  90
  91 /*!
  92         \fn status_t BTimeFormat::Format(char* string, size_t maxSize,
  93                 time_t time, BTimeFormatStyle style) const
  94         \brief Fills in \a string with a formatted time for the given
  95                \a time, and \a style for the locale.
  96
  97         \param string The string buffer to fill with the formatted time.
  98         \param time The time (in seconds since midnight) to format.
  99         \param style Specify the long format or the short format.
 100
 101         \returns A status code.
 102         \retval B_OK Everything went fine.
 103         \retval B_ERROR Unable to lock the BLocale.
 104         \retval B_NO_MEMORY Ran out of memory while creating the object.
 105
 106         \sa BLocale::FormatDate(BString*, time_t, BTimeFormatStyle,
 107                 const BTimeZone*) const
 108         \sa BLocale::FormatDateTime(BString*, time_t, BTimeFormatStyle,
 109                 BTimeFormatStyle, const BTimeZone*) const
 110
 111         \since Haiku R1
 112 */
 113
 114
 115 /*!
 116         \fn status_t BTimeFormat::Format(BString& string, const time_t time,
 117                 const BTimeFormatStyle style, const BTimeZone* timeZone) const
 118         \brief Fills in \a string with a formatted time for the given
 119                \a time, \a style, and \a timeZone for the locale.
 120
 121         \param string The string buffer to fill with the formatted time.
 122         \param time The time (in seconds since epoch) to format.
 123         \param style Specifies whether to use the long format or short format.
 124         \param timeZone Specifies the time zone to use, if \c NULL, use the
 125                system default time zone (usually UTC).
 126
 127         \returns A status code.
 128         \retval B_OK Everything went fine.
 129         \retval B_ERROR Unable to lock the BLocale.
 130         \retval B_NO_MEMORY Ran out of memory while creating the object.
 131         \retval B_BAD_VALUE There was not enough space to store the result.
 132
 133         \since Haiku R1
 134 */
 135
 136
 137 /*!
 138         \fn status_t BTimeFormat::Format(BString& string, int*& fieldPositions,
 139                 int& fieldCount, time_t time, BTimeFormatStyle style) const
 140         \brief Fills in \a string with a custom formatted date according to the
 141                given parameters for the locale and fills out an array of
 142                \a fieldPositions which must be freed by the caller and a
 143                \a fieldCount which contains the number of positions.
 144
 145         The positions are offsets in the string at which each element of the time
 146         (hour, minute, second, etc) and the separator starting positions. These
 147         can be used, for example, to split the string in parts to use in a
 148         locale-aware set of BMenuFields to edit the time in the local format.
 149
 150         \param string The string buffer to fill with the formatted time.
 151         \param fieldPositions An array of time field positions to be filled out.
 152         \param fieldCount The number of \a fields in \a fieldPositions to be
 153                filled out.
 154         \param time The time (in seconds since epoch) to format.
 155         \param style Specify the long format (with day name, full
 156                 month name) or the short format, 08/12/2010 or similar.
 157
 158         \returns A status code.
 159         \retval B_OK Everything went fine.
 160         \retval B_ERROR Unable to lock the BLocale.
 161         \retval B_NO_MEMORY Ran out of memory while creating the object.
 162         \retval B_BAD_VALUE There was not enough space to store the result.
 163
 164         \since Haiku R1
 165 */
 166
 167
 168 /*!
 169         \fn status_t BTimeFormat::GetTimeFields(BDateElement*& fields, int& fieldCount,
 170                 BTimeFormatStyle style) const
 171         \brief Get the type of each field in the time format of the locale.
 172
 173         This method is used most often in combination with FormatTime().
 174         FormatTime() gives you the offset of each field in a formatted string,
 175         and GetTimeFields() gives you the type of the field at a given offset.
 176         With this information you can handle the formatted time string as
 177         a list of fields that you can split and alter at will.
 178
 179         \param fields Pointer to the fields object.
 180         \param fieldCount The number of fields.
 181         \param style Specify the long format or the short format.
 182
 183         \returns A status code.
 184         \retval B_OK Everything went fine.
 185         \retval B_ERROR Unable to lock the BLocale.
 186         \retval B_NO_MEMORY Ran out of memory while creating the object.
 187         \retval B_BAD_VALUE Bad or invalid \a fields data.
 188
 189         \since Haiku R1
 190 */