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*/ 191