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 FLclGregorianCalendar.h
20 * @brief This is the header file for the %GregorianCalendar class.
22 * This header file contains the declarations of the %GregorianCalendar class.
24 #ifndef _FLCL_GREGORIAN_CALENDAR_H_
25 #define _FLCL_GREGORIAN_CALENDAR_H_
29 #include <FLclCalendar.h>
30 #include <FLclLocale.h>
31 #include <FLclTimeZone.h>
33 namespace Tizen { namespace Locales
37 * @class GregorianCalendar
38 * @brief This class is a concrete subclass of calendar and provides the Gregorian calendar that is the most commonly used standard calendar.
42 * @final This class is not intended for extension.
44 * The %GregorianCalendar class is a concrete subclass of calendar and provides the Gregorian calendar that is the most commonly used standard calendar.
46 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/gregorian_calendar.htm">Gregorian Calendar</a>.
48 * @see Tizen::Locales::Locale
49 * @see Tizen::Locales::TimeZone
51 * The following example demonstrates how to use the %GregorianCalendar class.
56 using namespace Tizen::Base;
57 using namespace Tizen::Locales;
60 MyClass::GregorianCalendarExample(void)
62 Calendar* pGregorianCalendar = Calendar::CreateInstanceN(CALENDAR_GREGORIAN);
64 pGregorianCalendar->SetTimeField(TIME_FIELD_YEAR, 2005);
65 pGregorianCalendar->SetTimeField(TIME_FIELD_MONTH, JANUARY);
66 pGregorianCalendar->SetTimeField(TIME_FIELD_DAY_OF_MONTH, 3);
68 int dayOfWeek = pGregorianCalendar->GetTimeField(TIME_FIELD_DAY_OF_WEEK);// It is Monday.
70 pGregorianCalendar->Clear();
71 pGregorianCalendar->SetTimeField(TIME_FIELD_YEAR, 1972);
72 pGregorianCalendar->SetTimeField(TIME_FIELD_MONTH, OCTOBER);
73 pGregorianCalendar->SetTimeField(TIME_FIELD_DAY_OF_MONTH, 26); // It is Thursday
75 pGregorianCalendar->AddTimeField(TIME_FIELD_DAY_OF_MONTH, 1);
76 dayOfWeek = pGregorianCalendar->GetTimeField(TIME_FIELD_DAY_OF_WEEK); // It is Friday.
82 class _OSP_EXPORT_ GregorianCalendar
87 * This is the default constructor for this class. @n
88 * 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.
94 GregorianCalendar(void);
98 * This is the destructor for this class. @n
99 * This destructor overrides Tizen::Locales::Calendar::~Calendar().
103 virtual ~GregorianCalendar(void);
107 * Initializes this instance of %GregorianCalendar with the current GMT time zone and the system locale.
108 * The time zone is used for the zone offset and the DST offset.
109 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set and weekend cease.
110 * The weekdata are set as default values by the locale.
114 * @return An error code
115 * @exception E_SUCCESS The method is successful.
116 * @exception E_OUT_OF_MEMORY The memory is insufficient.
118 result Construct(void);
122 * Initializes this instance of %GregorianCalendar with the specified parameter.
126 * @return An error code
127 * @param[in] gc An instance of %GregorianCalendar to copy
128 * @exception E_SUCCESS The method is successful.
129 * @exception E_OUT_OF_MEMORY The memory is insufficient.
131 result Construct(const GregorianCalendar& gc);
135 * Initializes this instance of %GregorianCalendar based on the current time in the specified time zone with the system locale. @n
136 * The @c timeZone is used for the zone offset and the DST offset.
137 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
138 * The weekdata are set as default values by the locale.
142 * @return An error code
143 * @param[in] timeZone An instance of TimeZone
144 * @exception E_SUCCESS The method is successful.
145 * @exception E_OUT_OF_MEMORY The memory is insufficient.
147 result Construct(const TimeZone& timeZone);
151 * Initializes this instance of %GregorianCalendar based on the current time in the GMT time zone with the specified @c locale.
152 * The time zone is used for the zone offset and the DST offset.
153 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
154 * The weekdata are set as default values by the specified @c locale.
157 * @brief <i> [Compatibility] </i>
161 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
162 * For more information, see @ref CompGregorianCalendarConstructPage "here".
165 * @return An error code
166 * @param[in] locale An instance of Locale
167 * @exception E_SUCCESS The method is successful.
168 * @exception E_OUT_OF_MEMORY The memory is insufficient.
169 * @exception E_INVALID_ARG The specified @c locale is invalid.
171 result Construct(const Locale& locale);
175 * Initializes this instance of %GregorianCalendar based on the current time in the specified time zone with the specified system locale. @n
176 * The @c timeZone is used for the zone offset and the DST offset.
177 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
178 * The weekdata are set as default values by the specified @c locale.
181 * @brief <i> [Compatibility] </i>
185 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
186 * For more information, see @ref CompGregorianCalendarConstructPage "here".
189 * @return An error code
190 * @param[in] timeZone An instance of TimeZone
191 * @param[in] locale An instance of Locale
192 * @exception E_SUCCESS The method is successful.
193 * @exception E_OUT_OF_MEMORY The memory is insufficient.
194 * @exception E_INVALID_ARG The specified @c locale is invalid.
196 result Construct(const TimeZone& timeZone, const Locale& locale);
200 * @page CompGregorianCalendarConstructPage Compatibility for Construct()
201 * @section CompGregorianCalendarConstructIssueSection Issues
202 * Implementation of this method in OSP compatible applications has the following issue: @n
203 * -# The method returns E_UNSUPPORTED_OPERATION if the @c locale is invalid.
205 * @section CompGregorianCalendarConstructSolutionSection Resolutions
206 * This issue has been resolved in Tizen.
207 * @par When working in Tizen:
208 * -# The method returns E_INVALID_ARG if the @c locale is invalid.
213 * Initializes this instance of %GregorianCalendar based on the specified @c year, @c month, @c day, @c hour, @c minute, and @c second
214 * in the GMT time zone with the system locale. @n
215 * The time zone is used for the zone offset and the DST offset.
216 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
217 * The weekdata are set as default values by the locale.
218 * The Gregorian calendar is lenient: time fields are normalized when the user calls the Calendar::GetTimeField() method.
222 * @return An error code
223 * @param[in] year An integer value used to set the year time field
224 * @param[in] month An integer value used to set the month time field @n
225 * The indexing is 1-based. Therefore, 1 means January.
226 * @param[in] day An integer value used to set the date time field
227 * @param[in] hour An integer value used to set the hour time field
228 * @param[in] minute An integer value used to set the minute time field
229 * @param[in] second An integer value used to set the second time field
230 * @exception E_SUCCESS The method is successful.
231 * @exception E_INVALID_ARG An argument is invalid.
232 * @exception E_OUT_OF_MEMORY The memory is insufficient.
233 * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
234 * If the value of the time fields goes out of range, this exception is returned.
236 result Construct(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
240 * Initializes this instance of %GregorianCalendar based on the specified date and time in the GMT time zone with the system locale. @n
241 * The time zone is used for the zone offset and the DST offset.
242 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
243 * The weekdata are set as default values by the locale.
247 * @return An error code
248 * @param[in] dateTime An instance of Tizen::Base::DateTime
249 * @exception E_SUCCESS The method is successful.
250 * @exception E_OUT_OF_MEMORY The memory is insufficient.
251 * @exception E_INVALID_ARG The specified @c dateTime is invalid.
252 * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
253 * If the value of the time fields goes out of range, this exception is returned.
255 result Construct(const Tizen::Base::DateTime& dateTime);
259 * Adds the specified amount to the specified time field, based on the calendar rules. @n
260 * It is equivalent to calling Set(field, GetTimeField(field)+amount) with two adjustments. @n
262 * @b Add @b Rule1: The value of @c field after the call minus the value of @c field before the call is delta, modulo any overflow that has occurred in @c field.
263 * Overflow occurs when the @c field value exceeds its range and, as a result, the next larger field is incremented or decremented and the @c field value is adjusted back into its range. @n
265 * @b Add @b Rule2: If a smaller field is expected to be invariant, but it is impossible for it to be equal to its prior value because of
266 * changes in its minimum or maximum value after the @c field value is changed, then its value is adjusted to the closest possible value. @n
268 * A smaller field represents a smaller unit of time. The TIME_FIELD_HOUR field is smaller than the TIME_FIELD_DAY_OF_MONTH field.
269 * No adjustment is made to smaller fields that are not expected to be invariant.
270 * The calendar system determines what fields are expected to be invariant. @n
272 * In addition, this method forces re-computation of the calendar's milliseconds and all time fields immediately.
274 * For example, consider a %GregorianCalendar set to Oct. 31. 2004. Calling AddTimeField(TIME_FIELD_MONTH, 13) sets the calendar to Nov. 30. 2005.
275 * The TIME_FIELD_MONTH field is set to TIME_FIELD_NOVEMBER by @b Rule1, since adding 13 months to October gives November of the next year. Since
276 * the TIME_FIELD_DAY_OF_MONTH cannot be 31 in November in a %GregorianCalendar, TIME_FIELD_DAY_OF_MONTH is set to 30 by @b Rule2.
280 * @return An error code
281 * @param[in] field The time field
282 * @param[in] amount The amount to add
283 * @exception E_SUCCESS The method is successful.
284 * @exception E_INVALID_ARG The specified @c field is invalid.
285 * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
286 * If the value of the time fields goes out of range, this exception is returned.
287 * @remarks The TIME_FIELD_EXTENDED_YEAR and TIME_FIELD_YEAR_WOY fields cannot be added.
289 virtual result AddTimeField(TimeField field, int amount);
293 * Gets the actual minimum value that the specified time field can have, given the current date. @n
294 * For the Gregorian calendar, this is the same as Calendar::GetMinTimeField() and Calendar::GetGreatestMinTimeField().
298 * @return An integer value indicating the actual minimum value
299 * @param[in] field The time field
300 * @exception E_SUCCESS The method is successful.
301 * @exception E_INVALID_ARG The specified time field is invalid.
302 * @remarks The specific error code can be accessed using the GetLastResult() method.
304 virtual int GetActualMinTimeField(TimeField field) const;
308 * Gets the actual maximum value that the specified time field can have, given the current date. @n
309 * For example, if the current date is "Feb. 3. 2004", then the maximum value of the DATE field is 29.
313 * @return An integer value indicating the actual maximum value
314 * @param[in] field The time field
315 * @exception E_SUCCESS The method is successful.
316 * @exception E_INVALID_ARG The specified time field is invalid.
318 * @remarks The specific error code can be accessed using the GetLastResult() method.
320 virtual int GetActualMaxTimeField(TimeField field) const;
324 * Gets the Gregorian Calendar change date. @n
325 * This is the point when the switch from Julian dates to Gregorian dates occurred.
326 * Default is 00:00:00 local time, October 15, 1582. Previous to this the time and date are Julian dates.
330 * @return The milliseconds which is the Gregorian cutover time for this calendar
332 long long GetGregorianChange(void) const;
336 * Gets the calendar type of the current instance.
340 * @return An instance of CalendarType representing the calendar type of the current instance of Calendar @n
341 * In this case, CALENDAR_GREGORIAN.
343 virtual CalendarType GetType(void) const;
346 * Checks whether the current date for the current instance is in Daylight Saving Time (DST).
350 * @return An error code
351 * @param[out] isInDst Set to @c true if the current date is in DST, @n
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
355 * If the value of the time fields goes out of range, this exception is returned.
356 * @exception E_INVALID_STATE In this method, time fields of this instance are calculated. @n
357 * If any time field value previously set is invalid, this exception is returned.
359 virtual result IsInDst(bool& isInDst) const;
363 * Checks whether the specified year is a leap year.
367 * @return @c true if the specified year is a leap year, @n
369 * @param[in] year The year to check
371 bool IsLeapYear(int year) const;
375 * Sets the Gregorian Calendar change date. @n
376 * This is the point when the switch from Julian dates to Gregorian dates occurred.
377 * Default is 00:00:00 local time, Oct 15, 1582. Previous to this, dates are in the Julian calendar.
379 * To obtain a pure Julian calendar, set the change @c change to MAX_MILLISECOND.
380 * To obtain a pure Gregorian calendar, set the change @c change to MIN_MILLISECOND.
384 * @return An error code
385 * @param[in] change The given Gregorian cutover date
386 * @exception E_SUCCESS The method is successful.
387 * @exception E_OUT_OF_MEMORY The memory is insufficient.
389 result SetGregorianChange(long long change);
392 * Rolls up or down as per the specified amount in the specified field. @n
393 * This method overrides Calendar(). @n
394 * For more details, refer to Tizen::Locales::Calendar::Roll(TimeField, int).
398 * @return An error code
399 * @param[in] field The time field
400 * @param[in] amount The amount to roll up/down
401 * @exception E_SUCCESS The method is successful.
402 * @exception E_INVALID_STATE In this method, time fields of this instance are calculated. @n
403 * If any time field value previously set is invalid, this exception is returned.
404 * @exception E_INVALID_ARG The specified @c field is invalid (for example, TIME_FIELD_DST_OFFSET, TIME_FIELD_ZONE_OFFSET).
405 * @exception E_OUT_OF_RANGE In this method, time fields of this instance are calculated. @n
406 * If the value of the time fields goes out of range, this exception is returned.
408 virtual result Roll(TimeField field, int amount);
412 * Gets the millisecond which is midnight, local time at or before the Gregorian cutover.
416 * @return The millisecond which is midnight, local time at or before the Gregorian cutover
417 * If this method fails, @c -1 is returned.
418 * The specific error code can be accessed using the GetLastResult() method.
420 long long GetNormalizedGregorianCutover(void) const;
423 * Gets the year of the Gregorian cutover, with @c 0 representing 1 BC, @c -1 representing 2 BC, and so on.
427 * @return The year of the Gregorian cutover
428 * If this method fails, @c -1 is returned.
429 * The specific error code can be accessed using the GetLastResult() method.
431 int GetGregorianCutoverYear(void) const;
434 * Gets the Julian day number of the Gregorian cutover.
438 * @return The Julian day number of the Gregorian cutover
440 int GetCutoverJulianDay(void) const;
444 * Checks whether the current calendar is a Gregorian calendar or not.
448 * @return @c true if the current calendar is a Gregorian calendar, @n
451 bool IsGregorian() const;
455 * Gets the current time of the instance in milliseconds from epoch.
459 * @return An error code
460 * @param[out] millisec The current time in milliseconds from the epoch
461 * @exception E_SUCCESS The method is successful.
462 * @exception E_INVALID_STATE If any time field value previously set is invalid, this exception is returned.
463 * @exception E_OUT_OF_RANGE A time field or its value is out of range.
465 result GetTimeInMillisecFromEpoch(long long& millisec) const;
469 * Sets the current time of the instance with the specified milliseconds value.
473 * @return An error code
474 * @param[in] millisec The new time in milliseconds from the epoch
475 * @exception E_OUT_OF_RANGE A time field or its value is out of range.
477 result SetTimeInMillisecFromEpoch(long long millisec);
481 * Converts the 1970-epoch day number to the Gregorian year, month, date, day of week, and day of year.
485 * @param[in] day The 1970-epoch day number
486 * @param[out] year The year to convert
487 * @param[out] month The month to convert
488 * @param[out] dayOfMonth The date to convert
489 * @param[out] dayOfWeek The day of week to convert
490 * @param[out] dayOfYear The day of year to convert
492 static void DayToFields(int day, int& year, int& month, int& dayOfMonth, int& dayOfWeek, int& dayOfYear);
496 * @enum GregorianCalendarEras
498 * Defines Era for Gregorian calendar. The indexing is 0-based.
500 enum GregorianCalendarEras
502 GREGORIAN_CALENDAR_BC = 0, // BC
503 GREGORIAN_CALENDAR_AD = 1, // AD
505 GREGORIAN_CALENDAR_BCE = 0, // BCE
506 GREGORIAN_CALENDAR_CE = 1, // CE
510 * The implementation of this copy constructor is intentionally blank and declared as private to
511 * prohibit copying of objects.
513 GregorianCalendar(const GregorianCalendar& gregorianCalendar);
516 * The implementation of this copy assignment operator is intentionally blank and declared as private
517 * to prohibit copying of objects.
519 GregorianCalendar& operator =(const GregorianCalendar& gregorianCalendar);
521 // added for backward compatibility
522 virtual result RollWithSingleUnit(TimeField field, bool up);
523 virtual result ComputeTimeFields(void);
524 virtual result ComputeTime(void);
525 virtual int GetMonthLength(int extendedYear, int month) const;
526 virtual int HandleGetLimit(TimeField field, CalendarLimitType limitType) const;
527 virtual Calendar* CloneN(void) const;
531 * Defines the length of months.
535 static const int MONTH_LENGTH[24];
538 * Defines the days of a year.
542 static const int NUM_DAYS[24];
545 * The Gregorian cutover number for Julian day.
549 static const int CUTOVER_JULIAN_DAY = 2299161; // Oct 15, 1582
556 static const int EPOCH_YEAR = 1970;
559 * The epoch start for Julian day.
563 static const int EPOCH_START_AS_JULIAN_DAY = 2440588; // Jan 1, 1970(Gregorian)
566 * Jan 1, 1 epoch start for Julian day.
570 static const int JAN_1_1_JULIAN_DAY = 1721426; // Jan 1, 1 CE Gregorian
573 * Temporary value for the Gregorian cutover.
577 static const long long PAPAL_CUTOVER =
578 ((long long) (GregorianCalendar::CUTOVER_JULIAN_DAY -
579 GregorianCalendar::EPOCH_START_AS_JULIAN_DAY) * (long long) ONE_DAY_IN_MILLISEC);
582 * Maximum value for longlong.
586 static const long long MAX_LONGLONG = (2 ^ 63) - 1;
589 * Minimum value for longlong.
593 static const long long MIN_LONGLONG = -1 * (2 ^ 63);
596 * Maximum value for Julian day.
600 static const int MAX_JULIAN = 0x7F000000;
603 * Minimum value for Julian day.
607 static const int MIN_JULIAN = -0x7F000000;
610 * Maximum millisecond value for Julian day.
614 static const long long MAX_MILLISEC = ((GregorianCalendar::MAX_JULIAN - GregorianCalendar::EPOCH_START_AS_JULIAN_DAY) * (long long) ONE_DAY_IN_MILLISEC);
617 * Minimum millisecond value for Julian day.
621 static const long long MIN_MILLISEC = ((GregorianCalendar::MIN_JULIAN - GregorianCalendar::EPOCH_START_AS_JULIAN_DAY) * (long long) ONE_DAY_IN_MILLISEC);
624 * Epoch offset in millisecond value.
628 static const long long EPOCH_OFFSET_IN_MILLISEC = 62135596800000LL; // Jan 1, 1970
631 * Default Gregorian cutover.
635 static const long long DEFAULT_GREGORIAN_CUTOVER = -12219292800000LL;
638 long long __normalizedGregorianCutover; // = __gregorianCutover;
639 int __gregorianCutoverYear; // 1582
640 int __cutoverJulianDay;
642 friend class _GregorianCalendarImpl;
643 class _GregorianCalendarImpl* __pGregorianCalendarImpl;
645 }; // GregorianCalendar
649 #endif //_FLCL_GREGORIAN_CALENDAR_H_