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