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                     Date( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear )
  73                         { setDateFromDMY(nDay, nMonth, nYear); }
  74                     Date( const css::util::Date& rUDate )
  75                     {
  76                         setDateFromDMY(rUDate.Day, rUDate.Month, rUDate.Year);
  77                     }
  78                     Date( const css::util::DateTime& _rDateTime );
  79
  80     void            SetDate( sal_Int32 nNewDate );
  81     sal_Int32       GetDate() const { return mnDate; }
  82     /** Type safe access for values that are guaranteed to be unsigned, like Date::SYSTEM. */
  83     sal_uInt32      GetDateUnsigned() const { return static_cast<sal_uInt32>(mnDate < 0 ? -mnDate : mnDate); }
  84     css::util::Date GetUNODate() const { return css::util::Date(GetDay(), GetMonth(), GetYear()); }
  85
  86     void            SetDay( sal_uInt16 nNewDay );
  87     void            SetMonth( sal_uInt16 nNewMonth );
  88     void            SetYear( sal_Int16 nNewYear );
  89     sal_uInt16      GetDay() const
  90                     {
  91                         return mnDate < 0 ?
  92                             static_cast<sal_uInt16>(-mnDate % 100) :
  93                             static_cast<sal_uInt16>( mnDate % 100);
  94                     }
  95     sal_uInt16      GetMonth() const
  96                     {
  97                         return mnDate < 0 ?
  98                             static_cast<sal_uInt16>((-mnDate / 100) % 100) :
  99                             static_cast<sal_uInt16>(( mnDate / 100) % 100);
 100                     }
 101     sal_Int16       GetYear() const { return static_cast<sal_Int16>(mnDate / 10000); }
 102     /** Type safe access for values that are guaranteed to be unsigned, like Date::SYSTEM. */
 103     sal_uInt16      GetYearUnsigned() const { return static_cast<sal_uInt16>((mnDate < 0 ? -mnDate : mnDate) / 10000); }
 104     sal_Int16       GetNextYear() const { sal_Int16 nY = GetYear(); return nY == -1 ? 1 : nY + 1; }
 105     sal_Int16       GetPrevYear() const { sal_Int16 nY = GetYear(); return nY == 1 ? -1 : nY - 1; }
 106
 107     /** Add years skipping year 0 and truncating at limits. If the original
 108         date was on Feb-29 and the resulting date is not a leap year, the
 109         result is adjusted to Feb-28.
 110     */
 111     void            AddYears( sal_Int16 nAddYears );
 112
 113     /** Add months skipping year 0 and truncating at limits. If the original
 114         date was on Feb-29 or day 31 and the resulting date is not a leap year
 115         or a month with less days, the result is adjusted to Feb-28 or day 30.
 116     */
 117     void            AddMonths( sal_Int32 nAddMonths );
 118
 119     /** Obtain the day of the week for the date.
 120
 121         Internally normalizes a copy of values.
 122         The result may be unexpected for a non-normalized invalid date like
 123         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 124      */
 125     DayOfWeek       GetDayOfWeek() const;
 126
 127     /** Obtain the day of the year for the date.
 128
 129         Internally normalizes a copy of values.
 130         The result may be unexpected for a non-normalized invalid date like
 131         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 132      */
 133     sal_uInt16      GetDayOfYear() const;
 134
 135     /** Obtain the week of the year for a date.
 136
 137         @param nMinimumNumberOfDaysInWeek
 138                How many days of a week must reside in the first week of a year.
 139
 140         Internally normalizes a copy of values.
 141         The result may be unexpected for a non-normalized invalid date like
 142         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 143      */
 144     sal_uInt16      GetWeekOfYear( DayOfWeek eStartDay = MONDAY,
 145                                    sal_Int16 nMinimumNumberOfDaysInWeek = 4 ) const;
 146
 147     /** Obtain the number of days in the month of the year of the date.
 148
 149         Internally normalizes a copy of values.
 150
 151         The result may be unexpected for a non-normalized invalid date like
 152         Date(31,11,2000) or a sequence of aDate.SetDay(31); aDate.SetMonth(11);
 153
 154         These would result in 31 as --11-31 rolls over to --12-01 and the
 155         number of days in December is returned.
 156
 157         Instead, to obtain the value for the actual set use the static method
 158         Date::GetDaysInMonth( aDate.GetMonth(), aDate.GetYear()) in such cases.
 159      */
 160     sal_uInt16      GetDaysInMonth() const;
 161
 162     sal_uInt16      GetDaysInYear() const { return (IsLeapYear()) ? 366 : 365; }
 163     bool            IsLeapYear() const;
 164
 165     /** If the represented date is valid (1<=month<=12, 1<=day<=(28,29,30,31)
 166         depending on month/year) AND is of the Gregorian calendar (1582-10-15
 167         <= date) (AND implicitly date <= 9999-12-31 due to internal
 168         representation) */
 169     bool            IsValidAndGregorian() const;
 170
 171     /** If the represented date is valid (1<=month<=12, 1<=day<=(28,29,30,31)
 172         depending on month/year) */
 173     bool            IsValidDate() const;
 174
 175     /** Normalize date, invalid day or month values are adapted such that they
 176         carry over to the next month or/and year, for example 1999-02-32
 177         becomes 1999-03-04, 1999-13-01 becomes 2000-01-01, 1999-13-42 becomes
 178         2000-02-11. Truncates at 9999-12-31, 0000-00-x will yield the
 179         normalized value of 0000-01-max(1,(x-31))
 180
 181         This may be necessary after Date ctors or if the SetDate(), SetDay(),
 182         SetMonth(), SetYear() methods set individual non-matching values.
 183         Adding/subtracting to/from dates never produces invalid dates.
 184
 185         @returns TRUE if the date was normalized, i.e. not valid before.
 186      */
 187     bool            Normalize();
 188
 189     bool            IsBetween( const Date& rFrom, const Date& rTo ) const
 190                         { return ((mnDate >= rFrom.mnDate) &&
 191                                  (mnDate <= rTo.mnDate)); }
 192
 193     bool            operator ==( const Date& rDate ) const
 194                         { return (mnDate == rDate.mnDate); }
 195     bool            operator !=( const Date& rDate ) const
 196                         { return (mnDate != rDate.mnDate); }
 197     bool            operator  >( const Date& rDate ) const
 198                         { return (mnDate > rDate.mnDate); }
 199     bool            operator  <( const Date& rDate ) const
 200                         { return (mnDate < rDate.mnDate); }
 201     bool            operator >=( const Date& rDate ) const
 202                         { return (mnDate >= rDate.mnDate); }
 203     bool            operator <=( const Date& rDate ) const
 204                         { return (mnDate <= rDate.mnDate); }
 205
 206     Date&           operator =( const Date& rDate )
 207                         { mnDate = rDate.mnDate; return *this; }
 208     Date&           operator =( const css::util::Date& rUDate )
 209                         { setDateFromDMY( rUDate.Day, rUDate.Month, rUDate.Year); return *this; }
 210     Date&           operator +=( long nDays );
 211     Date&           operator -=( long nDays );
 212     Date&           operator ++();
 213     Date&           operator --();
 214
 215     TOOLS_DLLPUBLIC friend Date     operator +( const Date& rDate, long nDays );
 216     TOOLS_DLLPUBLIC friend Date     operator -( const Date& rDate, long nDays );
 217     TOOLS_DLLPUBLIC friend long     operator -( const Date& rDate1, const Date& rDate2 );
 218
 219     /** Obtain number of days in a month of a year.
 220
 221         Internally sanitizes nMonth to values 1 <= nMonth <= 12, does not
 222         normalize values.
 223      */
 224     static sal_uInt16 GetDaysInMonth( sal_uInt16 nMonth, sal_Int16 nYear );
 225
 226     /// Internally normalizes values.
 227     static long DateToDays( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear );
 228     /// Semantically identical to IsValidDate() member method.
 229     static bool IsValidDate( sal_uInt16 nDay, sal_uInt16 nMonth, sal_Int16 nYear );
 230     /// Semantically identical to Normalize() member method.
 231     static bool Normalize( sal_uInt16 & rDay, sal_uInt16 & rMonth, sal_Int16 & rYear );
 232
 233  private:
 234     /// An accelerated form of DateToDays on this date
 235     long GetAsNormalizedDays() const;
 236 };
 237
 238 #endif
 239
 240 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */