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