2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FLclDateTimeFormatter.h
20 * @brief This is the header file for the %DateTimeFormatter class.
22 * This header file contains the declarations of the %DateTimeFormatter class.
25 #ifndef _FLCL_DATE_TIME_FORMATTER_H_
26 #define _FLCL_DATE_TIME_FORMATTER_H_
29 #include <FBaseString.h>
30 #include <FLclCalendar.h>
31 #include <FLclDateTimeSymbols.h>
34 namespace Tizen { namespace Locales
37 // forward declaration
38 class NumberFormatter;
40 class _DateTimeFormatterImpl;
46 * Defines the style for date and time.
52 DATE_TIME_STYLE_NONE = -1, /**< The date time style: None */
53 DATE_TIME_STYLE_FULL = 0, /**< The date time style: FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42PM PST */
54 DATE_TIME_STYLE_LONG = 1, /**< The date time style: LONG is longer, such as July 18, 2012 or 3:30:32PM */
55 DATE_TIME_STYLE_MEDIUM = 2, /**< The date time style: MEDIUM is a little longer, such as Jan 12, 1952 */
56 DATE_TIME_STYLE_SHORT = 3, /**< The date time style: SHORT is completely numeric, such as 12/13/52 or 3:30PM */
57 DATE_TIME_STYLE_DEFAULT = DATE_TIME_STYLE_MEDIUM /**< The default date time style: Medium */
61 * @class DateTimeFormatter
62 * @brief This class provides methods for formatting the date and time formats.
66 * The %DateTimeFormatter class is used to format the date and time formats in a language-independent manner.
67 * The date and time are represented as a Tizen::Base::DateTime instance.
69 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/datetime_formatter.htm">Date and Time Formatter</a>.
71 * @see Tizen::Base::DateTime
72 * @see DateTimeSymbols
74 * The following example demonstrates how to use the %DateTimeFormatter class.
81 using namespace Tizen::Base;
82 using namespace Tizen::Locales;
83 using namespace Tizen::System;
86 LocaleApp::DateTimeFormatterExample(void)
89 Locale locale(LANGUAGE_ENG, COUNTRY_US);
93 SystemTime::GetCurrentTime(TIME_MODE_UTC, today);
96 DateTimeFormatter* pDateFormatter = DateTimeFormatter::CreateDateFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
98 String formattedString;
100 // Format today with date formatter
101 pDateFormatter->Format(today, formattedString);
103 // Get time formatter
104 DateTimeFormatter* pTimeFormatter = DateTimeFormatter::CreateTimeFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
106 // Format today with time formatter
107 pTimeFormatter->Format(today, formattedString);
109 // Customized pattern
110 String cutomizedPattern = L"EEE d MMM yy";
111 pDateFormatter->ApplyPattern(cutomizedPattern);
113 // Format today with date formatter
114 pDateFormatter->Format(today, formattedString);
116 delete pDateFormatter;
117 delete pTimeFormatter;
122 class _OSP_EXPORT_ DateTimeFormatter
123 : public Tizen::Base::Object
127 * This is the destructor for this class. @n
128 * This destructor overrides Tizen::Base::Object::~Object().
132 virtual ~DateTimeFormatter(void);
135 * Creates the date formatter with the specified formatting style for the system locale.
139 * @return A pointer to the system locale date formatter, @n
140 * else @c null if an error occurs
141 * @param[in] style The formatting style @n
142 * For example, "M/d/yy" is the short form for displaying only date in the US locale.
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_OUT_OF_MEMORY The memory is insufficient.
145 * @exception E_UNSUPPORTED_OPERATION The current locale is not supported.
146 * @exception E_INVALID_ARG The specified @c style is an invalid value.
147 * @remarks The specific error code can be accessed using the GetLastResult() method.
149 static DateTimeFormatter* CreateDateFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
153 * Creates the date formatter with the specified formatting style for the specified locale.
156 * @brief <i> [Compatibility] </i>
160 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
161 * For more information, see @ref CompDateTimeFormatterCreateDateFormatterNPage "here".
164 * @return A pointer to the specified locale date formatter, @n
165 * else @c null if an error occurs
166 * @param[in] locale The locale
167 * @param[in] style The formatting style @n
168 * For example, "M/d/yy" is the short form for displaying only date in the US locale.
169 * @exception E_SUCCESS The method is successful.
170 * @exception E_OUT_OF_MEMORY The memory is insufficient.
171 * @exception E_INVALID_ARG The specified @c locale or @c style is invalid.
172 * @remarks The specific error code can be accessed using the GetLastResult() method.
174 static DateTimeFormatter* CreateDateFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
178 * @page CompDateTimeFormatterCreateDateFormatterNPage Compatibility for CreateDateFormatterN()
179 * @section CompDateTimeFormatterCreateDateFormatterNIssueSection Issues
180 * Implementation of this method in OSP compatible applications has the following issue: @n
181 * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
183 * @section CompDateTimeFormatterCreateDateFormatterNtSolutionSection Resolutions
184 * This issue has been resolved in Tizen.
185 * @par When working in Tizen:
186 * -# The method returns E_INVALID_ARG if the @c locale or @c style is invalid.
192 * Creates the time formatter with the specified formatting style for the system locale.
196 * @return A pointer to the system locale time formatter, @n
197 * else @c null if an error occurs
198 * @param[in] style The formatting style @n
199 * For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
200 * @exception E_SUCCESS The method is successful.
201 * @exception E_OUT_OF_MEMORY The memory is insufficient.
202 * @exception E_UNSUPPORTED_OPERATION The current locale is not supported.
203 * @exception E_INVALID_ARG The specified @c style is invalid.
204 * @remarks The specific error code can be accessed using the GetLastResult() method.
206 static DateTimeFormatter* CreateTimeFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
210 * Creates the time formatter with the specified formatting style for the specified @c locale.
213 * @brief <i> [Compatibility] </i>
217 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
218 * For more information, see @ref CompDateTimeFormatterCreateTimeFormatterNPage "here".
221 * @return A pointer to the specified locale time formatter, @n
222 * else @c null if an error occurs
223 * @param[in] locale The locale
224 * @param[in] style The formatting style @n
225 * For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
226 * @exception E_SUCCESS The method is successful.
227 * @exception E_OUT_OF_MEMORY The memory is insufficient.
228 * @exception E_INVALID_ARG The specified @c locale or @c style is invalid.
229 * @remarks The specific error code can be accessed using the GetLastResult() method.
231 static DateTimeFormatter* CreateTimeFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
235 * @page CompDateTimeFormatterCreateTimeFormatterNPage Compatibility for CreateTimeFormatterN()
236 * @section CompDateTimeFormatterCreateTimeFormatterNIssueSection Issues
237 * Implementation of this method in OSP compatible applications has the following issue: @n
238 * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
240 * @section CompGrDateTimeFormatterCreateTimeFormatterNSolutionSection Resolutions
241 * This issue has been resolved in Tizen.
242 * @par When working in Tizen:
243 * -# The method returns E_INVALID_ARG if the @c locale or @c style is invalid.
248 * Creates the date/time formatter with the specified formatting style for the system locale.
252 * @return A pointer to the system locale date/time formatter, @n
253 * else @c null if an error occurs
254 * @param[in] dateStyle The date formatting style @n
255 * For example, "M/d/yy" is the short form for displaying only date in the US locale.
256 * @param[in] timeStyle The time formatting style @n
257 * For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
258 * @exception E_SUCCESS The method is successful.
259 * @exception E_OUT_OF_MEMORY The memory is insufficient.
260 * @exception E_UNSUPPORTED_OPERATION The current locale is not supported.
261 * @exception E_INVALID_ARG The specified @c dateStyle or @c timeStyle is invalid.
262 * @remarks The specific error code can be accessed using the GetLastResult() method.
264 static DateTimeFormatter* CreateDateTimeFormatterN(DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
268 * Creates the date/time formatter with the specified formatting style for the specified @c locale.
272 * @return A pointer to the specified locale date/time formatter, @n
273 * else @c null if an error occurs
274 * @param[in] locale The locale
275 * @param[in] dateStyle The date formatting style @n
276 * For example, "M/d/yy" is the short form for displaying only date in the US locale.
277 * @param[in] timeStyle The time formatting style @n
278 * For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
279 * @exception E_SUCCESS The method is successful.
280 * @exception E_OUT_OF_MEMORY The memory is insufficient.
281 * @exception E_INVALID_ARG The specified @c locale is not supported, or the @c dateStyle or the @c timeStyle is invalid.
282 * @remarks The specific error code can be accessed using the GetLastResult() method.
284 static DateTimeFormatter* CreateDateTimeFormatterN(const Locale& locale, DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
287 * Formats a Tizen::Base::DateTime object into a date/time string and appends the resulting string to the specified string buffer.
291 * @return An error code
292 * @param[in] date The Tizen::Base::DateTime object to format
293 * @param[out] str The string to append to the resultant string
294 * @exception E_SUCCESS The method is successful.
295 * @remarks This method does not handle the time zone information, so "z" pattern always returns "GMT+00:00".
296 * @see Tizen::Base::DateTime
298 virtual result Format(const Tizen::Base::DateTime& date, Tizen::Base::String& str) const;
302 * Formats a Calendar object into a date/time string and appends the resulting string to the specified string buffer.
306 * @return An error code
307 * @param[in] calendar The Calendar object to format
308 * @param[out] str The string to append to the resultant string
309 * @exception E_SUCCESS The method is successful.
310 * @see Tizen::Base::DateTime
312 virtual result Format(const Calendar& calendar, Tizen::Base::String& str) const;
316 * Applies the specified pattern string to the date format.
320 * @param[in] pattern The new date and time pattern for the date format
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG The length of the specified @c pattern is @c 0.
324 result ApplyPattern(const Tizen::Base::String& pattern);
328 * Gets a pattern string describing the date format.
332 * @return A string describing the date format
334 Tizen::Base::String GetPattern(void) const;
338 * Gets the date and time format symbols of the formatter.
342 * @return A pointer to DateTimeSymbols for the formatter instance
343 * @see SetDateTimeSymbols()
345 const DateTimeSymbols* GetDateTimeSymbols(void) const;
349 * Sets the date and time format symbols of the date format.
353 * @param[in] newSymbols The new date and time format symbols
354 * @see GetDateTimeSymbols()
356 void SetDateTimeSymbols(const DateTimeSymbols& newSymbols);
359 NumberFormatter* __pNumberFormat;
360 Calendar* __pCalendar;
363 * This default constructor is intentionally declared as private so that only the platform can create an instance.
365 DateTimeFormatter(void);
368 * The implementation of this copy constructor is intentionally blank and declared as private to
369 * prohibit copying of objects.
371 DateTimeFormatter(const DateTimeFormatter& dateTimeFormatter);
374 * The implementation of this copy assignment operator is intentionally blank and declared as private
375 * to prohibit copying of objects.
377 DateTimeFormatter& operator =(const DateTimeFormatter& dateTimeFormatter);
379 friend class _DateTimeFormatterImpl;
380 class _DateTimeFormatterImpl* __pDateTimeFormatterImpl;
381 }; // DateTimeFormatter
385 #endif //_FLCL_DATE_TIME_FORMATTER_H_