cxDate.h

Go to the documentation of this file.

// Copyright (c) 2026 E. Oulashin
#ifndef __CXDATE_H__
#define __CXDATE_H__
 
// Copyright (c) 2007 Eric Oulashin
//
// cxDate.h - C++17-improved date class for the cxWidgets library.
// This is a modernized version of the original 'date' class (date.h/date.cpp),
// renamed to cxDate to follow cxWidgets naming conventions, and updated to use
// C++17 standard features throughout.
//
// Changes from the original 'date' class:
//  - Class renamed from 'date' to 'cxDate'
//  - [[nodiscard]] attributes added to accessor/query methods
//  - noexcept specifications added to non-throwing methods
//  - std::string_view used for read-only string parameters
//  - std::optional<cxDate> returned by tryParse() for safe parsing
//  - std::chrono used in today() for current date retrieval
//  - std::stoi() replaces atoi() for safer string-to-int conversion
//  - std::to_string() replaces the custom anythingToString<T>() template
//  - inline constexpr replaces #define for numeric constants
//  - static cxDate today() added as a clear, expressive convenience method
//  - Default member initializers used in the class definition
//  - = default used for copy constructor, copy assignment, and destructor
//  - std::clamp used for range-clamping in validateDateElements()
 
#include <string>
#include <string_view>
#include <iostream>
#include <optional>
 
namespace cx {
 
// Date format enumeration (kept compatible with original date.h)
enum eDateFormats
{
   YYYY_MM_DD,
   MM_DD_YYYY,
   DD_MM_YYYY,
   YY_MM_DD,
   MM_DD_YY,
   DD_MM_YY,
   YYYYMMDD,
   MMDDYYYY,
   DDMMYYYY,
   YYMMDD,
   MMDDYY,
   DDMMYY,
   UNKNOWN
};
 
enum eWeekDays
{
   eSUNDAY,
   eMONDAY,
   eTUESDAY,
   eWEDNESDAY,
   eTHURSDAY,
   eFRIDAY,
   eSATURDAY
};
 
// C++17: inline constexpr replaces #define for compile-time constants
inline constexpr int CXDATE_DEFAULT_YEAR           = 2000;
inline constexpr int CXDATE_YEAR_2DIGIT_LAST_CENT  = 49;
inline constexpr int CXDATE_MONTHS_IN_YEAR         = 12;
inline constexpr int CXDATE_START_MONTH            = 1;
inline constexpr int CXDATE_END_MONTH              = 12;
inline constexpr int CXDATE_START_DAY              = 1;
inline constexpr int CXDATE_YEAR_MIN               = 1800;
inline constexpr int CXDATE_YEAR_MAX               = 2500;
 
class cxDate
{
public:
   // -----------------------------------------------------------------------
   // Constructors / Destructor
   // -----------------------------------------------------------------------
 
   explicit cxDate(eDateFormats pDateFormat = YYYY_MM_DD, char pSepChar = '-');
 
   cxDate(int pYear, int pMonth, int pDay,
          eDateFormats pDateFormat = YYYY_MM_DD,
          char pSepChar = '-') noexcept;
 
   cxDate(std::string_view pDateStr,
          eDateFormats pDateFormat = YYYY_MM_DD,
          char pSepChar = '-');
 
   cxDate(std::string_view pDateStr, char pSepChar);
 
   cxDate(long pJulianDate,
          eDateFormats pDateFormat = YYYY_MM_DD,
          char pSepChar = '-') noexcept;
 
   virtual ~cxDate() = default;
   cxDate(const cxDate&) = default;
   cxDate& operator=(const cxDate&) = default;
 
   // -----------------------------------------------------------------------
   // Accessors (all [[nodiscard]] and noexcept)
   // -----------------------------------------------------------------------
 
   [[nodiscard]] int getYear() const noexcept
   {
      return mYear;
   }
   [[nodiscard]] int getMonth() const noexcept
   {
      return mMonth;
   }
   [[nodiscard]] int getDay() const noexcept
   {
      return mDay;
   }
   [[nodiscard]] eDateFormats getDateFormat() const noexcept
   {
      return mDateFormat;
   }
   [[nodiscard]] char getSepChar() const noexcept
   {
      return mSepChar;
   }
   [[nodiscard]] bool getDisplayLong() const noexcept
   {
      return mDisplayLong;
   }
 
   // -----------------------------------------------------------------------
   // Mutators
   // -----------------------------------------------------------------------
 
   void setYear(int pYear)   noexcept;
   void setMonth(int pMonth) noexcept;
   void setDay(int pDay)     noexcept;
   void setDateFormat(eDateFormats pDateFormat) noexcept;
   void setSepChar(char pSepChar) noexcept
   {
      mSepChar = pSepChar;
   }
   void setDisplayLong(bool pDisplay) noexcept
   {
      mDisplayLong = pDisplay;
   }
 
   [[nodiscard]] bool setDate(int pYear, int pMonth, int pDay) noexcept;
 
   // -----------------------------------------------------------------------
   // Date arithmetic
   // -----------------------------------------------------------------------
 
