nlib
nn::nlib::DateTime Class Referencefinal

The class for representing the date and time. More...

#include "nn/nlib/DateTime.h"

Public Types

enum  Week {
  kWeekSunday = 0,
  kWeekMonday,
  kWeekTuesday,
  kWeekWednesday,
  kWeekThursday,
  kWeekFriday,
  kWeekSaturday
}
 Constants representing the days of the week. More...
 

Public Member Functions

errno_t GetDay (int *year, int *month, int *day) const noexcept
 Gets the year, month, and day. You may specify a null character for an unnecessary value. More...
 
errno_t GetTime (int *hour, int *min, int *sec, int *msec, int *usec) const noexcept
 Gets the time. You may specify a null character for an unnecessary value. More...
 
errno_t Get (DateTimeParams *rhs) const noexcept
 Gets the time. More...
 
TimeValue ToTimeValue () const noexcept
 Returns a TimeValue object.
 
bool IsValid () const noexcept
 Checks whether the time is valid. More...
 
errno_t GetDayOfYear (int *nth) const noexcept
 Gets the day of the year based on the specified date and time. More...
 
errno_t GetDayOfWeek (Week *week) const noexcept
 Gets what day of the week it is. More...
 
errno_t Add (const TimeSpan &rhs) noexcept
 Adds the duration specified in rhs to the date and time. More...
 
errno_t AddYears (int value) noexcept
 Adds the number of years specified in value to the date and time. More...
 
errno_t AddMonths (int value) noexcept
 Adds the number of months specified in value to the date and time. More...
 
errno_t AddDays (double value) noexcept
 Adds the number of days specified in value to the date and time. More...
 
errno_t AddHours (double value) noexcept
 Adds the number of hours specified in value to the date and time. More...
 
errno_t AddMinutes (double value) noexcept
 Adds the number of minutes specified in value to the date and time. More...
 
errno_t AddSeconds (double value) noexcept
 Adds the number of seconds specified in value to the date and time. More...
 
errno_t AddMilliSeconds (double value) noexcept
 Adds the number of milliseconds specified in value to the date and time. More...
 
errno_t AddMicroSeconds (double value) noexcept
 Adds the number of microseconds specified in value to the date and time. More...
 
errno_t ToW3cDtf (char(&str)[32], const TimeSpan &zone) const noexcept
 Outputs the date and time as a string in W3CDTF format. More...
 
errno_t ToW3cDtf (char(&str)[32]) const noexcept
 Calls ToW3cDtf(str, TimeSpan()).
 
errno_t ToRfc2822 (char(&str)[32], const TimeSpan &zone) const noexcept
 Outputs the date and time as a string in RFC 2822 format. More...
 
errno_t ToRfc2822 (char(&str)[32]) const noexcept
 Calls ToRfc2822(str, TimeSpan()).
 
errno_t ToAscTime (char(&str)[26]) const noexcept
 Outputs the date and time as a string in asctime format. Note that the string ends with a newline character. More...
 
 operator bool () const
 Returns true if the time being held is valid.
 
DateTimeoperator+= (const TimeSpan &rhs) noexcept
 Adds the time indicated by rhs.
 
DateTimeoperator-= (const TimeSpan &rhs) noexcept
 Subtracts the time indicated by rhs.
 
 DateTime (const struct timespec *tm) noexcept
 Instantiates the object from the timespec structure.
 
void ToTimeSpec (struct timespec *tm) const noexcept
 Converts to a value of the timespec structure.
 
Constructor, Destructor, and Initialization
constexpr DateTime () noexcept
 Instantiates the object with default parameters (default constructor). Initializes with an invalid time.
 
errno_t Init (int year, int month, int day, int hour=0, int min=0, int sec=0, int msec=0, int usec=0) noexcept
 Initializes the time. More...
 
errno_t Init (const DateTimeParams &rhs) noexcept
 Initializes the date and time using the DateTimeParams structure. Returns EINVAL if given an invalid date.
 
errno_t Init (const TimeValue &tv) noexcept
 Initializes the date and time using the TimeValue structure. Returns EINVAL if given an invalid date.
 

Static Public Member Functions

