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. 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 40 41/*! 42 \fn BDateFormat::BDateFormat(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 50 51/*! 52 \fn BDateFormat::BDateFormat(const BDateFormat& other) 53 \brief Copy Constructor. 54 55 \param other The BDateFormat object to copy from. 56 57 \since Haiku R1 58*/ 59 60 61/*! 62 \fn BDateFormat::~BDateFormat() 63 \brief Destructor. 64 65 \since Haiku R1 66*/ 67 68 69/*! 70 \fn ssize_t BDateFormat::Format(char* string, const size_t maxSize, 71 const time_t time, const BDateFormatStyle style) const 72 \brief Fills in \a string with a formatted date up to \a maxSize bytes for 73 the given \a time and \a style for the locale. 74 75 \param string The string buffer to fill with the formatted date. 76 \param maxSize The size of the buffer. 77 \param time The time (in seconds since epoch) to format 78 \param style Specify the long format (with day name, full 79 month name) or the short format, 08/12/2010 or similar. 80 81 \returns The number of bytes written during the date formatting. 82 \retval B_ERROR Unable to lock the BLocale. 83 \retval B_NO_MEMORY Ran out of memory while creating the object. 84 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 85 86 \since Haiku R1 87*/ 88 89 90/*! 91 \fn status_t BDateFormat::Format(BString& string, const time_t time, 92 const BDateFormatStyle style, const BTimeZone* timeZone) const 93 \brief Fills in \a string with a formatted date for the given 94 \a time, \a style, and \a timeZone for the locale. 95 96 \param string The string buffer to fill with the formatted date. 97 \param time The time (in seconds since epoch) to format 98 \param style Specify the long format (with day name, full 99 month name) or the short format, 08/12/2010 or similar. 100 \param timeZone The time zone. 101 102 \returns A status code. 103 \retval B_OK Everything went fine. 104 \retval B_ERROR Unable to lock the BLocale. 105 \retval B_NO_MEMORY Ran out of memory while creating the object. 106 107 \since Haiku R1 108*/ 109 110 111/*! 112 \fn status_t BDateFormat::Format(BString& string, 113 int*& fieldPositions, int& fieldCount, const time_t time, 114 const BDateFormatStyle style) const 115 \brief Fills in \a string with a custom formatted date according to the 116 given parameters for the locale. 117 118 \param string The string buffer to fill with the formatted date. 119 \param fieldPositions An array of date field positions to use. 120 \param fieldCount The number of \a fields in \a fieldPositions. 121 \param time The time (in seconds since epoch) to format 122 \param style Specify the long format (with day name, full 123 month name) or the short format, 08/12/2010 or similar. 124 125 \returns A status code. 126 \retval B_OK Everything went fine. 127 \retval B_ERROR Unable to lock the BLocale. 128 \retval B_NO_MEMORY Ran out of memory while creating the object. 129 \retval B_BAD_VALUE An error occurred while performing the date formatting. 130 131 \since Haiku R1 132*/ 133 134 135/*! 136 \fn status_t BDateFormat::GetFields(BDateElement*& fields, int& fieldCount, 137 BDateFormatStyle style) const 138 \brief Get the type of each field in the date format of the locale. 139 140 This method is most often used in combination with FormatDate(). 141 FormatDate() gives you the offset of each field in a formatted string, 142 and GetDateFields() gives you the type of the field at a given offset. 143 With these informations, you can handle the formatted date string as 144 a list of fields that you can split and alter at will. 145 146 \param fields Pointer to the fields object. 147 \param fieldCount The number of fields. 148 \param style Specify the long format (with day name, full 149 month name) or the short format, 08/12/2010 or similar. 150 151 \returns A status code. 152 \retval B_OK Everything went fine. 153 \retval B_ERROR Unable to lock the BLocale. 154 \retval B_NO_MEMORY Ran out of memory while creating the object. 155 \retval B_BAD_VALUE An error occurred while getting the date fields. 156 157 \sa BDateFormat::GetTimeFields(BDateElement*& fields, int& fieldCount, 158 BTimeFormatStyle style) const 159 160 \since Haiku R1 161*/ 162 163 164/*! 165 \fn status_t BDateFormat::GetStartOfWeek(BWeekday* startOfWeek) const 166 \brief Returns the day used as the start of week in this locale. 167 168 Possible values for \a startOfWeek include: 169 - \c B_WEEKDAY_SUNDAY 170 - \c B_WEEKDAY_MONDAY 171 - \c B_WEEKDAY_TUESDAY 172 - \c B_WEEKDAY_WEDNESDAY 173 - \c B_WEEKDAY_THURSDAY 174 - \c B_WEEKDAY_FRIDAY 175 - \c B_WEEKDAY_SATURDAY 176 177 \returns A status code. 178 \retval B_OK Everything went fine. 179 \retval B_BAD_VALUE \a startOfWeek is \c NULL. 180 \retval B_ERROR Unable to lock the BLocale or another error occurred. 181 182 \since Haiku R1 183*/ 184