Date is an immutable class representing a date without a time zone in the ISO-8601 calendar system, such as "2017-12-15". More...

#include <date.hpp>

Public Types
Enumerations
enum class	Weekday { Monday = 1 , Tuesday = 2 , Wednesday = 3 , Thursday = 4 , Friday = 5 , Saturday = 6 , Sunday = 7 }
	Type of weekday.

enum class	Month { January = 1 , February = 2 , March = 3 , April = 4 , May = 5 , June = 6 , July = 7 , August = 8 , September = 9 , October = 10 , November = 11 , December = 12 }
	Type of month.

Durations
using	Days = internal::Days
	Day duration.

using	Weeks = std::chrono::duration< long, std::ratio_multiply< std::ratio< 7 >, Days::period > >
	Week duration.

Public Member Functions
Constructors and Destructors
	Date ()
	Constructs an invalid Date object with every field is set to zero. More...

	Date (const Date &other)=default
	Copy-constructs a Date object from `other`.

	Date (Date &&other)=default
	Move-constructs a Date object from `other`.

	Date (const Days &days)
	Constructs a Date object from `days` elapsed since the epoch "1970-01-01".

	Date (int year, int month, int day)
	Constructs a Date object from the given `year`, `month` and `day`.

	~Date ()=default
	Default destructor.

Assignment Operators
Date &	operator= (const Date &other)=default
	Copy assignment operator.

Date &	operator= (Date &&other)=default
	Move assignment operator.

Comparison Operators
bool	operator< (const Date &other) const
	Returns whether this date is earlier than `other`.

bool	operator<= (const Date &other) const
	Returns whether this date is earlier than `other` or equal to it.

bool	operator> (const Date &other) const
	Returns whether this date is later than `other`.

bool	operator>= (const Date &other) const
	Returns whether this date is later than `other` or equal to it.

bool	operator== (const Date &other) const
	Returns whether this date is equal to `other`.

bool	operator!= (const Date &other) const
	Returns whether this date is different from `other`.

Querying Methods
bool	isValid () const
	Returns whether this date object represents a valid date. More...

void	getYearMonthDay (int year, int month, int *day) const
	Set the year, month, and day of this date in the parameters `year`, `month`, and `day`, respectively.

int	day () const
	Returns the day of the month of this date as a number between 1 and 31.

int	month () const
	Returns the month of the year of this date as a number between 1 and 12, which corresponds to the enumeration Month.

int	year () const
	Returns the year of this date as a number. More...

int	dayOfWeek () const
	Returns the weekday of this date as a number between 1 and 7, which corresponds to the enumeration Weekday.

int	dayOfYear () const
	Returns the day of year of this date as a number between 1 and 365 (1 to 366 on leap years).

int	daysInMonth () const
	Returns the number of days in the month of this date. It ranges between 28 and 31.

int	daysInYear () const
	Returns the number of days in the year of this date. It is either 365 or 366.

bool	isLeapYear () const
	Returns whether the year of this date is a leap year. More...

int	weekOfYear (int *weekYear=nullptr) const
	Returns the week of the year of this date, and optionally stores the year in weekYear. More...

std::string	dayOfWeekName (bool shortName=false) const
	Returns the name of the weekday of this date. More...

std::string	monthName (bool shortName=false) const
	Returns the name of the month of this date. More...

Addition/Subtraction Methods
Date	addDays (int days) const
	Returns the result of adding `days` to this date as a new Date object.

Date	subtractDays (int days) const
	Returns the result of subtracting `days` from this date as a new Date object.

Date	addMonths (int months) const
	Returns the result of adding `months` to this date as a new Date object. More...

Date	subtractMonths (int months) const
	Returns the result of subtracting `months` from this date as a new Date object. More...

Date	addYears (int years) const
	Returns the result of adding `years` to this date as a new Date object.

Date	subtractYears (int years) const
	Returns the result of subtracting `years` from this date as a new Date object.

Conversion Methods
long	toDaysSinceEpoch () const
	Returns the number of elapsed days since the epoch "1970-01-01".

Days	toStdDurationSinceEpoch () const
	Returns the elapsed time since the epoch "1970-01-01" as a Days duration.

long	toJulianDay () const
	Returns the corresponding Julian Day Number (JDN) of this date. More...

std::string	toString (const std::string &format) const
	Returns this date as a string, formatted according to the format string `format`. More...

Static Public Member Functions
static Date	current ()
	Returns a Date object set to the current date obtained from the system clock. More...

static Date	epoch ()
	Returns a Date object set to the epoch "1970-01-01".

static Date	fromString (const std::string &date, const std::string &format)
	Returns a Date object from the date string `date` according to the format string `format`. More...

static Date	fromJulianDay (long julianDay)
	Returns a Date object corresponding to the Julian day `julianDay`. More...

static bool	isLeapYear (int year)
	Returns whether `year` is a leap year. More...

static int	daysInMonthOfYear (int year, int month)
	Returns the number of days in `month` of `year`. It ranges between 28 and 31.

