2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseDateTime.h
19 * @brief This is the header file for the %DateTime class.
21 * This header file contains the declarations of the %DateTime class.
23 #ifndef _FBASE_DATE_TIME_H_
24 #define _FBASE_DATE_TIME_H_
26 #include <FBaseObject.h>
27 #include <FBaseTimeSpan.h>
28 #include <FBaseString.h>
29 #include <FBaseDouble.h>
32 namespace Tizen { namespace Base
36 * @brief This class represents the date and time as per the Gregorian calendar.
40 * The %DateTime class represents dates and times with values ranging from 12:00:00.000 midnight,
41 * January 1, 1 to 11:59:59.999 P.M., December 31, 9999 in the Gregorian calendar. It
42 * provides methods for conversion between the time formats.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/datetime_timespan.htm">DateTime and TimeSpan</a>.
46 * The following example demonstrates how to use the %DateTime class.
52 * using namespace Tizen::Base;
54 * // This method sets both current local time and UTC time.
56 * MyClass::DateTimeSample(void)
59 * int year, month, day;
61 * dt.SetValue(2009, 10, 25);
68 * year = dt.GetYear(); // 2020
69 * month = dt.GetMonth(); // 1
70 * day = dt.GetDay(); // 30
74 class _OSP_EXPORT_ DateTime
79 * This is the default constructor for this class.
83 * @remarks The value of the instance is the same as the value of the instance returned by the GetMinValue() method.
88 * Copying of objects using this copy constructor is allowed.
92 * @param[in] value The %DateTime instance to copy
94 DateTime(const DateTime& value);
97 * This destructor overrides Tizen::Base::Object::~Object().
101 virtual ~DateTime(void);
104 * Sets the current instance of %DateTime to the value of the specified instance of TimeSpan since the minimum date (GetMinValue()).
108 * @param[in] value An instance of TimeSpan
109 * @exception E_SUCCESS The method is successful.
110 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
111 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
112 * is less than the value returned by GetMinValue().
114 result SetValue(const TimeSpan& value);
117 * Sets the current instance of %DateTime to the value of the specified instance of %DateTime.
121 * @param[in] value An instance of %DateTime
123 void SetValue(const DateTime& value);
126 * Sets the current instance of %DateTime to the specified @c year, @c month, @c day, @c hour, @c minute, and @c second.
130 * @return An error code
131 * @param[in] year The year to set
132 * @param[in] month The month to set
133 * @param[in] day The day to set
134 * @param[in] hour The hour to set
135 * @param[in] minute The minute set
136 * @param[in] second The second to set
137 * @exception E_SUCCESS The method is successful.
138 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
139 * Either the arguments are greater than the value returned by GetMaxValue() or
140 * are less than the value returned by GetMinValue(), or
141 * the arguments contain invalid values.
142 * For example, day is 31 when month is 2.
144 result SetValue(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
147 * Sets the current instance of %DateTime to the specified @c year, @c month, @c day, @c hour, @c minute, @c second, and @c millisecond.
151 * @return An error code
152 * @param[in] year The year to set
153 * @param[in] month The month to set
154 * @param[in] day The day to set
155 * @param[in] hour The hour to set
156 * @param[in] minute The minute set
157 * @param[in] second The second to set
158 * @param[in] millisecond The millisecond to set
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
161 * Either the arguments are greater than the value returned by GetMaxValue() or
162 * are less than the value returned by GetMinValue(), or
163 * the arguments contain invalid values.
164 * For example, day is 31 when month is 2.
166 result SetValue(int year, int month, int day, int hour, int minute, int second, int millisecond);
169 * Sets the current instance of %DateTime with the specified number of %ticks.
170 * The tick value of type @c long @c long represents dates and times ranging from January 1, 1 A.D. 00:00:00.000 am.
174 * @return An error code
175 * @param[in] ticks The number of ticks
176 * @exception E_SUCCESS The method is successful.
177 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
178 * Either the arguments are greater than the value returned by GetMaxValue() or
179 * are less than the value returned by GetMinValue(), or
180 * the arguments contain invalid values.
181 * For example, day is 31 when month is 2.
183 result SetValue(long long ticks);
186 * Copying of objects using this copy assignment operator is allowed.
190 * @return A reference to the current object
191 * @param[in] rhs An instance of %DateTime
193 DateTime& operator =(const DateTime& rhs);
196 * Checks whether the current instance of %DateTime is equivalent to the specified instance of %DateTime.
200 * @return @c true if the current instance is equivalent to the specified instance, @n
202 * @param[in] rhs An instance of %DateTime
204 bool operator ==(const DateTime& rhs) const;
207 * Checks whether the current instance of %DateTime is not equivalent to the specified instance of %DateTime.
211 * @return @c true if the current instance is not equivalent to the specified instance, @n
213 * @param[in] rhs An instance of %DateTime
215 bool operator !=(const DateTime& rhs) const;
218 * Checks whether the value of the current instance of %DateTime is less than the value of the specified instance of %DateTime.
222 * @return @c true if the value of the current instance is less than the value of the specified instance, @n
224 * @param[in] rhs An instance of %DateTime
226 bool operator <(const DateTime& rhs) const;
229 * Checks whether the value of the current instance of %DateTime is greater than the value of the specified instance of %DateTime.
233 * @return @c true if the value of the current instance is greater than the value of the specified instance, @n
235 * @param[in] rhs An instance of %DateTime
237 bool operator >(const DateTime& rhs) const;
240 * Checks whether the value of the current instance of %DateTime is less than or equal to the value of the specified instance of %DateTime.
244 * @return @c true if the value of the current instance is less than or equal to the value of the specified instance, @n
246 * @param[in] rhs An instance of %DateTime
248 bool operator <=(const DateTime& rhs) const;
251 * Checks whether the value of the current instance of %DateTime is greater than or equal to the value of the specified instance of %DateTime.
255 * @return @c true if the value of the current instance is greater than or equal to the value of the specified instance, @n
257 * @param[in] rhs An instance of %DateTime
259 bool operator >=(const DateTime& rhs) const;
262 * Adds the specified time span to the instance of %DateTime.
266 * @return An error code
267 * @param[in] t The time span to add
268 * @exception E_SUCCESS The method is successful.
269 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
270 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
271 * is less than the value returned by GetMinValue().
273 result Add(const TimeSpan& t);
276 * Adds the specified number of days to the instance of %DateTime.
280 * @return An error code
281 * @param[in] days The number of days to add
282 * @exception E_SUCCESS The method is successful.
283 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
284 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
285 * is less than the value returned by GetMinValue().
287 result AddDays(int days);
290 * Adds the specified number of hours to the instance of %DateTime.
294 * @return An error code
295 * @param[in] hours The number of hours to add
296 * @exception E_SUCCESS The method is successful.
297 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
298 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
299 * is less than the value returned by GetMinValue().
301 result AddHours(int hours);
304 * Adds the specified number of minutes to the instance of %DateTime.
308 * @return An error code
309 * @param[in] minutes The number of minutes to add
310 * @exception E_SUCCESS The method is successful.
311 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
312 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
313 * is less than the value returned by GetMinValue().
315 result AddMinutes(int minutes);
318 * Adds the specified number of months to the instance of %DateTime.
322 * @return An error code
323 * @param[in] months The number of months to add
324 * @exception E_SUCCESS The method is successful.
325 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
326 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
327 * is less than the value returned by GetMinValue().
329 result AddMonths(int months);
332 * Adds the specified number of seconds to the instance of %DateTime.
336 * @return An error code
337 * @param[in] seconds The number of seconds to add
338 * @exception E_SUCCESS The method is successful.
339 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
340 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
341 * is less than the value returned by GetMinValue().
343 result AddSeconds(int seconds);
346 * Adds a specified number of milliseconds to the instance of %DateTime.
350 * @return An error code
351 * @param[in] milliseconds The number of milliseconds to add
352 * @exception E_SUCCESS The method is successful.
353 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
354 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
355 * is less than the value returned by GetMinValue().
357 result AddMilliseconds(long long milliseconds);
360 * Adds a specified number of ticks to the instance of %DateTime.
364 * @return An error code
365 * @param[in] ticks The number of ticks to add
366 * @exception E_SUCCESS The method is successful.
367 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
368 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
369 * is less than the value returned by GetMinValue().
371 result AddTicks(long long ticks);
374 * Adds the specified number of years to the instance of %DateTime.
378 * @return An error code
379 * @param[in] years The number of years to add
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
382 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
383 * is less than the value returned by GetMinValue().
385 result AddYears(int years);
388 * Compares two specified instances of %DateTime. @n
389 * The two instances must be in the same time zone to make a meaningful comparison.
393 * @return A 32-bit @c signed integer value
395 * < 0 if the value of @c dt1 is less than the value of @c dt2
396 * == 0 if the value of @c dt1 is equal to the value of @c dt2
397 * > 0 if the value of @c dt1 is greater than the value of @c dt2
399 * @param[in] dt1 An instance of %DateTime
400 * @param[in] dt2 An instance of %DateTime
402 static int Compare(const DateTime& dt1, const DateTime& dt2);
405 * Compares the value of the current instance of %DateTime with the value of the specified instance of %DateTime.
409 * @return A 32-bit @c signed integer value
411 * < 0 if the value of the current instance is less than value of the specified instance
412 * == 0 if the value of the current instance is equal to value of the specified instance
413 * > 0 if the value of the current instance is greater than value of the specified instance
415 * @param[in] value An instance of %DateTime
417 int CompareTo(const DateTime& value) const;
420 * Checks whether the specified instance of Object is equivalent to the current instance of %DateTime.
424 * @return @c true if the specified instance of Object is equivalent to the current instance of %DateTime, @n
426 * @param[in] obj The object to compare with the current instance of %DateTime
427 * @see Tizen::Base::Object::GetHashCode()
429 virtual bool Equals(const Object& obj) const;
432 * Gets the hash value of the current instance of %DateTime. @n
433 * The hash value is calculated as (GetTime() ^ (GetTime() >> 16)).
437 * @return The hash value of the current instance of %DateTime
438 * @see Tizen::Base::Object::Equals()
440 virtual int GetHashCode(void) const;
443 * Gets the time span since the midnight of the date represented by the current instance of %DateTime.
447 * @return An instance of TimeSpan
449 TimeSpan GetTimeOfDay(void) const;
452 * Gets the number of @c days in the specified @c month of the specified @c year.
456 * @return An error code
457 * @param[in] year The year
458 * @param[in] month The month
459 * @param[out] days The number of days
460 * @exception E_SUCCESS The method is successful.
461 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
462 * @c year must be a value between @c 1 and @c 9999 and @c month must be a value between @c 1 and @c 12.
464 static result GetDaysInMonth(int year, int month, int& days);
467 * Subtracts the specified time span from the value of the current instance of %DateTime.
471 * @return An error code
472 * @param[in] t The time span to deduct
473 * @exception E_SUCCESS The method is successful.
474 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method. @n
475 * The resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
476 * is less than the value returned by GetMinValue().
478 result Subtract(const TimeSpan& t);
481 * Represents the current instance of %DateTime as a string.
485 * @return A string containing Unicode representation of the value of the current instance of %DateTime
486 * @remarks The format of the String representation is "mm/dd/yyyy hh:mm:ss".
487 * @remarks Use the Tizen::Locale namespace for a string of the locale-specific representation.
490 String ToString(void) const;
493 * Parses the specified String representation of the date and time value.
497 * @return An error code
498 * @param[in] str A String representation of a date and time value
499 * @param[out] dt The result of the method
500 * @exception E_SUCCESS The method is successful.
501 * @exception E_INVALID_FORMAT The specified string is in an invalid format.
502 * @exception E_OUT_OF_RANGE The specified string contains an invalid value. @n
503 * 1) The resulting value of %DateTime is greater than the value returned by GetMaxValue()
504 * or is less than the value returned by GetMinValue(). @n
505 * 2) The specified string contains an invalid value.
506 * For example, day is 31 when the month is 2.
508 * - The format of the string is "mm/dd/yyyy hh:mm:ss".
509 * - This method guarantees that the original value of out-parameter is not changed when the method returns error.
511 static result Parse(const String& str, DateTime& dt);
514 * Gets the year of the current instance of %DateTime.
518 * @return An integer value indicating the year of the current instance of %DateTime
520 int GetYear(void) const;
523 * Gets the month of the current instance of %DateTime.
527 * @return An integer value indicating the month of the current instance of %DateTime
529 int GetMonth(void) const;
532 * Gets the day of the current instance of %DateTime.
536 * @return An integer value indicating the day of the current instance of %DateTime
538 int GetDay(void) const;
541 * Gets the hour of the current instance of %DateTime.
545 * @return An integer value indicating the hour of the current instance of %DateTime
547 int GetHour(void) const;
550 * Gets the minute of the current instance of %DateTime.
554 * @return An integer value indicating the minute of the current instance of %DateTime
556 int GetMinute(void) const;
559 * Gets the second of the current instance of %DateTime.
563 * @return An integer value indicating the second of the current instance of %DateTime
565 int GetSecond(void) const;
568 * Gets the millisecond of the current instance of %DateTime.
572 * @return An integer value indicating the millisecond of the current instance of %DateTime
574 int GetMillisecond(void) const;
577 * Gets the number of ticks in 1 second.
581 * @return The number of ticks in 1 second.
583 static int GetTicksPerSecond(void);
586 * Gets the tick of the current instance of %DateTime.
587 * The tick value of type @c long @c long represents dates and times ranging from January 1, 1 A.D. 00:00:00.000 am.
591 * @return A @c long @c long value indicating the tick of the current instance of %DateTime
593 long long GetTicks(void) const;
596 * Gets the number of milliseconds (in TimeSpan) since the minimum date (GetMinValue()).
600 * @return An instance of TimeSpan
601 * @remarks The returned instance is the time since the value returned by GetMinValue().
603 TimeSpan GetTime(void) const;
606 * Gets the maximum allowable value of %DateTime (that is, "December 31 9999 23:59:59.999").
610 * @return An instance of %DateTime
612 static const DateTime& GetMaxValue(void);
615 * Gets the minimum allowable value of %DateTime (that is, "January 1 1 00:00:00.000").
619 * @return An instance of %DateTime
621 static const DateTime& GetMinValue(void);
624 * Checks whether the year represented by the current instance of %DateTime is a leap year.
628 * @return @c true if the year represented by the current instance of %DateTime is a leap year, @n
631 bool IsLeapYear(void) const;
634 * Checks whether the specified @c year is a leap year.
638 * @return @c true if the specified year is a leap year, @n
640 * @param[in] year The year
642 static bool IsLeapYear(int year);
645 DateTime(int year, int month, int day, int hour, int minute, int second, int tick);
647 int CountLeapYear(int year) const
649 return static_cast< int >((year - 1) / 4 - (year - 1) / 100 + (year - 1) / 400);
653 int CountDays(int year) const
655 return static_cast< int >((year - 1) * 365 + CountLeapYear(year));
658 int CountYears(int day) const
660 double year = (day - CountLeapYear(day / 365)) / 365.0;
664 if (year1.Equals(year2))
670 year = (year != static_cast< int >(year) ? 1 + static_cast< int >(year) : static_cast< int >(year));
671 int tempDays = day - CountDays(year);
673 // Check the boundary of days
674 if (IsLeapYear(year))
695 int year; /**<The year (1-9999)*/
696 int month; /**<The month (1-12)*/
697 int day; /**<The day (1-31)*/
698 int hour; /**<The hour (0-23)*/
699 int minute; /**<The minute (0-59)*/
700 int second; /**<The first 16 bits store tick (0-999) and the last 16 bits store second (0-59)*/
703 result ConvertTicksToDate(long long ticks, TmDateTime* pDateTime);
704 long long ConvertDateToTicks(const TmDateTime* pDateTime) const;
706 result ConvertSecondsToDate(long long seconds, TmDateTime* pDateTime);
707 long long ConvertDateToSeconds(const TmDateTime* pDateTime) const;
709 TmDateTime __dateTime;
711 friend class _DateTimeImpl;
712 class _DateTimeImpl * __pDateTimeImpl;
718 #endif // _FBASE_DATE_TIME_H_