static constexpr bool IsLeapYear (int year) noexcept
 Checks whether the specified year is a leap year. More...
 
static errno_t GetNow (DateTime *p) noexcept
 Sets the DateTime object based on the current time. More...
 
static int GetDaysInMonth (int year, int month) noexcept
 Gets the number of days in a particular month, based on the specified year and month. More...
 
static std::pair< const char *, errno_tParse (const char *first, const char *last, DateTime *dt, TimeSpan *delta) noexcept
 Parses the string that denotes the date and time and sets it in a DateTime object and a TimeSpan object. More...
 
static errno_t Parse (const char *str, DateTime *dt, TimeSpan *delta)
 Parses a string that is terminated with a null character. If a character that is not parsed is encountered before reaching the terminating null character, an error occurs.
 
static bool IsRfc3339 (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Specify a string to determine whether it is a time string complying with RFC3339. More...
 
static bool IsRfc3339 (const nlib_utf8_t *str) noexcept
 A parameter omitted version of the above function which receives a null terminated string.
 

Detailed Description

The class for representing the date and time.

Description
Represents the date and the time, between 00::00 of January 1 of the year 1, to 23:59:59.999 of December 31 of the year 9999. Each day is treated as having exactly 86,400 seconds.
The date and time is represented internally as a 64-bit integer value, where 1 = 100 nanoseconds. You can use the various member functions and operators to compare dates and times and to perform operations like addition and subtraction on them.
The addition and subtraction TimeSpan objects is also supported.
Examples:
misc/datetime/datetime.cpp, misc/threading/tls/tls.cpp, msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

Definition at line 231 of file DateTime.h.

Member Enumeration Documentation

◆ Week

Constants representing the days of the week.

Enumerator
kWeekSunday 

Sunday.

kWeekMonday 

Monday.

kWeekTuesday 

Tuesday.

kWeekWednesday 

Wednesday.

kWeekThursday 

Thursday.

kWeekFriday 

Friday.

kWeekSaturday 

Saturday.

Definition at line 234 of file DateTime.h.

Member Function Documentation

◆ Add()

nn::nlib::DateTime::Add ( const TimeSpan rhs)
inlinenoexcept

Adds the duration specified in rhs to the date and time.

Parameters
[in]rhsA duration of time.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.

Definition at line 362 of file DateTime.h.

◆ AddDays()

nn::nlib::DateTime::AddDays ( double  value)
inlinenoexcept

Adds the number of days specified in value to the date and time.

Parameters
[in]valueA number of days.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.
Description
Sample code is provided below.
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("Now: %s\n", w3cdtf);
dt.AddDays(1.5);
dt.ToW3cDtf(w3cdtf);
nlib_printf("1.5 days from now: %s\n", w3cdtf);
/*
Output:
Now: 2017-12-26T04:40:29.00Z
1.5 days from now: 2017-12-27T16:40:29.00Z
*/

Definition at line 367 of file DateTime.h.

◆ AddHours()

nn::nlib::DateTime::AddHours ( double  value)
inlinenoexcept

Adds the number of hours specified in value to the date and time.

Parameters
[in]valueA number of hours.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.
Description
Sample code is provided below.
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("Now: %s\n", w3cdtf);
dt.AddHours(24 * 365);
dt.ToW3cDtf(w3cdtf);
nlib_printf("24x365 hours from now: %s\n", w3cdtf);
/*
Output:
Now: 2017 - 12 - 26T04 : 57 : 15.00Z
24x365 hours from now : 2018 - 12 - 26T04 : 57 : 15.00Z
*/

Definition at line 373 of file DateTime.h.

◆ AddMicroSeconds()

nn::nlib::DateTime::AddMicroSeconds ( double  value)
inlinenoexcept

Adds the number of microseconds specified in value to the date and time.

Parameters
[in]valueA number of microseconds.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.

Definition at line 397 of file DateTime.h.

◆ AddMilliSeconds()

nn::nlib::DateTime::AddMilliSeconds ( double  value)
inlinenoexcept

Adds the number of milliseconds specified in value to the date and time.

Parameters
[in]valueA number of milliseconds.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.

Definition at line 391 of file DateTime.h.

◆ AddMinutes()

nn::nlib::DateTime::AddMinutes ( double  value)
inlinenoexcept

Adds the number of minutes specified in value to the date and time.

Parameters
[in]valueA number of minutes.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.

Definition at line 379 of file DateTime.h.

◆ AddMonths()

nn::nlib::DateTime::AddMonths ( int  value)
noexcept

Adds the number of months specified in value to the date and time.

Parameters
[in]valueA number of months.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.
Description
If the addition operations results in a date that does not exist (such as 2000-02-29), the value is set to the last day of the relevant month. Sample code is provided below.
errno_t e = dt.Init(2015, 12, 31);
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("Base: %s\n", w3cdtf);
for (int i = 1; i <= 15; ++i) {
dt2 = dt;
dt2.AddMonths(i);
dt2.ToW3cDtf(w3cdtf);
nlib_printf("%d months(s) from the base: %s\n", i, w3cdtf);
}
/*
Output:
Base: 2015-12-31T00:00:00.00Z
1 months(s) from the base: 2016-01-31T00:00:00.00Z
2 months(s) from the base: 2016-02-29T00:00:00.00Z
3 months(s) from the base: 2016-03-31T00:00:00.00Z
4 months(s) from the base: 2016-04-30T00:00:00.00Z
5 months(s) from the base: 2016-05-31T00:00:00.00Z
6 months(s) from the base: 2016-06-30T00:00:00.00Z
7 months(s) from the base: 2016-07-31T00:00:00.00Z
8 months(s) from the base: 2016-08-31T00:00:00.00Z
9 months(s) from the base: 2016-09-30T00:00:00.00Z
10 months(s) from the base: 2016-10-31T00:00:00.00Z
11 months(s) from the base: 2016-11-30T00:00:00.00Z
12 months(s) from the base: 2016-12-31T00:00:00.00Z
13 months(s) from the base: 2017-01-31T00:00:00.00Z
14 months(s) from the base: 2017-02-28T00:00:00.00Z
15 months(s) from the base: 2017-03-31T00:00:00.00Z
*/

◆ AddSeconds()

nn::nlib::DateTime::AddSeconds ( double  value)
inlinenoexcept

Adds the number of seconds specified in value to the date and time.

Parameters
[in]valueA number of seconds.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.

Definition at line 385 of file DateTime.h.

◆ AddYears()

nn::nlib::DateTime::AddYears ( int  value)
noexcept

Adds the number of years specified in value to the date and time.

Parameters
[in]valueA number of years.
Returns
Returns 0 if successful, or ERANGE if DateTime is or will be invalid.
Description
If the addition operations results in a date that does not exist (such as 2000-02-29), the value is set to the last day of the relevant month. Sample code is provided below.
errno_t e = dt.Init(2016, 2, 29);
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("Base: %s\n", w3cdtf);
for (int i = 1; i <= 5; ++i) {
dt2 = dt;
dt2.AddYears(-i);
dt2.ToW3cDtf(w3cdtf);
nlib_printf("%d year(s) ago: %s\n", i, w3cdtf);
}
nlib_printf("\n");
for (int i = 1; i <= 5; ++i) {
dt2 = dt;
dt2.AddYears(i);
dt2.ToW3cDtf(w3cdtf);
nlib_printf("%d year(s) from the base: %s\n", i, w3cdtf);
}
/*
Output:
Base: 2016-02-29T00:00:00.00Z
1 year(s) ago: 2015-02-28T00:00:00.00Z
2 year(s) ago: 2014-02-28T00:00:00.00Z
3 year(s) ago: 2013-02-28T00:00:00.00Z
4 year(s) ago: 2012-02-29T00:00:00.00Z
5 year(s) ago: 2011-02-28T00:00:00.00Z
1 year(s) from the base: 2017-02-28T00:00:00.00Z
2 year(s) from the base: 2018-02-28T00:00:00.00Z
3 year(s) from the base: 2019-02-28T00:00:00.00Z
4 year(s) from the base: 2020-02-29T00:00:00.00Z
5 year(s) from the base: 2021-02-28T00:00:00.00Z
*/

◆ Get()

nn::nlib::DateTime::Get ( DateTimeParams rhs) const
noexcept

Gets the time.

Parameters
[out]rhsThe pointer to the structure when the time is written.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.
Description
Sample code is provided below.
errno_t e = nlib_ns::DateTime::Parse("1994-11-05T08:15:30-05:00", &dt, &delta);
SUCCEED_IF(e == 0);
dt.Get(&params);
nlib_printf("Year: %d\nMonth: %d\nDay: %d\n", params.year, params.month, params.day);
nlib_printf("Hour: %d\nMinute: %d\nSecond: %d\n", params.hour, params.min, params.sec);
/*
Output:
Year: 1994
Month: 11
Day: 5
Hour: 8
Minute: 15
Second: 30
*/

◆ GetDay()

nn::nlib::DateTime::GetDay ( int *  year,
int *  month,
int *  day 
) const
noexcept

Gets the year, month, and day. You may specify a null character for an unnecessary value.

Parameters
[out]yearThe year (1-9999).
[out]monthThe month (1-12).
[out]dayThe day (1-).
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.

◆ GetDayOfWeek()

nn::nlib::DateTime::GetDayOfWeek ( Week week) const
noexcept

Gets what day of the week it is.

Parameters
[out]weekThe day of the week.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.

◆ GetDayOfYear()

nn::nlib::DateTime::GetDayOfYear ( int *  nth) const
noexcept

Gets the day of the year based on the specified date and time.

Parameters
[out]nthThe number of days since the start of the specified year, counted starting from 0.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.

◆ GetDaysInMonth()

nn::nlib::DateTime::GetDaysInMonth ( int  year,
int  month 
)
staticnoexcept

Gets the number of days in a particular month, based on the specified year and month.

Parameters
[in]yearA year.
[in]monthA month.
Returns
The number of days in that month, or 0 if there was an error.

◆ GetNow()

nn::nlib::DateTime::GetNow ( DateTime p)
staticnoexcept

Sets the DateTime object based on the current time.

Parameters
[out]pThe pointer to the DateTime.
Returns
Returns 0 if successful, and another value if the function fails.
Description
Sample code is provided below.
dt.ToW3cDtf(w3cdtf);
nlib_printf("%s\n", w3cdtf);
/*
Output:
2017-12-24T21:00:00.00Z
*/

◆ GetTime()

nn::nlib::DateTime::GetTime ( int *  hour,
int *  min,
int *  sec,
int *  msec,
int *  usec 
) const
noexcept

Gets the time. You may specify a null character for an unnecessary value.

Parameters
[out]hourThe hour (1-23).
[out]minThe minute (0-59).
[out]secThe second (0-59).
[out]msecThe millisecond (0-999).
[out]usecThe microsecond (0-999).
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.

◆ Init()

nn::nlib::DateTime::Init ( int  year,
int  month,
int  day,
int  hour = 0,
int  min = 0,
int  sec = 0,
int  msec = 0,
int  usec = 0 
)
noexcept

Initializes the time.

Parameters
[in]yearThe year (1-1999).
[in]monthThe month (1-12).
[in]dayThe day (1-).
[in]hourThe hour (0-23).
[in]minThe minute (0-59).
[in]secThe second (0-59).
[in]msecThe millisecond (0-999).
[in]usecThe microsecond (0-999999).
Returns
Returns 0 if successful, or EINVAL if an invalid date and time has been specified.
Description
Specify numerical values to set the date.
errno_t e = dt.Init(1973, 11, 10);
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("%s\n", w3cdtf);
e = dt.Init(2018, 2, 29);
SUCCEED_IF(e == EINVAL);
/*
Output:
1973-11-10T00:00:00.00Z
*/

◆ IsLeapYear()

nn::nlib::DateTime::IsLeapYear ( int  year)
inlinestaticnoexcept

Checks whether the specified year is a leap year.

Parameters
[in]yearThe year to check.
Returns
Returns true if it is a leap year, and false otherwise.

Definition at line 323 of file DateTime.h.

◆ IsRfc3339()

nn::nlib::DateTime::IsRfc3339 ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Specify a string to determine whether it is a time string complying with RFC3339.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Returns
If true is returned, the string is a time string that complies with RFC 3339.

◆ IsValid()

nn::nlib::DateTime::IsValid ( ) const
noexcept

Checks whether the time is valid.

Returns
Returns true if the time is valid (that is, some time between 00::00 of January 1 of the year 1 and 23:59:59.999 of December 31 of the year 9999).

◆ Parse()

nn::nlib::DateTime::Parse ( const char *  first,
const char *  last,
DateTime dt,
TimeSpan delta 
)
staticnoexcept

Parses the string that denotes the date and time and sets it in a DateTime object and a TimeSpan object.

Parameters
[in]firstThe first character of a string denoting a date and time.
[in]lastThe last character of a string denoting a date and time.
[out]dtStores the date and time information.
[out]deltaStores the time zone information (for example, +09:00 hours).
Returns
If successful, returns a pair of the pointer to the first character that is not parsed and 0, otherwise returns a pair of first and a nonzero value.
Description
The date and time notation supports W3C-DTF(RFC3339), RFC2822, or asctime format.
The parsing supports W3CDTF date and time notation where '-' is replaced by '/' and 'T' is replaced by a blank space. In other words, the following non-standard strings can also be parsed.
  • 2012/09/10
  • 2012/09/10 17:27
Sample code is provided below.
errno_t e = nlib_ns::DateTime::Parse("1994-11-05T08:15:30-05:00", &dt, &delta);
SUCCEED_IF(e == 0);
dt.Get(&params);
nlib_printf("Year: %d\nMonth: %d\nDay: %d\n", params.year, params.month, params.day);
nlib_printf("Hour: %d\nMinute: %d\nSecond: %d\n", params.hour, params.min, params.sec);
/*
Output:
Year: 1994
Month: 11
Day: 5
Hour: 8
Minute: 15
Second: 30
*/
See also
http://www.w3.org/TR/NOTE-datetime (W3C-DTF)
https://www.ietf.org/rfc/rfc2822.txt (RFC2822)
http://srgia.com/docs/rfc2822j.html (RFC2822, in Japanese)
https://tools.ietf.org/html/rfc3339 (RFC3339)

◆ ToAscTime()

nn::nlib::DateTime::ToAscTime ( char(&)  str[26]) const
noexcept

Outputs the date and time as a string in asctime format. Note that the string ends with a newline character.

Parameters
[out]strThe buffer for the 26-byte output string.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.
Description
Sample code is provided below.
errno_t e = dt.Init(1973, 11, 10);
SUCCEED_IF(e == 0);
dt.ToAscTime(asctime);
nlib_printf("%s\n", asctime);
/*
Output:
Sat Nov 10 00:00:00 1973
*/

◆ ToRfc2822()

nn::nlib::DateTime::ToRfc2822 ( char(&)  str[32],
const TimeSpan zone 
) const
noexcept

Outputs the date and time as a string in RFC 2822 format.

Parameters
[out]strThe buffer for the 32-byte output string.
[in]zoneThe time zone.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.
Description
Sample code is provided below.
errno_t e = dt.Init(1973, 11, 10);
SUCCEED_IF(e == 0);
dt.ToRfc2822(rfc2822);
nlib_printf("%s\n", rfc2822);
/*
Output:
Sat, 10 Nov 1973 00:00:00 +0000
*/

◆ ToW3cDtf()

nn::nlib::DateTime::ToW3cDtf ( char(&)  str[32],
const TimeSpan zone 
) const
noexcept

Outputs the date and time as a string in W3CDTF format.

Parameters
[out]strThe buffer for the 32-byte output string.
[in]zoneThe time zone.
Returns
Returns 0 if successful, or ERANGE if DateTime is invalid.
Description
Sample code is provided below.
errno_t e = dt.Init(1973, 11, 10);
SUCCEED_IF(e == 0);
dt.ToW3cDtf(w3cdtf);
nlib_printf("%s\n", w3cdtf);
e = dt.Init(2018, 2, 29);
SUCCEED_IF(e == EINVAL);
/*
Output:
1973-11-10T00:00:00.00Z
*/

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