Calculation Methods
The following methods return the time difference between two dates; `from` and `to`. If `to` is earlier than (smaller than) `from`, then the difference is negative.
static long	daysBetween (const Date &from, const Date &to)
	Returns the number of days between `from` and `to`. More...

static long	weeksBetween (const Date &from, const Date &to)
	Returns the number of weeks between `from` and `to`. More...

Related Functions
(Note that these are not member functions.)
Input/Output Operators
std::ostream &	operator<< (std::ostream &os, const Date &d)
	Writes date `d` to stream `os` in ISO-8601 date format, "yyyy-MM-dd". More...

std::istream &	operator>> (std::istream &is, Date &d)
	Reads a date in ISO-8601 date format "yyyy-MM-dd" from stream `is` and stores it in date `d`. More...

Detailed Description

Date is an immutable class representing a date without a time zone in the ISO-8601 calendar system, such as "2017-12-15".

The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system.

Date describes the date as a triple (year, month, day). There is no year 0, and dates with a year 0 are considered invalid. Negative years indicate years before the common era (BCE). So, year -1 represents year 1 BCE, year -2 represents year 2 BCE, and so on.

A default-constructed Date object is invalid (calling isValid() on it returns false). Date objects can be created by explicitly giving the number of years, months and days. Also, it can be created from the number of days since the epoch "1970-01-01".

The year, month, and day of the date can be accessed through the methods year(), month(), and day(), respectively. Other date fields, such as day-of-year, day-of-week, and week-of-year, can also be accessed through dayOfYear(), dayOfWeek(), and weekOfYear(), respectively.

Date defines two durations: Days and Weeks, and two enumerations: Weekday and Month.

Date provides methods for manipulating dates. Years, months, and days can be added to a date (through addYears(), addMonths(), and addDays(), respectively) or subtracted from it (through subtractYears(), subtractMonths(), and subtractDays(), respectively).

It also provides operators for comparing dates. Date A is considered earlier than Date B if A is smaller than B, and so on. The methods daysBetween() and weeksBetween() returns how many days and weeks are between two dates, respectively.

Also, Date provides the methods fromJulianDay() and toJulianDay() to convert a date from and to a Julian Day Number (JDN). The toString() method can be used to get a textual representation of the date formatted according to a given format string.

See also: The unit tests in date.h for further details.

Constructor & Destructor Documentation

◆ Date()

xclox::Date::Date ( )

inline

Constructs an invalid Date object with every field is set to zero.

See also: isValid()

Member Function Documentation

◆ addMonths()

Date xclox::Date::addMonths ( int months ) const

inline

Returns the result of adding months to this date as a new Date object.

When the ending day/month combination does not exist in the resulting month/year, it returns the latest valid date. For example:

Date d = Date(2013, 1, 31).addMonths(1); //d = Date(2013, 2, 28)

xclox::Date::Date

Date()

Constructs an invalid Date object with every field is set to zero.

Definition: date.hpp:142

◆ current()

static Date xclox::Date::current ( )

inlinestatic

Returns a Date object set to the current date obtained from the system clock.

Note that the returned date is not the current local date but rather the current system date in Coordinated Universal Time (UTC).

◆ dayOfWeekName()

std::string xclox::Date::dayOfWeekName ( bool shortName = false ) const

inline

Returns the name of the weekday of this date.

The short and long names of the weekdays are named according to the following convention:

Weekday No.	Short Name	Long Name
1	Mon	Monday
2	Tue	Tuesday
3	Wed	Wednesday
4	Thu	Thursday
5	Fri	Friday
6	Sat	Saturday
7	Sun	Sunday

Parameters

shortName If true, returns the short name of the weekday, such as "Sat". If false (by default), returns the long name, such as "Saturday".

◆ daysBetween()

static long xclox::Date::daysBetween	(	const Date &	from,
		const Date &	to
	)

inlinestatic

Returns the number of days between from and to.

For example:

int num = Date::daysBetween(Date(1999, 1, 1), Date(1999, 1, 3)); // num = 2

xclox::Date::daysBetween

static long daysBetween(const Date &from, const Date &to)

Returns the number of days between from and to.

Definition: date.hpp:707

◆ fromJulianDay()

static Date xclox::Date::fromJulianDay ( long julianDay )

inlinestatic

Returns a Date object corresponding to the Julian day julianDay.

See also: toJulianDay()

◆ fromString()

static Date xclox::Date::fromString	(	const std::string &	date,
		const std::string &	format
	)

inlinestatic

Returns a Date object from the date string date according to the format string format.

The format patterns are the same patterns used in the method toString().

See also: toString()

◆ isLeapYear() [1/2]

bool xclox::Date::isLeapYear ( ) const

inline

Returns whether the year of this date is a leap year.

See also: isLeapYear(int)

◆ isLeapYear() [2/2]

static bool xclox::Date::isLeapYear ( int year )

inlinestatic

Returns whether year is a leap year.

According to the ISO proleptic calendar system rules, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100 are not leap years, with the exception of years divisible by 400. For example, 1904 is a leap year; it is divisible by 4. 1900 was not a leap year, as it is divisible by 100. However, 2000 was a leap year, as it is divisible by 400.

