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