   void addYears(int pNumYears)        noexcept;
   void subtractYears(int pNumYears)   noexcept;
   void addMonths(int pNumMonths)      noexcept;
   void subtractMonths(int pNumMonths) noexcept;
   void addDays(int pNumDays)          noexcept;
   void subtractDays(int pNumDays)     noexcept;
 
   // -----------------------------------------------------------------------
   // Operators
   // -----------------------------------------------------------------------
 
   void operator+=(int pNumDays) noexcept;
   void operator-=(int pNumDays) noexcept;
 
   [[nodiscard]] bool operator==(const cxDate& pThat) const noexcept;
   [[nodiscard]] bool operator!=(const cxDate& pThat) const noexcept;
   [[nodiscard]] bool operator> (const cxDate& pThat) const noexcept;
   [[nodiscard]] bool operator>=(const cxDate& pThat) const noexcept;
   [[nodiscard]] bool operator< (const cxDate& pThat) const noexcept;
   [[nodiscard]] bool operator<=(const cxDate& pThat) const noexcept;
 
   cxDate  operator++(int) noexcept;  // post-increment (advance one day)
   cxDate& operator++()    noexcept;  // pre-increment  (advance one day)
   cxDate  operator--(int) noexcept;  // post-decrement (go back one day)
   cxDate& operator--()    noexcept;  // pre-decrement  (go back one day)
 
   [[nodiscard]] cxDate operator+(int pNumDays)       const noexcept;
   [[nodiscard]] cxDate operator-(int pNumDays)       const noexcept;
   [[nodiscard]] int    operator-(const cxDate& pThat) const noexcept;
 
   friend std::ostream& operator<<(std::ostream& pOS, const cxDate& pDate);
   friend std::istream& operator>>(std::istream& pIS, cxDate& pDate);
 
   // -----------------------------------------------------------------------
   // String conversion
   // -----------------------------------------------------------------------
 
   [[nodiscard]] std::string toString() const;
   bool fromString(std::string_view pDateStr);
 
   // -----------------------------------------------------------------------
   // Utility
   // -----------------------------------------------------------------------
 
   [[nodiscard]] int       numMonthDays()  const noexcept;
   [[nodiscard]] bool      isLeapYear()    const noexcept;
   [[nodiscard]] eWeekDays dayOfWeek()     const noexcept;
   [[nodiscard]] std::string dayOfWeekStr()  const;
 
   // -----------------------------------------------------------------------
   // Static methods
   // -----------------------------------------------------------------------
 
   [[nodiscard]] static int       numMonthDays(int pMonth, int pYear)       noexcept;
   [[nodiscard]] static bool      isLeapYear(int pYear)                     noexcept;
   [[nodiscard]] static eWeekDays dayOfWeek(int pYear, int pMonth, int pDay) noexcept;
   [[nodiscard]] static std::string dayOfWeekStr(eWeekDays pWeekDay);
   [[nodiscard]] static std::string dayOfWeekStr(int pYear, int pMonth, int pDay);
   [[nodiscard]] static std::string monthName(int pMonth, bool pAbbreviated = false);
 
   [[nodiscard]] static std::string getToday(bool pLong = false);
   [[nodiscard]] static int     getCurrentYear() noexcept;
 
   [[nodiscard]] static cxDate today() noexcept;
 
   [[nodiscard]] static std::optional<cxDate> tryParse(
      std::string_view pDateStr,
      eDateFormats pDateFormat = YYYY_MM_DD,
      char pSepChar = '-');
 
   // -----------------------------------------------------------------------
   // Julian date conversions
   // -----------------------------------------------------------------------
 
   [[nodiscard]] long toJulian() const noexcept;
   static long  toJulian(int pYear, int pMonth, int pDay) noexcept;
   void         fromJulian(long pJulianDate)               noexcept;
   static void  fromJulian(long pJulianDate, int& pYear, int& pMonth, int& pDay) noexcept;
 
   // -----------------------------------------------------------------------
   // Date format detection
   // -----------------------------------------------------------------------
 
   [[nodiscard]] static eDateFormats getDateFormat(std::string_view pDateStr);
   [[nodiscard]] static std::string getDateFormatStr(eDateFormats pDateFormat);
 
   // -----------------------------------------------------------------------
   // Calendar output
   // -----------------------------------------------------------------------
 
   static void monthCalendar(int pYear, int pMonth,
                              std::ostream& pOutStream = std::cout,
                              int pTrailingEndlines = 2);
   static void yearCalendar(int pYear,
                             std::ostream& pOutStream = std::cout,
                             int pTrailingEndlines = 2);
 
private:
   int          mYear        = CXDATE_DEFAULT_YEAR;
   int          mMonth       = 1;
   int          mDay         = 1;
   eDateFormats mDateFormat  = YYYY_MM_DD;
   char         mSepChar     = '-';
   bool         mDisplayLong = false;
 
   // Validates and clamps month/day to legal ranges.
   // Returns true if all values were already valid.
   static bool validateDateElements(int pYear, int& pMonth, int& pDay) noexcept;
 
   [[nodiscard]] static std::string getMonthName(int pMonth);
   [[nodiscard]] static bool        allDigits(std::string_view pStr) noexcept;
};
 
} // namespace cx
 
#endif // __CXDATE_H__