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>
31 namespace Tizen { namespace Base
35 * @brief This class represents the date and time as per the Gregorian calendar.
39 * The %DateTime class represents dates and times with values ranging from 12:00:00.000 midnight,
40 * January 1, 1 to 11:59:59.999 P.M., December 31, 9999 in the Gregorian calendar. It
41 * provides methods for conversion between the time formats.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/datetime_timespan.htm">DateTime and TimeSpan</a>.
45 * The following example demonstrates how to use the %DateTime class.
51 * using namespace Tizen::Base;
53 * // This method sets both current local time and UTC time.
55 * MyClass::DateTimeSample(void)
58 * int year, month, day;
60 * dt.SetValue(2009, 10, 25);
67 * year = dt.GetYear(); // 2020
68 * month = dt.GetMonth(); // 1
69 * day = dt.GetDay(); // 30
73 class _OSP_EXPORT_ DateTime
78 * This is the default constructor for this class.
82 * @remarks The value of the instance is the same as the value of the instance returned by the GetMinValue() method.
87 * Copying of objects using this copy constructor is allowed.
91 * @param[in] value The %DateTime instance to copy
93 DateTime(const DateTime& value);
96 * This destructor overrides Tizen::Base::Object::~Object().
100 virtual ~DateTime(void);
103 * Sets the current instance of %DateTime to the value of the specified instance of TimeSpan since the minimum date (GetMinValue()).
107 * @param[in] value An instance of TimeSpan
108 * @exception E_SUCCESS The method is successful.
109 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
110 * - The specified @c value is outside the valid range defined by the method.
111 * - The resulting value of %DateTime is greater than the value returned by GetMaxValue().
112 * - The resulting value of %DateTime 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 year, month, day, hour, minute, and 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 Either of the following conditions has occurred:
139 * - The value of the arguments is outside the valid range defined by the method.
140 * - Either the arguments are greater than the value returned by GetMaxValue() or
141 * less than the value returned by GetMinValue().
142 * - The arguments contain invalid values,
143 * for example, @c day is @c 31 when @c month is @c 2.
145 result SetValue(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
148 * Sets the current instance of %DateTime to the specified year, month, day, hour, minute, second, and millisecond.
152 * @return An error code
153 * @param[in] year The year to set
154 * @param[in] month The month to set
155 * @param[in] day The day to set
156 * @param[in] hour The hour to set
157 * @param[in] minute The minute set
158 * @param[in] second The second to set
159 * @param[in] millisecond The millisecond to set
160 * @exception E_SUCCESS The method is successful.
161 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
162 * - The value of the arguments is outside the valid range defined by the method.
163 * - Either the arguments are greater than the value returned by GetMaxValue() or
164 * less than the value returned by GetMinValue().
165 * - The arguments contain invalid values,
166 * for example, @c day is @c 31 when @c month is @c 2.
168 result SetValue(int year, int month, int day, int hour, int minute, int second, int millisecond);
171 * Sets the current instance of %DateTime with the specified number of ticks.
172 * 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.
176 * @return An error code
177 * @param[in] ticks The number of ticks
178 * @exception E_SUCCESS The method is successful.
179 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
180 * - The value of the arguments is outside the valid range defined by the method.
181 * - Either the arguments are greater than the value returned by GetMaxValue() or
182 * less than the value returned by GetMinValue().
183 * - The arguments contain invalid values,
184 * for example, @c day is @c 31 when @c month is @c 2.
186 result SetValue(long long ticks);
189 * Copying of objects using this copy assignment operator is allowed.
193 * @return A reference to the current object
194 * @param[in] rhs An instance of %DateTime to copy
196 DateTime& operator =(const DateTime& rhs);
199 * Checks whether the current instance of %DateTime is equivalent to the specified instance of %DateTime.
203 * @return @c true if the current instance is equivalent to the specified instance, @n
205 * @param[in] rhs An instance of %DateTime to compare
207 bool operator ==(const DateTime& rhs) const;
210 * Checks whether the current instance of %DateTime is not equivalent to the specified instance of %DateTime.
214 * @return @c true if the current instance is not equivalent to the specified instance, @n
216 * @param[in] rhs An instance of %DateTime to compare
218 bool operator !=(const DateTime& rhs) const;
221 * Checks whether the value of the current instance of %DateTime is less than the value of the specified instance of %DateTime.
225 * @return @c true if the value of the current instance is less than the value of the specified instance, @n
227 * @param[in] rhs An instance of %DateTime to compare
229 bool operator <(const DateTime& rhs) const;
232 * Checks whether the value of the current instance of %DateTime is greater than the value of the specified instance of %DateTime.
236 * @return @c true if the value of the current instance is greater than the value of the specified instance, @n
238 * @param[in] rhs An instance of %DateTime to compare
240 bool operator >(const DateTime& rhs) const;
243 * Checks whether the value of the current instance of %DateTime is less than or equal to the value of the specified instance of %DateTime.
247 * @return @c true if the value of the current instance is less than or equal to the value of the specified instance, @n
249 * @param[in] rhs An instance of %DateTime to compare
251 bool operator <=(const DateTime& rhs) const;
254 * Checks whether the value of the current instance of %DateTime is greater than or equal to the value of the specified instance of %DateTime.
258 * @return @c true if the value of the current instance is greater than or equal to the value of the specified instance, @n
260 * @param[in] rhs An instance of %DateTime to compare
262 bool operator >=(const DateTime& rhs) const;
265 * Adds the specified time span to the instance of %DateTime.
269 * @return An error code
270 * @param[in] t The time span to add
271 * @exception E_SUCCESS The method is successful.
272 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
273 * - The value of the argument is outside the valid range defined by the method.
274 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
275 * less than the value returned by GetMinValue().
277 result Add(const TimeSpan& t);
280 * Adds the specified number of days to the instance of %DateTime.
284 * @return An error code
285 * @param[in] days The number of days to add
286 * @exception E_SUCCESS The method is successful.
287 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
288 * - The value of the argument is outside the valid range defined by the method.
289 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
290 * less than the value returned by GetMinValue().
292 result AddDays(int days);
295 * Adds the specified number of hours to the instance of %DateTime.
299 * @return An error code
300 * @param[in] hours The number of hours to add
301 * @exception E_SUCCESS The method is successful.
302 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
303 * - The value of the argument is outside the valid range defined by the method.
304 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
305 * less than the value returned by GetMinValue().
307 result AddHours(int hours);
310 * Adds the specified number of minutes to the instance of %DateTime.
314 * @return An error code
315 * @param[in] minutes The number of minutes to add
316 * @exception E_SUCCESS The method is successful.
317 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
318 * - The value of the argument is outside the valid range defined by the method.
319 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
320 * less than the value returned by GetMinValue().
322 result AddMinutes(int minutes);
325 * Adds the specified number of months to the instance of %DateTime.
329 * @return An error code
330 * @param[in] months The number of months to add
331 * @exception E_SUCCESS The method is successful.
332 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
333 * - The value of the argument is outside the valid range defined by the method.
334 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
335 * or less than the value returned by GetMinValue().
337 result AddMonths(int months);
340 * Adds the specified number of seconds to the instance of %DateTime.
344 * @return An error code
345 * @param[in] seconds The number of seconds to add
346 * @exception E_SUCCESS The method is successful.
347 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
348 * - The value of the argument is outside the valid range defined by the method.
349 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
350 * less than the value returned by GetMinValue().
352 result AddSeconds(int seconds);
355 * Adds the specified number of milliseconds to the instance of %DateTime.
359 * @return An error code
360 * @param[in] milliseconds The number of milliseconds to add
361 * @exception E_SUCCESS The method is successful.
362 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
363 * - The value of the argument is outside the valid range defined by the method.
364 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
365 * less than the value returned by GetMinValue().
367 result AddMilliseconds(long long milliseconds);
370 * Adds the specified number of ticks to the instance of %DateTime.
374 * @return An error code
375 * @param[in] ticks The number of ticks to add
376 * @exception E_SUCCESS The method is successful.
377 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
378 * - The value of the argument is outside the valid range defined by the method.
379 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
380 * less than the value returned by GetMinValue().
382 result AddTicks(long long ticks);
385 * Adds the specified number of years to the instance of %DateTime.
389 * @return An error code
390 * @param[in] years The number of years to add
391 * @exception E_SUCCESS The method is successful.
392 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
393 * - The value of the argument is outside the valid range defined by the method.
394 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
395 * less than the value returned by GetMinValue().
397 result AddYears(int years);
400 * Compares two specified instances of %DateTime. @n
401 * The two instances must be in the same time zone to make a meaningful comparison.
405 * @return The 32-bit @c signed integer value
407 * < 0 if the value of dt1 is less than the value of dt2
408 * == 0 if the value of dt1 is equal to the value of dt2
409 * > 0 if the value of dt1 is greater than the value of dt2
411 * @param[in] dt1 An instance of %DateTime
412 * @param[in] dt2 An instance of %DateTime
414 static int Compare(const DateTime& dt1, const DateTime& dt2);
417 * Compares the value of the current instance of %DateTime with the value of the specified instance of %DateTime.
421 * @return The 32-bit @c signed integer value
423 * < 0 if the value of the current instance is less than value of the specified instance
424 * == 0 if the value of the current instance is equal to value of the specified instance
425 * > 0 if the value of the current instance is greater than value of the specified instance
427 * @param[in] value An instance of %DateTime
429 int CompareTo(const DateTime& value) const;
432 * Checks whether the specified instance of Object is equivalent to the current instance of %DateTime.
436 * @return @c true if the specified instance of Object is equivalent to the current instance of %DateTime, @n
438 * @param[in] obj The object to compare with the current instance of %DateTime
439 * @see Tizen::Base::Object::GetHashCode()
441 virtual bool Equals(const Object& obj) const;
444 * Gets the hash value of the current instance of %DateTime. @n
445 * The hash value is calculated as (GetTime() ^ (GetTime() >> 16)).
449 * @return The hash value of the current instance of %DateTime
450 * @see Tizen::Base::Object::Equals()
452 virtual int GetHashCode(void) const;
455 * Gets the time span since the midnight of the date represented by the current instance of %DateTime.
459 * @return An instance of TimeSpan
461 TimeSpan GetTimeOfDay(void) const;
464 * Gets the number of days in the specified month of the specified year.
468 * @return An error code
469 * @param[in] year The year
470 * @param[in] month The month
471 * @param[out] days The number of days
472 * @exception E_SUCCESS The method is successful.
473 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
474 * - The value of the argument is outside the valid range defined by the method.
475 * - The specified @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.
477 static result GetDaysInMonth(int year, int month, int& days);
480 * Subtracts the specified time span from the value of the current instance of %DateTime.
484 * @return An error code
485 * @param[in] t The time span to subtract
486 * @exception E_SUCCESS The method is successful.
487 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
488 * - The value of the argument is outside the valid range defined by the method.
489 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue() or @n
490 * less than the value returned by GetMinValue().
492 result Subtract(const TimeSpan& t);
495 * Represents the current instance of %DateTime as a string.
499 * @return The string that contains the Unicode representation of the value of the current instance of %DateTime
501 * - The format of the String representation is "mm/dd/yyyy hh:mm:ss".
502 * - Use the Tizen::Locale namespace for a string of the locale-specific representation.
505 String ToString(void) const;
508 * Parses the specified String representation of the date and time value.
512 * @return An error code
513 * @param[in] str The String representation of the date and time value
514 * @param[out] dt The result of the method
515 * @exception E_SUCCESS The method is successful.
516 * @exception E_INVALID_FORMAT The specified string is in an invalid format.
517 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
518 * - The specified string contains an invalid value.
519 * - Either the resulting value of %DateTime is greater than the value returned by GetMaxValue()
520 * or less than the value returned by GetMinValue().
521 * - The specified string contains an invalid value,
522 * for example, @c day is @c 31 when the @c month is @c 2.
524 * - The format of the string is "mm/dd/yyyy hh:mm:ss".
525 * - This method guarantees that the original value of the out-parameter is not changed when the method returns an error.
527 static result Parse(const String& str, DateTime& dt);
530 * Gets the year of the current instance of %DateTime.
534 * @return The integer value that indicates the year of the current instance of %DateTime
536 int GetYear(void) const;
539 * Gets the month of the current instance of %DateTime.
543 * @return The integer value that indicates the month of the current instance of %DateTime
545 int GetMonth(void) const;
548 * Gets the day of the current instance of %DateTime.
552 * @return The integer value that indicates the day of the current instance of %DateTime
554 int GetDay(void) const;
557 * Gets the hour of the current instance of %DateTime.
561 * @return The integer value that indicates the hour of the current instance of %DateTime
563 int GetHour(void) const;
566 * Gets the minute of the current instance of %DateTime.
570 * @return The integer value that indicates the minute of the current instance of %DateTime
572 int GetMinute(void) const;
575 * Gets the second of the current instance of %DateTime.
579 * @return The integer value that indicates the second of the current instance of %DateTime
581 int GetSecond(void) const;
584 * Gets the millisecond of the current instance of %DateTime.
588 * @return The integer value that indicates the millisecond of the current instance of %DateTime
590 int GetMillisecond(void) const;
593 * Gets the number of ticks in one second.
597 * @return The number of ticks in one second.
599 static int GetTicksPerSecond(void);
602 * Gets the tick of the current instance of %DateTime.
603 * 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.
607 * @return The @c long @c long value that indicates the tick of the current instance of %DateTime
609 long long GetTicks(void) const;
612 * Gets the number of milliseconds (in TimeSpan) since the minimum date (GetMinValue()).
616 * @return An instance of TimeSpan
617 * @remarks The returned instance is the time since the value returned by GetMinValue().
619 TimeSpan GetTime(void) const;
622 * Gets the maximum allowable value of %DateTime (that is, "December 31 9999 23:59:59.999").
626 * @return An instance of %DateTime
628 static const DateTime& GetMaxValue(void);
631 * Gets the minimum allowable value of %DateTime (that is, "January 1 1 00:00:00.000").
635 * @return An instance of %DateTime
637 static const DateTime& GetMinValue(void);
640 * Checks whether the year represented by the current instance of %DateTime is a leap year.
644 * @return @c true if the year represented by the current instance of %DateTime is a leap year, @n
647 bool IsLeapYear(void) const;
650 * Checks whether the specified year is a leap year.
654 * @return @c true if the specified year is a leap year, @n
656 * @param[in] year The year
658 static bool IsLeapYear(int year);
661 DateTime(int year, int month, int day, int hour, int minute, int second, int tick);
663 int CountLeapYear(int year) const
665 return static_cast< int >((year - 1) / 4 - (year - 1) / 100 + (year - 1) / 400);
668 int CountDays(int year) const
670 return static_cast< int >((year - 1) * 365 + CountLeapYear(year));
673 int CountYears(int day) const
675 double year = (day - CountLeapYear(day / 365)) / 365.0;
679 if (year1.Equals(year2))
685 year = (year != static_cast< int >(year) ? 1 + static_cast< int >(year) : static_cast< int >(year));
686 int tempDays = day - CountDays(year);
688 // Check the boundary of days
689 if (IsLeapYear(year))
710 int year; /**<The year (1-9999)*/
711 int month; /**<The month (1-12)*/
712 int day; /**<The day (1-31)*/
713 int hour; /**<The hour (0-23)*/
714 int minute; /**<The minute (0-59)*/
715 int second; /**<The first 16 bits store tick (0-999) and the last 16 bits store second (0-59)*/
718 result ConvertTicksToDate(long long ticks, TmDateTime* pDateTime);
719 long long ConvertDateToTicks(const TmDateTime* pDateTime) const;
721 result ConvertSecondsToDate(long long seconds, TmDateTime* pDateTime);
722 long long ConvertDateToSeconds(const TmDateTime* pDateTime) const;
724 TmDateTime __dateTime;
726 friend class _DateTimeImpl;
727 class _DateTimeImpl* __pDateTimeImpl;
731 #endif // _FBASE_DATE_TIME_H_