inc/FLclDateTimeSymbols.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                FLclDateTimeSymbols.h
  20  * @brief               This is the header file for the %DateTimeSymbols class.
  21  *
  22  * This header file contains the declarations of the %DateTimeSymbols class.
  23  *
  24  */
  25 #ifndef _FLCL_DATE_TIME_SYMBOLS_H_
  26 #define _FLCL_DATE_TIME_SYMBOLS_H_
  27
  28 #include <FBaseColArrayList.h>
  29 #include <FLclLocale.h>
  30 #include <FLclCalendar.h>
  31
  32 namespace Tizen { namespace Locales
  33 {
  34
  35 /**
  36  * @class               DateTimeSymbols
  37  * @brief               This class provides methods that help in providing date and time symbols.
  38  *
  39  * @since               2.0
  40  *
  41  * The %DateTimeSymbols class is used for encapsulating localizable date-time formatting data, such as the names of the months, the days of the week, and the time zone data.
  42  * It is also used by DateTimeFormatter.
  43  * %DateTimeSymbols specifies the exact character strings to use for various parts of a date or time. For example, the names of the months and days of the week, the strings for AM and PM, and the day of the week considered to be the first day of the week.
  44  *
  45  * 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>.
  46  *
  47  * @see                 Tizen::Locales::DateTimeFormatter
  48  *
  49  */
  50 class _OSP_EXPORT_ DateTimeSymbols
  51         : public Tizen::Base::Object
  52 {
  53
  54 public:
  55         /**
  56          * This is the default constructor for this class. @n
  57          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  58          *
  59          * @since                       2.0
  60          *
  61          * @see                         Construct()
  62          */
  63         DateTimeSymbols(void);
  64
  65         /**
  66          * This is the destructor for this class. @n
  67          * This destructor overrides Tizen::Base::Object::~Object().
  68          *
  69          * @since               2.0
  70          */
  71         virtual ~DateTimeSymbols(void);
  72
  73
  74         /**
  75          * Initializes this instance of %DateTimeSymbols with the specified @c locale and @c calendarType.
  76          *
  77          * @if OSPCOMPAT
  78          * @brief <i> [Compatibility] </i>
  79          * @endif
  80          * @since                               2.0
  81          * @if OSPCOMPAT
  82          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
  83          *                              For more information, see @ref CompDateTimeSymbolsConstructPage "here".
  84          * @endif
  85          *
  86          * @return                              An error code
  87          * @param[in]                   locale                                                  The locale
  88          * @param[in]                   calendarType                                    The calendar type
  89          * @exception                   E_SUCCESS                                               The method is successful.
  90          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
  91          * @exception                   E_INVALID_ARG                   The specified @c locale or @c calendarType is invalid.
  92          */
  93         result Construct(const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
  94
  95
  96         /**
  97          * Initializes this instance of %DateTimeSymbols with the specified parameter. @n
  98          * This method loads the format data from the resources for the default locale into the default calendar.
  99          *
 100          * @if OSPCOMPAT
 101          * @brief <i> [Compatibility] </i>
 102          * @endif
 103          * @since                               2.0
 104          * @if OSPCOMPAT
 105          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 106          *                              For more information, see @ref CompDateTimeSymbolsConstructPage "here".
 107          * @endif
 108          *
 109          * @return                              An error code
 110          * @param[in]                   calendarType                                    The calendar type
 111          * @exception                   E_SUCCESS                                               The method is successful.
 112          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
 113          * @exception                   E_INVALID_ARG                   The specified @c calendarType is invalid.
 114          */
 115         result Construct(CalendarType calendarType);
 116
 117         /**
 118          * @if OSPCOMPAT
 119          * @page                    CompDateTimeSymbolsConstructPage Compatibility for Construct()
 120          * @section                   CompDateTimeSymbolsConstructIssueSection Issues
 121          * Implementation of this method in OSP compatible applications has the following issue: @n
 122          * -# The method returns E_UNSUPPORTED_OPERATION if the @c calendarType is invalid.
 123          *
 124          * @section                 CompDateTimeSymbolsConstructSolutionSection Resolutions
 125          * This issue has been resolved in Tizen.
 126          * @par When working in Tizen:
 127          * -# The method returns E_INVALID_ARG if the @c calendarType is invalid.
 128          * @endif
 129          */
 130
 131
 132         /**
 133          * Initializes this instance of %DateTimeSymbols with the specified parameter.
 134          *
 135          * @since                               2.0
 136          *
 137          * @return                              An error code
 138          * @param[in]                   other                                                   An instance of %DateTimeSymbols
 139          * @exception                   E_SUCCESS                                               The method is successful.
 140          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
 141          */
 142         result Construct(const DateTimeSymbols& other);
 143
 144
 145         /**
 146          * Gets the list of the era strings. @n
 147          * For example: "AD" and "BC".
 148          *
 149          * @since                               2.0
 150          *
 151          * @return                              A pointer to the list of era strings, @n
 152          *                                              else @c null if this instance has not been constructed as yet
 153          * @see                                 SetEras()
 154          */
 155         const Tizen::Base::Collection::IList* GetEras(void) const;
 156
 157
 158         /**
 159          * Sets the era strings. @n
 160          * Multiple strings can be concatenated by '|'. For example: "AD|BC".
 161          *
 162          * @since                               2.0
 163          *
 164          * @return                              An error code
 165          * @param[in]                   eras                                            The era strings concatenated by '|'
 166          * @exception                   E_SUCCESS                                       The method is successful.
 167          * @exception                   E_INVALID_ARG                           The specified @c eras contains an invalid value.
 168          * @see                                 GetEras()
 169          */
 170         result SetEras(const Tizen::Base::String& eras);
 171
 172
 173         /**
 174          * Gets the list of the month name strings. @n
 175          * For example: "January", "February", etc.
 176          *
 177          * @since                               2.0
 178          *
 179          * @return                              A pointer to the list of month name strings, @n
 180          *                                              else @c null if this instance has not been constructed as yet
 181          * @see                                 SetMonths()
 182          */
 183         const Tizen::Base::Collection::IList* GetMonths(void) const;
 184
 185
 186         /**
 187          * Sets the month name strings concatenated by '|'. @n
 188          * For example: "January|February|March|April|May|June|July|August|September|October|November|December".
 189          *
 190          * @since                               2.0
 191          *
 192          * @return                              An error code
 193          * @param[in]                   months                                          The new month strings concatenated by '|'
 194          * @exception                   E_SUCCESS                                       The method is successful.
 195          * @exception                   E_INVALID_ARG                           The specified @c months contains an invalid value.
 196          * @see                                         GetMonths()
 197          */
 198         result SetMonths(const Tizen::Base::String& months);
 199
 200
 201         /**
 202          * Gets the list of the short month name strings. @n
 203          * For example: "Jan", "Feb", etc.
 204          *
 205          * @since                               2.0
 206          *
 207          * @return                              A pointer to the list of short month name strings, @n
 208          *                                              else @c null if this instance has not been constructed as yet
 209          * @see                                 SetShortMonths()
 210          */
 211         const Tizen::Base::Collection::IList* GetShortMonths(void) const;
 212
 213
 214         /**
 215          * Sets the short month name strings concatenated by '|'. @n
 216          * For example: "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec".
 217          *
 218          * @since                                       2.0
 219          * @return                              An error code
 220          * @param[in]                   shortMonths                             The new short month name strings concatenated by '|'
 221          * @exception                   E_SUCCESS                               The method is successful.
 222          * @exception                   E_INVALID_ARG                   The specified @c shortMonths contains an invalid value. @n See the valid string in the description of the method.
 223          * @see                                         GetShortMonths()
 224          */
 225         result SetShortMonths(const Tizen::Base::String& shortMonths);
 226
 227
 228         /**
 229          * Gets the list of the weekday name strings. @n
 230          * For example: "Sunday", "Monday", etc.
 231          *
 232          * @since                               2.0
 233          *
 234          * @return                              A pointer to the list of weekday name strings, @n
 235          *                                              else @c null if this instance has not been constructed as yet
 236          * @see                                 SetWeekdays()
 237          */
 238         const Tizen::Base::Collection::IList* GetWeekdays(void) const;
 239
 240
 241         /**
 242          * Sets the weekday name strings concatenated by '|'. @n
 243          * For example: "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday".
 244          *
 245          * @since                               2.0
 246          *
 247          * @return                              An error code
 248          * @param[in]                   weekdays                                        The new weekday name strings concatenated by '|'
 249          * @exception                   E_SUCCESS                                       The method is successful.
 250          * @exception                   E_INVALID_ARG                           The specified @c weekdays contains an invalid value.
 251          * @see                                 GetWeekdays()
 252          */
 253         result SetWeekdays(const Tizen::Base::String& weekdays);
 254
 255
 256         /**
 257          * Gets the list of the short weekday name strings. @n
 258          * For example: "Sun", "Mon", etc.
 259          *
 260          * @since                               2.0
 261          *
 262          * @return                              A pointer to the list of short weekday name strings, @n
 263          *                                              else @c null if this instance has not been constructed as yet
 264          * @see                                 SetShortWeekdays()
 265          */
 266         const Tizen::Base::Collection::IList* GetShortWeekdays(void) const;
 267
 268
 269         /**
 270          * Sets the weekday name strings concatenated by '|'. @n
 271          * For example: "Sun|Mon|Tue|Wed|Thu|Fri|Sat".
 272          *
 273          * @since                               2.0
 274          *
 275          * @return                              An error code
 276          * @param[in]                   shortWeekdays                           The new short weekday strings concatenated by '|'
 277          * @exception                   E_SUCCESS                                       The method is successful.
 278          * @exception                   E_INVALID_ARG                           The specified @c shortWeekdays contains an invalid value.
 279          * @see                                 GetShortWeekdays()
 280          */
 281         result SetShortWeekdays(const Tizen::Base::String& shortWeekdays);
 282
 283
 284         /**
 285          * Gets the list of the AM/PM strings. @n
 286          * For example: "AM" and "PM".
 287          *
 288          * @since                               2.0
 289          *
 290          * @return                              A pointer to the list of AM/PM strings, @n
 291          *                                              else @c null if this instance has not been constructed as yet
 292          * @see                                 SetAmPm()
 293          */
 294         const Tizen::Base::Collection::IList* GetAmPm(void) const;
 295
 296
 297         /**
 298          * Sets the AM/PM strings concatenated by '|'. @n
 299          * For example: "AM|PM".
 300          *
 301          * @since                               2.0
 302          *
 303          * @return                              An error code
 304          * @param[in]                   amPm                                            The new AM/PM strings concatenated by '|'
 305          * @exception                   E_SUCCESS                                       The method is successful.
 306          * @exception                   E_INVALID_ARG                           The specified @c amPm contains an invalid value.
 307          * @see                                 GetAmPm()
 308          */
 309         result SetAmPm(const Tizen::Base::String& amPm);
 310
 311
 312         /**
 313          * Gets the name of the time zone. @n
 314          * For example: "Eastern European Time (EET)", "Eastern European Summer Time (EEST)".
 315          *
 316          * @since                               2.0
 317          *
 318          * @return                              The time zone name, @n
 319          *                                              else an empty string if @c timeZoneId is not found @n
 320          *                                              or the time zone name of @c timeZoneStyle is not found.
 321          * @param[in]   timeZoneId              The time zone ID
 322          * @param[in]   timeZoneStyle   The parameter may contain one of the following time zone styles:
 323          *                                                              @li The normal time zone (0)
 324          *                                                              @li The abbreviated time zone (1)
 325          *                                                              @li The normal summer time zone (2)
 326          *                                                              @li The abbreviated summer time zone (3)
 327          * @see                                                 SetTimeZoneName()
 328          * @see                                                 AddTimeZoneName()
 329          */
 330         Tizen::Base::String GetTimeZoneName(Tizen::Base::String& timeZoneId, int timeZoneStyle = 0) const;
 331
 332
 333         /**
 334          * Sets the time zone name string related to the specified time zone ID.
 335          *
 336          * @since                               2.0
 337          *
 338          * @return                              An error code
 339          * @param[in]                   timeZoneId                                                      The time zone ID @n
 340          *                                                                                                                      For example: "Europe/Helsinki".
 341          * @param[in]                   concatenatedTimeZoneName                        The new concatenated time zone name @n
 342          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 343          * @exception                   E_SUCCESS                       The method is successful.
 344          * @exception                   E_INVALID_ARG           The specified @c timeZoneId or @c concatenatedTimeZoneName contains an invalid value.
 345          * @exception                   E_OBJ_NOT_FOUND         The specified @c timeZoneId is not found.
 346          * @see                                         GetTimeZoneName()
 347          * @see                                         AddTimeZoneName()
 348          */
 349         result SetTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 350
 351
 352         /**
 353          * Adds a new time zone name string that is related to time zone ID.
 354          *
 355          * @since                               2.0
 356          *
 357          * @return                              An error code
 358          * @param[in]                   timeZoneId                                                      The time zone ID @n
 359          *                                                                                                                      For example: "Europe/Helsinki".
 360          * @param[in]                   concatenatedTimeZoneName                        The concatenated time zone name @n
 361          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 362          * @exception                   E_SUCCESS                       The method is successful.
 363          * @exception                   E_INVALID_ARG           A specified input parameter is invalid.
 364          * @exception                   E_OBJ_ALREADY_EXIST     The specified @c timeZoneId already exists.
 365          * @see                                 GetTimeZoneName()
 366          * @see                                 SetTimeZoneName()
 367          */
 368         result AddTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 369
 370
 371         /*
 372          * Gets the non-localized date-time pattern characters.
 373          *
 374          * @since                               2.0
 375          *
 376          * @return                              The non-localized date-time pattern characters
 377          */
 378         static Tizen::Base::WcharBuffer* GetNonLocalizedDateTimePatternN(void);
 379
 380 private:
 381         /**
 382          * The implementation of this copy constructor is intentionally blank and declared as private to
 383          * prohibit copying of objects.
 384          */
 385         DateTimeSymbols(const DateTimeSymbols& dateTimeSymbols);
 386
 387         /**
 388          * The implementation of this copy assignment operator is intentionally blank and declared as private
 389          * to prohibit copying of objects.
 390          */
 391         DateTimeSymbols& operator =(const DateTimeSymbols& dateTimeSymbols);
 392
 393         friend class _DateTimeSymbolsImpl;
 394         class _DateTimeSymbolsImpl* __pDateTimeSymbolsImpl;
 395
 396 }; // DateTimeSymbols
 397
 398 }} // Tizen::Locales
 399
 400 #endif //_FLCL_DATE_TIME_SYMBOLS_H_
 401