◆ isValid()

bool xclox::Date::isValid ( ) const

inline

Returns whether this date object represents a valid date.

A valid date contains a non-zero year, a valid month (between 1 and 12), and a valid day of month (between 1 and 31).

Date d; // same as Date(0, 0, 0)
bool state1 = d.isValid(); // returns false
bool state2 = Date(1999, -1, 1).isValid(); // returns false
bool state3 = Date(1999, 1, 0).isValid(); // returns false
d = Date(1970, 1, 1);
bool state4 = d.isValid(); // returns true

◆ monthName()

std::string xclox::Date::monthName ( bool shortName = false ) const

inline

Returns the name of the month of this date.

The short and long names of the months are named according to the following convention:

Month No.	Short Name	Long Name
1	Jan	January
2	Feb	February
3	Mar	March
4	Apr	April
5	May	May
6	Jun	June
7	Jul	July
8	Aug	August
9	Sep	September
10	Oct	October
11	Nov	November
12	Dec	December

Parameters

shortName If true, returns the short name of the month, such as "Jan". If false (by default), returns the long name, such as "January".

◆ subtractMonths()

Date xclox::Date::subtractMonths ( int months ) const

inline

Returns the result of subtracting months from this date as a new Date object.

When the ending day/month combination does not exist in the resulting month/year, it returns the latest valid date. For example:

Date d = Date(2012, 3, 31).subtractMonths(1); //d = Date(2012, 2, 29)

◆ toJulianDay()

long xclox::Date::toJulianDay ( ) const

inline

Returns the corresponding Julian Day Number (JDN) of this date.

JDN is the consecutive numbering of days since the beginning of the Julian Period on 1 January 4713 BCE in the proleptic Julian calendar, which occurs on 24 November 4714 BCE in the proleptic Gregorian calender. Note that the date to be converted is considered Gregorian. Also, the current Gregorian rules are extended backwards and forwards. There is no year 0. The first year before the common era (i.e., year 1 BCE) is year -1, year -2 is year 2 BCE, and so on.

◆ toString()

std::string xclox::Date::toString ( const std::string & format ) const

inline

Returns this date as a string, formatted according to the format string format.

The format string may contain the following patterns:

Pattern	Meaning
#	era of year as a positive sign(+) or negative sign(-)
E	era of year as CE or BCE
y	year as one digit or more (1, 9999)
yy	year of era as two digits (00, 99)
yyyy	year as four digits (0000, 9999)
M	month of year as one digit or more (1, 12)
MM	month of year as two digits (01, 12)
MMM	month of year as short name (e.g. "Feb")
MMMM	month of year as long name (e.g. "February")
d	day of month as one digit or more (1, 31)
dd	day of month as two digits (00, 31)
ddd	day of week as short name (e.g. "Fri")
dddd	day of week as long name (e.g. "Friday")

Any character in the format string not listed above will be inserted as-is into the output string. If this date is invalid, an empty string will be returned.

See also: dayOfWeekName(), monthName()

◆ weekOfYear()

int xclox::Date::weekOfYear ( int * weekYear = nullptr ) const

inline

Returns the week of the year of this date, and optionally stores the year in weekYear.

The week of the year ranges between 1 and 53. Most years have 52 weeks, but some have 53. According to ISO-8601, weeks start on Monday, and the first Thursday of a year is always in week 1 of that year. weekYear is not always the same as year(). For example:

The date of "1 January 2000" falls in week 52 of the year 1999.
The date of "31 December 2002" falls in week 1 of the year 2003.
The date of "1 January 2010" falls in week 53 of the year 2009.

◆ weeksBetween()

static long xclox::Date::weeksBetween	(	const Date &	from,
		const Date &	to
	)

inlinestatic

Returns the number of weeks between from and to.

For example:

int num = Date::weeksBetween(Date(1970, 1, 1), Date(1970, 1, 8)); // num = 1

xclox::Date::weeksBetween

static long weeksBetween(const Date &from, const Date &to)

Returns the number of weeks between from and to.

Definition: date.hpp:719

◆ year()

int xclox::Date::year ( ) const

inline

Returns the year of this date as a number.

There is no year 0. Negative numbers indicate years before 1 BCE; for example, year -1 is year 1 BCE, and so on.

Friends And Related Function Documentation

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	os,
		const Date &	d
	)

See toString() for information about the format patterns.

◆ operator>>()

std::istream & operator>>	(	std::istream &	is,
		Date &	d
	)

See toString() for information about the format patterns.

The documentation for this class was generated from the following file:

include/xclox/date.hpp

Public Types

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Date()

Member Function Documentation

◆ addMonths()

◆ current()

◆ dayOfWeekName()

◆ daysBetween()

◆ fromJulianDay()

◆ fromString()

◆ isLeapYear() [1/2]

◆ isLeapYear() [2/2]

◆ isValid()

◆ monthName()

◆ subtractMonths()

◆ toJulianDay()

◆ toString()

◆ weekOfYear()

◆ weeksBetween()

◆ year()

Friends And Related Function Documentation

◆ operator<<()

◆ operator>>()