inc/FLclDateTimeFormatter.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file                FLclDateTimeFormatter.h
  20  * @brief               This is the header file for the %DateTimeFormatter class.
  21  *
  22  * This header file contains the declarations of the %DateTimeFormatter class.
  23  *
  24  */
  25 #ifndef _FLCL_DATE_TIME_FORMATTER_H_
  26 #define _FLCL_DATE_TIME_FORMATTER_H_
  27
  28 // Includes
  29 #include <FBaseString.h>
  30 #include <FLclCalendar.h>
  31 #include <FLclDateTimeSymbols.h>
  32
  33
  34 namespace Tizen { namespace Locales
  35 {
  36
  37 // forward declaration
  38 class NumberFormatter;
  39 class _FieldPosition;
  40 class _DateTimeFormatterImpl;
  41
  42
  43 /**
  44  * @enum DateTimeStyle
  45  *
  46  * Defines the style for date and time.
  47  *
  48  * @since               2.0
  49  */
  50 enum DateTimeStyle
  51 {
  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 */
  58 };
  59
  60 /**
  61  * @class               DateTimeFormatter
  62  * @brief               This class provides methods for formatting the date and time formats.
  63  *
  64  * @since               2.0
  65  *
  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.
  68  *
  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>.
  70  *
  71  * @see         Tizen::Base::DateTime
  72  * @see         DateTimeSymbols
  73  *
  74  * The following example demonstrates how to use the %DateTimeFormatter class.
  75  *
  76  * @code
  77 #include <FBase.h>
  78 #include <FLocales.h>
  79 #include <FSystem.h>
  80
  81 using namespace Tizen::Base;
  82 using namespace Tizen::Locales;
  83 using namespace Tizen::System;
  84
  85 void
  86 LocaleApp::DateTimeFormatterExample(void)
  87 {
  88         // Construct locale
  89         Locale locale(LANGUAGE_ENG, COUNTRY_US);
  90
  91         // Get today
  92         DateTime today;
  93         SystemTime::GetCurrentTime(TIME_MODE_UTC, today);
  94
  95         // Get date formatter
  96         DateTimeFormatter* pDateFormatter = DateTimeFormatter::CreateDateFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
  97
  98         String formattedString;
  99
 100         // Format today with date formatter
 101         pDateFormatter->Format(today, formattedString);
 102
 103         // Get time formatter
 104         DateTimeFormatter* pTimeFormatter = DateTimeFormatter::CreateTimeFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
 105
 106         // Format today with time formatter
 107         pTimeFormatter->Format(today, formattedString);
 108
 109         // Customized pattern
 110         String cutomizedPattern = L"EEE d MMM yy";
 111         pDateFormatter->ApplyPattern(cutomizedPattern);
 112
 113         // Format today with date formatter
 114         pDateFormatter->Format(today, formattedString);
 115
 116         delete pDateFormatter;
 117         delete pTimeFormatter;
 118 }
 119 @endcode
 120  *
 121  */
 122 class _OSP_EXPORT_ DateTimeFormatter
 123         : public Tizen::Base::Object
 124 {
 125 public:
 126         /**
 127          * This is the destructor for this class. @n
 128          * This destructor overrides Tizen::Base::Object::~Object().
 129          *
 130          * @since               2.0
 131          */
 132         virtual ~DateTimeFormatter(void);
 133
 134         /**
 135          * Creates the date formatter with the specified formatting style for the system locale.
 136          *
 137          * @since                       2.0
 138          *
 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.
 148          */
 149         static DateTimeFormatter* CreateDateFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 150
 151
 152         /**
 153          * Creates the date formatter with the specified formatting style for the specified locale.
 154          *
 155          * @if OSPCOMPAT
 156          * @brief <i> [Compatibility] </i>
 157          * @endif
 158          * @since                       2.0
 159          * @if OSPCOMPAT
 160          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 161          *                              For more information, see @ref CompDateTimeFormatterCreateDateFormatterNPage "here".
 162          * @endif
 163          *
 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.
 173          */
 174         static DateTimeFormatter* CreateDateFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 175
 176         /**
 177          * @if OSPCOMPAT
 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.
 182          *
 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.
 187          * @endif
 188          */
 189
 190
 191         /**
 192          * Creates the time formatter with the specified formatting style for the system locale.
 193          *
 194          * @since                       2.0
 195          *
 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.
 205          */
 206         static DateTimeFormatter* CreateTimeFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 207
 208
 209         /**
 210          * Creates the time formatter with the specified formatting style for the specified @c locale.
 211          *
 212          * @if OSPCOMPAT
 213          * @brief <i> [Compatibility] </i>
 214          * @endif
 215          * @since                       2.0
 216          * @if OSPCOMPAT
 217          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 218          *                              For more information, see @ref CompDateTimeFormatterCreateTimeFormatterNPage "here".
 219          * @endif
 220          *
 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.
 230          */
 231         static DateTimeFormatter* CreateTimeFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 232
 233         /**
 234          * @if OSPCOMPAT
 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.
 239          *
 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.
 244          * @endif
 245          */
 246
 247         /**
 248          * Creates the date/time formatter with the specified formatting style for the system locale.
 249          *
 250          * @since                       2.0
 251          *
 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.
 263          */
 264         static DateTimeFormatter* CreateDateTimeFormatterN(DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
 265
 266
 267         /**
 268          * Creates the date/time formatter with the specified formatting style for the specified @c locale.
 269          *
 270          * @since                       2.0
 271          *
 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.
 283          */
 284         static DateTimeFormatter* CreateDateTimeFormatterN(const Locale& locale, DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
 285
 286         /**
 287          * Formats a Tizen::Base::DateTime object into a date/time string and appends the resulting string to the specified string buffer.
 288          *
 289          * @since                       2.0
 290          *
 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
 297          */
 298         virtual result Format(const Tizen::Base::DateTime& date, Tizen::Base::String& str) const;
 299
 300
 301         /**
 302          * Formats a Calendar object into a date/time string and appends the resulting string to the specified string buffer.
 303          *
 304          * @since                       2.0
 305          *
 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
 311          */
 312         virtual result Format(const Calendar& calendar, Tizen::Base::String& str) const;
 313
 314
 315         /**
 316         * Applies the specified pattern string to the date format.
 317         *
 318         * @since                                2.0
 319         *
 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.
 323         */
 324         result ApplyPattern(const Tizen::Base::String& pattern);
 325
 326
 327         /**
 328         * Gets a pattern string describing the date format.
 329         *
 330         * @since                                2.0
 331         *
 332         * @return                               A string describing the date format
 333         */
 334         Tizen::Base::String GetPattern(void) const;
 335
 336
 337         /**
 338         * Gets the date and time format symbols of the formatter.
 339         *
 340         * @since                                2.0
 341         *
 342         * @return                               A pointer to DateTimeSymbols for the formatter instance
 343         * @see                                  SetDateTimeSymbols()
 344         */
 345         const DateTimeSymbols* GetDateTimeSymbols(void) const;
 346
 347
 348         /**
 349         * Sets the date and time format symbols of the date format.
 350         *
 351         * @since                                2.0
 352         *
 353         * @param[in]                    newSymbols                      The new date and time format symbols
 354         * @see                                  GetDateTimeSymbols()
 355         */
 356         void SetDateTimeSymbols(const DateTimeSymbols& newSymbols);
 357
 358 private:
 359         NumberFormatter* __pNumberFormat;
 360         Calendar* __pCalendar;
 361
 362         /**
 363          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 364          */
 365         DateTimeFormatter(void);
 366
 367         /**
 368          * The implementation of this copy constructor is intentionally blank and declared as private to
 369          * prohibit copying of objects.
 370          */
 371         DateTimeFormatter(const DateTimeFormatter& dateTimeFormatter);
 372
 373         /**
 374          * The implementation of this copy assignment operator is intentionally blank and declared as private
 375          * to prohibit copying of objects.
 376          */
 377         DateTimeFormatter& operator =(const DateTimeFormatter& dateTimeFormatter);
 378
 379         friend class _DateTimeFormatterImpl;
 380         class _DateTimeFormatterImpl* __pDateTimeFormatterImpl;
 381 }; // DateTimeFormatter
 382
 383 }} // Tizen::Locales
 384
 385 #endif //_FLCL_DATE_TIME_FORMATTER_H_
 386