include/tools/date.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_TOOLS_DATE_HXX
  20 #define INCLUDED_TOOLS_DATE_HXX
  21
  22 #include <tools/toolsdllapi.h>
  23 #include <com/sun/star/util/Date.hpp>
  24 #include <com/sun/star/util/DateTime.hpp>
  25 #include <sal/log.hxx>
  26
  27 enum DayOfWeek { MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY,
  28                  SATURDAY, SUNDAY };
  29
  30 /** Represents a date in the proleptic Gregorian calendar.
  31
  32     Largest representable date is 32767-12-31 = 327671231
  33
  34     Smallest representable date is -32768-01-01 = -327680101
  35
  36     Due to possible conversions to css::util::Date, which has a short
  37     Year member variable, these limits are fix.
  38
  39     Year value 0 is unused. The year before year 1 CE is year 1 BCE, which is
  40     the traditional proleptic Gregorian calendar.
  41
  42     This is not how ISO 8601:2000 defines things (but ISO 8601:1998 Draft
  43     Revision did), but it enables class Date to be used for writing XML files
  44     as XML Schema Part 2 in D.3.2 No Year Zero says
  45     "The year "0000" is an illegal year value.", see
  46     https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#noYearZero
  47     and furthermore the note for 3.2.7 dateTime
  48     https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#dateTime
  49
  50  */
  51 class SAL_WARN_UNUSED TOOLS_DLLPUBLIC Date
  52 {
  53 private:
  54     sal_Int32       mnDate;
  55     void            setDateFromDMY( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear );
  56
  57 public:
  58     enum DateInitSystem
  59     {
  60         SYSTEM
  61     };
  62
  63     enum DateInitEmpty
  64     {
  65         EMPTY
  66     };
  67
  68                     explicit Date( DateInitEmpty ) : mnDate(0) {}
  69                     explicit Date( DateInitSystem );
  70                     explicit Date( sal_Int32 nDate ) : mnDate(nDate) {}
  71                     Date( const Date& rDate ) : mnDate(rDate.mnDate) {}
  72
  73                     /** nDay and nMonth both must be <100, nYear must be != 0 */
  74                     Date( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear )
  75                         { setDateFromDMY(nDay, nMonth, nYear); }
  76
  77                     Date( const css::util::Date& rUDate )
  78                     {
  79                         setDateFromDMY(rUDate.Day, rUDate.Month, rUDate.Year);
  80                     }
  81                     Date( const css::util::DateTime& _rDateTime );
  82
  83     bool            IsEmpty() const { return mnDate == 0; }
  84
  85     void            SetDate( sal_Int32 nNewDate );
  86     sal_Int32       GetDate() const { return mnDate; }
  87     /** Type safe access for values that are guaranteed to be unsigned, like Date::SYSTEM. */
  88     sal_uInt32      GetDateUnsigned() const { return static_cast<sal_uInt32>(mnDate < 0 ? -mnDate : mnDate); }
  89     css::util::Date GetUNODate() const { return css::util::Date(GetDay(), GetMonth(), GetYear()); }
  90
  91                     /** nNewDay must be <100 */
  92     void            SetDay( sal_uInt16 nNewDay );
  93                     /** nNewMonth must be <100 */
  94     void            SetMonth( sal_uInt16 nNewMonth );
  95                     /** nNewYear must be != 0 */
  96     void            SetYear( sal_Int16 nNewYear );
  97
  98     sal_uInt16      GetDay() const
  99                     {
 100                         return mnDate < 0 ?
 101                             static_cast<sal_uInt16>(-mnDate % 100) :
 102                             static_cast<sal_uInt16>( mnDate % 100);
 103                     }
 104     sal_uInt16      GetMonth() const
 105                     {
 106                         return mnDate < 0 ?
 107                             static_cast<sal_uInt16>((-mnDate / 100) % 100) :
 108                             static_cast<sal_uInt16>(( mnDate / 100) % 100);
 109                     }
 110     sal_Int16       GetYear() const { return static_cast<sal_Int16>(mnDate / 10000); }
 111     /** Type safe access for values that are guaranteed to be unsigned, like Date::SYSTEM. */
 112     sal_uInt16      GetYearUnsigned() const { return static_cast<sal_uInt16>((mnDate < 0 ? -mnDate : mnDate) / 10000); }
 113     sal_Int16       GetNextYear() const { sal_Int16 nY = GetYear(); return nY == -1 ? 1 : nY + 1; }
 114     sal_Int16       GetPrevYear() const { sal_Int16 nY = GetYear(); return nY == 1 ? -1 : nY - 1; }
 115
 116     /** Add years skipping year 0 and truncating at limits. If the original
 117         date was on Feb-29 and the resulting date is not a leap year, the
 118         result is adjusted to Feb-28.
 119     */
 120     void            AddYears( sal_Int16 nAddYears );
 121
 122     /** Add months skipping year 0 and truncating at limits. If the original
 123         date was on Feb-29 or day 31 and the resulting date is not a leap year
 124         or a month with less days, the result is adjusted to Feb-28 or day 30.
 125     */
 126     void            AddMonths( sal_Int32 nAddMonths );
 127
 128     /** Obtain the day of the week for the date.
 129
 130         Internally normalizes a copy of values.
 131         The result may be unexpected for a non-normalized invalid date like
 132         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 133      */
 134     DayOfWeek       GetDayOfWeek() const;
 135
 136     /** Obtain the day of the year for the date.
 137
 138         Internally normalizes a copy of values.
 139         The result may be unexpected for a non-normalized invalid date like
 140         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 141      */
 142     sal_uInt16      GetDayOfYear() const;
 143
 144     /** Obtain the week of the year for a date.
 145
 146         @param nMinimumNumberOfDaysInWeek
 147                How many days of a week must reside in the first week of a year.
 148
 149         Internally normalizes a copy of values.
 150         The result may be unexpected for a non-normalized invalid date like
 151         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 152      */
 153     sal_uInt16      GetWeekOfYear( DayOfWeek eStartDay = MONDAY,
 154                                    sal_Int16 nMinimumNumberOfDaysInWeek = 4 ) const;
 155
 156     /** Obtain the number of days in the month of the year of the date.
 157
 158         Internally normalizes a copy of values.
 159
 160         The result may be unexpected for a non-normalized invalid date like
 161         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 162
 163         These would result in 31 as --11-31 rolls over to --12-01 and the
 164         number of days in December is returned.
 165
 166         Instead, to obtain the value for the actual set use the static method
 167         Date::GetDaysInMonth( aDate.GetMonth(), aDate.GetYear()) in such cases.
 168      */
 169     sal_uInt16      GetDaysInMonth() const;
 170
 171     sal_uInt16      GetDaysInYear() const { return (IsLeapYear()) ? 366 : 365; }
 172     bool            IsLeapYear() const;
 173
 174     /** If the represented date is valid (1<=month<=12, 1<=day<=(28,29,30,31)
 175         depending on month/year) AND is of the Gregorian calendar (1582-10-15
 176         <= date)
 177      */
 178     bool            IsValidAndGregorian() const;
 179
 180     /** If the represented date is valid (1<=month<=12, 1<=day<=(28,29,30,31)
 181         depending on month/year) */
 182     bool            IsValidDate() const;
 183
 184     /** Normalize date, invalid day or month values are adapted such that they
 185         carry over to the next month or/and year, for example 1999-02-32
 186         becomes 1999-03-04, 1999-13-01 becomes 2000-01-01, 1999-13-42 becomes
 187         2000-02-11. Truncates at -32768-01-01 or 32767-12-31, 0001-00-x will
 188         yield the normalized value of -0001-12-x
 189
 190         This may be necessary after Date ctors or if the SetDate(), SetDay(),
 191         SetMonth(), SetYear() methods set individual non-matching values.
 192         Adding/subtracting to/from dates never produces invalid dates.
 193
 194         @returns TRUE if the date was normalized, i.e. not valid before.
 195      */
 196     bool            Normalize();
 197
 198     bool            IsBetween( const Date& rFrom, const Date& rTo ) const
 199                         { return ((mnDate >= rFrom.mnDate) &&
 200                                  (mnDate <= rTo.mnDate)); }
 201
 202     bool            operator ==( const Date& rDate ) const
 203                         { return (mnDate == rDate.mnDate); }
 204     bool            operator !=( const Date& rDate ) const
 205                         { return (mnDate != rDate.mnDate); }
 206     bool            operator  >( const Date& rDate ) const
 207                         { return (mnDate > rDate.mnDate); }
 208     bool            operator  <( const Date& rDate ) const
 209                         { return (mnDate < rDate.mnDate); }
 210     bool            operator >=( const Date& rDate ) const
 211                         { return (mnDate >= rDate.mnDate); }
 212     bool            operator <=( const Date& rDate ) const
 213                         { return (mnDate <= rDate.mnDate); }
 214
 215     Date&           operator =( const Date& rDate )
 216                         { mnDate = rDate.mnDate; return *this; }
 217     Date&           operator =( const css::util::Date& rUDate )
 218                         { setDateFromDMY( rUDate.Day, rUDate.Month, rUDate.Year); return *this; }
 219     Date&           operator +=( long nDays );
 220     Date&           operator -=( long nDays );
 221     Date&           operator ++();
 222     Date&           operator --();
 223
 224     TOOLS_DLLPUBLIC friend Date     operator +( const Date& rDate, long nDays );
 225     TOOLS_DLLPUBLIC friend Date     operator -( const Date& rDate, long nDays );
 226     TOOLS_DLLPUBLIC friend long     operator -( const Date& rDate1, const Date& rDate2 );
 227
 228     /** Obtain number of days in a month of a year.
 229
 230         Internally sanitizes nMonth to values 1 <= nMonth <= 12, does not
 231         normalize values.
 232      */
 233     static sal_uInt16 GetDaysInMonth( sal_uInt16 nMonth, sal_Int16 nYear );
 234
 235     /// Internally normalizes values.
 236     static long DateToDays( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear );
 237     /// Semantically identical to IsValidDate() member method.
 238     static bool IsValidDate( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear );
 239     /// Semantically identical to Normalize() member method.
 240     static bool Normalize( sal_uInt16 & rDay, sal_uInt16 & rMonth, sal_Int16 & rYear );
 241
 242  private:
 243     /// An accelerated form of DateToDays on this date
 244     long GetAsNormalizedDays() const;
 245 };
 246
 247 #endif
 248
 249 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */