inc/FLclDateTimeFormatter.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file                FLclDateTimeFormatter.h
  19  * @brief               This is the header file for the %DateTimeFormatter class.
  20  *
  21  * This header file contains the declarations of the %DateTimeFormatter class.
  22  *
  23  */
  24 #ifndef _FLCL_DATE_TIME_FORMATTER_H_
  25 #define _FLCL_DATE_TIME_FORMATTER_H_
  26
  27 // Includes
  28 #include <FBaseString.h>
  29 #include <FLclCalendar.h>
  30 #include <FLclDateTimeSymbols.h>
  31
  32
  33 namespace Tizen { namespace Locales
  34 {
  35
  36 // forward declaration
  37 class NumberFormatter;
  38 class _FieldPosition;
  39 class _DateTimeFormatterImpl;
  40
  41
  42 /**
  43  * @enum DateTimeStyle
  44  *
  45  * Defines the style for date and time.
  46  *
  47  * @since               2.0
  48  */
  49 enum DateTimeStyle
  50 {
  51         DATE_TIME_STYLE_NONE = -1,      /**< No date time style */
  52         DATE_TIME_STYLE_FULL = 0,       /**< The full date time style @n For example, Tuesday, April 12, 1952 AD or 3:30:42PM PST */
  53         DATE_TIME_STYLE_LONG = 1,       /**< The long date time style @n For example, July 18, 2012 or 3:30:32PM */
  54         DATE_TIME_STYLE_MEDIUM = 2,     /**< The medium date time style @n For example, Jan 12, 1952 */
  55         DATE_TIME_STYLE_SHORT = 3,      /**< The short date time style @n This style is completely numeric. For example, 12/13/52 or 3:30PM */
  56         DATE_TIME_STYLE_DEFAULT = DATE_TIME_STYLE_MEDIUM        /**< The default date time style @n This is set to Medium */
  57 };
  58
  59 /**
  60  * @class               DateTimeFormatter
  61  * @brief               This class provides methods for formatting the date and time formats.
  62  *
  63  * @since               2.0
  64  *
  65  * The %DateTimeFormatter class is used to format the date and time formats in a language-independent manner.
  66  * The date and time are represented as a Tizen::Base::DateTime instance.
  67  *
  68  * 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>.
  69  *
  70  * @see         Tizen::Base::DateTime
  71  * @see         DateTimeSymbols
  72  *
  73  * The following example demonstrates how to use the %DateTimeFormatter class.
  74  *
  75  * @code
  76 #include <FBase.h>
  77 #include <FLocales.h>
  78 #include <FSystem.h>
  79
  80 using namespace Tizen::Base;
  81 using namespace Tizen::Locales;
  82 using namespace Tizen::System;
  83
  84 void
  85 LocaleApp::DateTimeFormatterExample(void)
  86 {
  87         // Construct locale
  88         Locale locale(LANGUAGE_ENG, COUNTRY_US);
  89
  90         // Get today
  91         DateTime today;
  92         SystemTime::GetCurrentTime(TIME_MODE_UTC, today);
  93
  94         // Get date formatter
  95         DateTimeFormatter* pDateFormatter = DateTimeFormatter::CreateDateFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
  96
  97         String formattedString;
  98
  99         // Format today with date formatter
 100         pDateFormatter->Format(today, formattedString);
 101
 102         // Get time formatter
 103         DateTimeFormatter* pTimeFormatter = DateTimeFormatter::CreateTimeFormatterN(locale, DATE_TIME_STYLE_DEFAULT);
 104
 105         // Format today with time formatter
 106         pTimeFormatter->Format(today, formattedString);
 107
 108         // Customized pattern
 109         String cutomizedPattern = L"EEE d MMM yy";
 110         pDateFormatter->ApplyPattern(cutomizedPattern);
 111
 112         // Format today with date formatter
 113         pDateFormatter->Format(today, formattedString);
 114
 115         delete pDateFormatter;
 116         delete pTimeFormatter;
 117 }
 118 @endcode
 119  *
 120  */
 121 class _OSP_EXPORT_ DateTimeFormatter
 122         : public Tizen::Base::Object
 123 {
 124 public:
 125         /**
 126          * This is the destructor for this class. @n
 127          * This destructor overrides Tizen::Base::Object::~Object().
 128          *
 129          * @since               2.0
 130          */
 131         virtual ~DateTimeFormatter(void);
 132
 133         /**
 134          * Creates the date formatter with the specified formatting style for the system locale.
 135          *
 136          * @since                       2.0
 137          *
 138          * @return                      A pointer to the system locale date formatter, @n
 139          *                                      else @c null if an error occurs
 140          * @param[in]           style                                           The formatting style @n
 141          *                                                                                              For example, "M/d/yy" is the short form for displaying only the date in the US locale.
 142          * @exception           E_SUCCESS                                       The method is successful.
 143          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 144          * @exception           E_UNSUPPORTED_OPERATION         The current locale is not supported.
 145          * @exception           E_INVALID_ARG                           The specified @c style is an invalid value.
 146          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 147          */
 148         static DateTimeFormatter* CreateDateFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 149
 150
 151         /**
 152          * Creates the date formatter with the specified formatting style for the specified locale.
 153          *
 154          * @if OSPCOMPAT
 155          * @brief                       <i> [Compatibility] </i>
 156          * @endif
 157          * @since                       2.0
 158          * @if OSPCOMPAT
 159          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 160          *                                      For more information, see @ref CompDateTimeFormatterCreateDateFormatterNPage "here".
 161          * @endif
 162          *
 163          * @return                      A pointer to the specified locale date formatter, @n
 164          *                                      else @c null if an error occurs
 165          * @param[in]           locale                                          The locale
 166          * @param[in]           style                                           The formatting style @n
 167          *                                                                                              For example, "M/d/yy" is the short form for displaying only the date in the US locale.
 168          * @exception           E_SUCCESS                                       The method is successful.
 169          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 170          * @exception           E_INVALID_ARG           The specified @c locale or @c style is invalid.
 171          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 172          */
 173         static DateTimeFormatter* CreateDateFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 174
 175         /**
 176          * @if OSPCOMPAT
 177          * @page                        CompDateTimeFormatterCreateDateFormatterNPage Compatibility for CreateDateFormatterN()
 178          * @section                     CompDateTimeFormatterCreateDateFormatterNIssueSection Issues
 179          * Implementation of this method in OSP compatible applications has the following issue: @n
 180          * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
 181          *
 182          * @section                     CompDateTimeFormatterCreateDateFormatterNtSolutionSection Resolutions
 183          * This issue has been resolved in Tizen.
 184          * @par When working in Tizen:
 185          * -# The method returns E_INVALID_ARG if the @c locale or @c style is invalid.
 186          * @endif
 187          */
 188
 189
 190         /**
 191          * Creates the time formatter with the specified formatting style for the system locale.
 192          *
 193          * @since                       2.0
 194          *
 195          * @return                      A pointer to the system locale time formatter, @n
 196          *                                      else @c null if an error occurs
 197          * @param[in]           style                                           The formatting style @n
 198          *                                                                                              For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
 199          * @exception           E_SUCCESS                                       The method is successful.
 200          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 201          * @exception           E_UNSUPPORTED_OPERATION         The current locale is not supported.
 202          * @exception           E_INVALID_ARG                           The specified  @c style is invalid.
 203          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 204          */
 205         static DateTimeFormatter* CreateTimeFormatterN(DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 206
 207
 208         /**
 209          * Creates the time formatter with the specified formatting style for the specified @c locale.
 210          *
 211          * @if OSPCOMPAT
 212          * @brief                       <i> [Compatibility] </i>
 213          * @endif
 214          * @since                       2.0
 215          * @if OSPCOMPAT
 216          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 217          *                                      For more information, see @ref CompDateTimeFormatterCreateTimeFormatterNPage "here".
 218          * @endif
 219          *
 220          * @return                      A pointer to the specified locale time formatter, @n
 221          *                                      else @c null if an error occurs
 222          * @param[in]           locale                                          The locale
 223          * @param[in]           style                                           The formatting style @n
 224          *                                                                                              For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
 225          * @exception           E_SUCCESS                                       The method is successful.
 226          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 227          * @exception           E_INVALID_ARG                           The specified @c locale or @c style is invalid.
 228          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 229          */
 230         static DateTimeFormatter* CreateTimeFormatterN(const Locale& locale, DateTimeStyle style = DATE_TIME_STYLE_DEFAULT);
 231
 232         /**
 233          * @if OSPCOMPAT
 234          * @page                CompDateTimeFormatterCreateTimeFormatterNPage Compatibility for CreateTimeFormatterN()
 235          * @section             CompDateTimeFormatterCreateTimeFormatterNIssueSection Issues
 236          * Implementation of this method in OSP compatible applications has the following issue: @n
 237          * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
 238          *
 239          * @section             CompGrDateTimeFormatterCreateTimeFormatterNSolutionSection Resolutions
 240          * This issue has been resolved in Tizen.
 241          * @par When working in Tizen:
 242          * -# The method returns E_INVALID_ARG if the @c locale or @c style is invalid.
 243          * @endif
 244          */
 245
 246         /**
 247          * Creates the date/time formatter with the specified formatting style for the system locale.
 248          *
 249          * @since                       2.0
 250          *
 251          * @return                      A pointer to the system locale date/time formatter, @n
 252          *                                      else @c null if an error occurs
 253          * @param[in]           dateStyle                                       The date formatting style @n
 254          *                                                                                              For example, "M/d/yy" is the short form for displaying only the date in the US locale.
 255          * @param[in]           timeStyle                                       The time formatting style @n
 256          *                                                                                              For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
 257          * @exception           E_SUCCESS                                       The method is successful.
 258          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 259          * @exception           E_UNSUPPORTED_OPERATION         The current locale is not supported.
 260          * @exception           E_INVALID_ARG                           The specified @c dateStyle or @c timeStyle is invalid.
 261          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 262          */
 263         static DateTimeFormatter* CreateDateTimeFormatterN(DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
 264
 265
 266         /**
 267          * Creates the date/time formatter with the specified formatting style for the specified @c locale.
 268          *
 269          * @since                       2.0
 270          *
 271          * @return                      A pointer to the specified locale date/time formatter, @n
 272          *                                      else @c null if an error occurs
 273          * @param[in]           locale                                          The locale
 274          * @param[in]           dateStyle                                       The date formatting style @n
 275          *                                                                                              For example, "M/d/yy" is the short form for displaying only date in the US locale.
 276          * @param[in]           timeStyle                                       The time formatting style @n
 277          *                                                                                              For example, "h:mm a" is the short form for displaying the 12-hour time format in the US locale.
 278          * @exception           E_SUCCESS                                       The method is successful.
 279          * @exception           E_OUT_OF_MEMORY                         The memory is insufficient.
 280          * @exception           E_INVALID_ARG                           The specified @c locale is not supported, or the @c dateStyle or the @c timeStyle is invalid.
 281          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 282          */
 283         static DateTimeFormatter* CreateDateTimeFormatterN(const Locale& locale, DateTimeStyle dateStyle = DATE_TIME_STYLE_DEFAULT, DateTimeStyle timeStyle = DATE_TIME_STYLE_DEFAULT);
 284
 285         /**
 286          * Formats a Tizen::Base::DateTime object into a date/time string and appends the resulting string to the specified string.
 287          *
 288          * @since                       2.0
 289          *
 290          * @return                      An error code
 291          * @param[in]           date                            The Tizen::Base::DateTime object to format
 292          * @param[out]          str                                     The string to which formatted string is appended
 293          * @exception           E_SUCCESS                       The method is successful.
 294          * @remarks                     This method does not handle the time zone information, so "z" pattern always returns "GMT+00:00".
 295          */
 296         virtual result Format(const Tizen::Base::DateTime& date, Tizen::Base::String& str) const;
 297
 298
 299         /**
 300          * Formats a Calendar object into a date/time string and appends the resulting string to the specified string buffer.
 301          *
 302          * @since                       2.0
 303          *
 304          * @return                      An error code
 305          * @param[in]           calendar                                The Calendar object to format
 306          * @param[out]          str                                             The string to which formatted string is appended
 307          * @exception           E_SUCCESS                               The method is successful.
 308          * @see                         Tizen::Base::DateTime
 309          */
 310         virtual result Format(const Calendar& calendar, Tizen::Base::String& str) const;
 311
 312
 313         /**
 314         * Applies the specified pattern string to the date format.
 315         *
 316         * @since                                2.0
 317         *
 318         * @param[in]                    pattern                                 The date and time pattern for the date format
 319         * @exception                    E_SUCCESS                               The method is successful.
 320         * @exception                    E_INVALID_ARG                   The length of the specified @c pattern is @c 0.
 321         */
 322         result ApplyPattern(const Tizen::Base::String& pattern);
 323
 324
 325         /**
 326         * Gets the pattern string describing the date format.
 327         *
 328         * @since                                2.0
 329         *
 330         * @return                               The date format pattern string
 331         */
 332         Tizen::Base::String GetPattern(void) const;
 333
 334
 335         /**
 336         * Gets the date and time format symbols of the formatter.
 337         *
 338         * @since                                2.0
 339         *
 340         * @return                               A pointer to DateTimeSymbols of the formatter
 341         * @see                                  SetDateTimeSymbols()
 342         */
 343         const DateTimeSymbols* GetDateTimeSymbols(void) const;
 344
 345
 346         /**
 347         * Sets the date and time format symbols of the formatter.
 348         *
 349         * @since                                2.0
 350         *
 351         * @param[in]                    newSymbols                      The date and time format symbols
 352         * @see                                  GetDateTimeSymbols()
 353         */
 354         void SetDateTimeSymbols(const DateTimeSymbols& newSymbols);
 355
 356 private:
 357         NumberFormatter* __pNumberFormat;
 358         Calendar* __pCalendar;
 359
 360         /**
 361          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 362          */
 363         DateTimeFormatter(void);
 364
 365         /**
 366          * The implementation of this copy constructor is intentionally blank and declared as private to
 367          * prohibit copying of objects.
 368          */
 369         DateTimeFormatter(const DateTimeFormatter& dateTimeFormatter);
 370
 371         /**
 372          * The implementation of this copy assignment operator is intentionally blank and declared as private
 373          * to prohibit copying of objects.
 374          */
 375         DateTimeFormatter& operator =(const DateTimeFormatter& dateTimeFormatter);
 376
 377         friend class _DateTimeFormatterImpl;
 378         class _DateTimeFormatterImpl* __pDateTimeFormatterImpl;
 379 }; // DateTimeFormatter
 380
 381 }} // Tizen::Locales
 382
 383 #endif //_FLCL_DATE_TIME_FORMATTER_H_
 384