xtd::date_time Class Reference

Inheritance diagram for xtd::date_time:

Definition

Represents an instant in time, typically expressed as a date and time of day.

class core_export_ date_time : public xtd::icomparable<date_time>, public xtd::iequatable<date_time>, public xtd::object

Inheritance

xtd::object → xtd::date_time

Implements

xtd::icomparable <>, xtd::iequatable <>

Header

#include <xtd/date_time> 

Namespace

xtd

Library

xtd.core

Remarks

The xtd::date_time value type represents dates and times with values ranging from 00:00:00 (midnight), January 1, 0001 Anno Domini (Common Era) through 11:59:59 P.M., December 31, 9999 A.D. (C.E.) in the Gregorian calendar.

Time values are measured in 100-nanosecond units called ticks. A particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the GregorianCalendar calendar. The number excludes ticks that would be added by leap seconds. For example, a ticks value of 31241376000000000L represents the date Friday, January 01, 0100 12:00:00 midnight. A xtd::date_time value is always expressed in the context of an explicit or default calendar.

Note

If you are working with a ticks value that you want to convert to some other time interval, such as minutes or seconds, you should use the xtd::time_span::ticks_per_day, xtd::time_span::ticks_per_hour, xtd::time_span::ticks_per_minute, xtd::time_span::ticks_per_second, or xtd::time_span::ticks_per_millisecond constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the xtd::date_time::second component of a xtd::date_time value, you can use the expression date_value.second() + n_ticks/timespan.ticks_per_second.

Remarks

For more information about types, see Native types, boxing and unboxing. For example, a ticks value of 31241376000000000LL represents the date, Friday, January 01, 0100 12:00:00 midnight. A xtd::date_time value is always expressed in the context of an explicit or default calendar.

Instantiating a xtd::date_time object

You can create a new xtd::dateTime value in any of the following ways:

• By calling any of the overloads of the xtd::date_time constructor that allow you to specify specific elements of the date and time value (such as the year, month, and day, or the number of ticks). The following statement illustrates a call to one of the xtd::date_time constructors to create a date with a specific year, month, day, hour, minute, and second.

  xtd::date_time date1(2008, 5, 1, 8, 30, 52);

• By assigning the xtd::date_time object a date and time value returned by a property or method. The following example assigns the current date and time, the current Coordinated Universal Time (UTC) date and time, and the current date to three new date_time variables.

  date_time date1 = date_time::now();
  date_time date2 = date_time::utc_now();
  date_time date3 = date_time::today();

• By parsing the xtd::ustring representation of a date and time value. The xtd::date_time::parse, xtd::date_time::parse_exact, xtd::date_time::try_parse, and xtd::date_time::try_parse_exact methods all convert a xtd::ustring to its equivalent date and time value. The following example uses the xtd::date_time::parse method to parse a xtd::ustring and convert it to a xtd::date_time value.

  ustring date_string = "5/1/2008 8:30:52";
  date_time date1 = date_time::parse(date_string);

  Note that the xtd::date_time::try_parse and xtd::date_time::try_parse_exact methods indicate whether a particular xtd::ustring contains a valid representation of a xtd::date_time value in addition to performing the conversion.
• By calling the xtd::date_time structure's implicit default constructor. The following example illustrates a call to the xtd::date_time implicit default constructor.

  date_time dat1;
  // The following method call displays 1/01/0001 00:00:00.
  console::write_line(dat1.to_string());
  // The following method call displays true.
  console::write_line(dat1.equals(date_time::min_value));

Remarks

For more information about xtd::date_time, see Date and time.

Examples

The following example demonstrates how to compare roughly equivalent xtd::date_time values, accepting a small margin of difference when declaring them equal.

#include <xtd/console>
#include <xtd/convert>
#include <xtd/date_time>
#include <xtd/math>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto window = 10;
    auto freq = 60 * 60 * 2; // 2 hours;
    
    auto d1 = date_time::now();
    
    auto d2 = d1.add_seconds(2 * window);
    auto d3 = d1.add_seconds(-2 * window);
    auto d4 = d1.add_seconds(window / 2);
    auto d5 = d1.add_seconds(-window / 2);
    
    auto d6 = (d1.add_hours(2)).add_seconds(2 * window);
    auto d7 = (d1.add_hours(2)).add_seconds(-2 * window);
    auto d8 = (d1.add_hours(2)).add_seconds(window / 2);
    auto d9 = (d1.add_hours(2)).add_seconds(-window / 2);
    
    console::write_line("d1 ({0}) ~= d1 ({1}): {2}", d1, d1, roughly_equals(d1, d1, window, freq));
    console::write_line("d1 ({0}) ~= d2 ({1}): {2}", d1, d2, roughly_equals(d1, d2, window, freq));
    console::write_line("d1 ({0}) ~= d3 ({1}): {2}", d1, d3, roughly_equals(d1, d3, window, freq));
    console::write_line("d1 ({0}) ~= d4 ({1}): {2}", d1, d4, roughly_equals(d1, d4, window, freq));
    console::write_line("d1 ({0}) ~= d5 ({1}): {2}", d1, d5, roughly_equals(d1, d5, window, freq));
    
    console::write_line("d1 ({0}) ~= d6 ({1}): {2}", d1, d6, roughly_equals(d1, d6, window, freq));
    console::write_line("d1 ({0}) ~= d7 ({1}): {2}", d1, d7, roughly_equals(d1, d7, window, freq));
    console::write_line("d1 ({0}) ~= d8 ({1}): {2}", d1, d8, roughly_equals(d1, d8, window, freq));
    console::write_line("d1 ({0}) ~= d9 ({1}): {2}", d1, d9, roughly_equals(d1, d9, window, freq));
  }
  
private:
  static bool roughly_equals(const date_time& time, const date_time& time_with_window, int window_in_seconds, int frequency_in_seconds) {
    auto delta = convert::to_int32((time_with_window - time).total_seconds_duration().count()) % frequency_in_seconds;
    
    delta = delta > window_in_seconds ? frequency_in_seconds - delta : delta;
    
    return math::abs(delta) < window_in_seconds;
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// d1 (Thu Dec 30 16:18:10 2021) ~= d1 (Thu Dec 30 16:18:10 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d2 (Thu Dec 30 16:18:30 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d3 (Thu Dec 30 16:17:50 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d4 (Thu Dec 30 16:18:15 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d5 (Thu Dec 30 16:18:05 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d6 (Thu Dec 30 18:18:30 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d7 (Thu Dec 30 18:17:50 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d8 (Thu Dec 30 18:18:15 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d9 (Thu Dec 30 18:18:05 2021): true

Examples

date_time.cpp, date_time_add_hours.cpp, date_time_add_milliseconds.cpp, date_time_add_minutes.cpp, date_time_add_months.cpp, date_time_add_seconds.cpp, date_time_add_years.cpp, date_time_date.cpp, date_time_day_of_week.cpp, date_time_day_of_year.cpp, date_time_max_value.cpp, date_time_min_value.cpp, date_time_specify_kind.cpp, date_time_sprintf.cpp, date_time_subtract.cpp, date_time_ticks.cpp, date_time_ticks2.cpp, date_time_to_string_format.cpp, date_time_today.cpp, format_date_time.cpp, graph_control.cpp, and time_span.cpp.

Public Fields
static const date_time	max_value
	Represents the largest possible value of xtd::date_time. This field is read-only.
static const date_time	min_value
	Represents the smallest possible value of xtd::date_time. This field is read-only.

Public Constructors
	date_time ()=default
	Initializes a new instance of the xtd::date_time structure.
	date_time (int64 ticks)
	Initializes a new instance of the xtd::date_time structure to a specified number of ticks.
	date_time (xtd::ticks ticks)
	Initializes a new instance of the xtd::date_time structure to a specified number of ticks.
	date_time (int64 ticks, xtd::date_time_kind kind)
	Initializes a new instance of the xtd::date_time structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.
	date_time (xtd::ticks ticks, xtd::date_time_kind kind)
	Initializes a new instance of the xtd::date_time structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.
	date_time (uint32 year, uint32 month, uint32 day)
	Initializes a new instance of the xtd::date_time structure to the specified year, month, and day.
	date_time (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second)
	Initializes a new instance of the xttd::date_time structure to the specified year, month, day, hour, minute, and second.
	date_time (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second, date_time_kind kind)
	Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, and Coordinated Universal Time (UTC) or local time.
	date_time (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second, uint32 millisecond)
	Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, and millisecond.
	date_time (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second, uint32 millisecond, date_time_kind kind)
	Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, millisecond, and Coordinated Universal Time (UTC) or local time.

Public Properties
date_time	date () const noexcept
	Gets the date component of this instance.
uint32	day () const noexcept
	Gets the day of the month represented by this instance.
xtd::day_of_week	day_of_week () const noexcept
	Gets the day of the week represented by this instance.
uint32	day_of_year () const noexcept
	Gets the day of the year represented by this instance.
uint32	hour () const noexcept
	Gets the hour component of the date represented by this instance.
date_time_kind	kind () const noexcept
	Gets a value that indicates whether the time represented by this instance is based on local time, Coordinated Universal Time (UTC), or neither.
uint32	millisecond () const noexcept
	Gets the milliseconds component of the date represented by this instance.
uint32	minute () const noexcept
	Gets the minute component of the date represented by this instance.
uint32	month () const noexcept
	Gets the month component of the date represented by this instance.
uint32	second () const noexcept
	Gets the seconds component of the date represented by this instance.
int64	ticks () const noexcept
	Gets the number of ticks that represent the date and time of this instance.
xtd::ticks	ticks_duration () const noexcept
	Gets the number of ticks that represent the date and time of this instance.
xtd::time_span	time_of_day () const noexcept
	Gets the time of day for this instance.
uint32	year () const noexcept
	Gets the year component of the date represented by this instance.

Public Methods
date_time	add (const xtd::time_span &value) const
	Returns a new xtd::date_time that adds the value of the specified xtd::time_span to the value of this instance.
date_time	add_days (double value) const
	Returns a new xtd::date_time that adds the specified number of days to the value of this instance.
date_time	add_hours (double value) const
	Returns a new xtd::date_time that adds the specified number of hours to the value of this instance.
date_time	add_milliseconds (double value) const
	Returns a new xtd::date_time that adds the specified number of milliseconds to the value of this instance.
date_time	add_minutes (double value) const
	Returns a new xtd::date_time that adds the specified number of minutes to the value of this instance.
date_time	add_months (int32 months) const
	Returns a new xtd::date_time that adds the specified number of months to the value of this instance.
date_time	add_seconds (double value) const
	Returns a new xtd::date_time that adds the specified number of seconds to the value of this instance.
date_time	add_ticks (int64 value) const
	Returns a new xtd::date_time that adds the specified number of ticks to the value of this instance.
date_time	add_years (int32 value) const
	Returns a new xtd::date_time that adds the specified number of years to the value of this instance.
int32	compare_to (const date_time &value) const noexcept override
	Compares the current instance with another object of the same type.
bool	equals (const date_time &) const noexcept override
	Indicates whether the current object is equal to another object of the same type.
std::vector< ustring >	get_date_time_formats () const noexcept
	Converts the value of this instance to all the string representations supported by the standard date and time format specifiers.
bool	is_daylight_saving_time () const noexcept
	Indicates whether this instance of xtd::date_time is within the daylight saving time range for the current time zone.
xtd::time_span	subtract (const date_time &value) const
	Returns a new xtd::time_span that subtracts the specified date and time from the value of this instance.
date_time	subtract (const xtd::time_span &value) const
	Returns a new xtd::date_time that subtracts the specified duration from the value of this instance.
int64	to_binary () const
	Serializes the current xtd::date_time object to a 64-bit binary value that subsequently can be used to recreate the xtd::date_time object.
int64	to_file_time () const
	Converts the value of the current xtd::date_time object to a Windows file time.
int64	to_file_time_utc () const
	Converts the value of the current xtd::date_time object to a Windows file time.
date_time	to_local_time () const
	Converts the value of the current xtd::date_time object to local time.
const xtd::ustring	to_long_date_string () const
	Converts the value of the current xtd::date_time object to its equivalent long date string representation.
const xtd::ustring	to_long_time_string () const
	Converts the value of the current xtd::date_time object to its equivalent long time string representation.
const xtd::ustring	to_short_date_string () const
	Converts the value of the current xtd::date_time object to its equivalent short date string representation.
const xtd::ustring	to_short_time_string () const
	Converts the value of the current xtd::date_time object to its equivalent short time string representation.
xtd::ustring	to_string () const noexcept override
	Converts the value of the current xtd::date_time object to its equivalent string representation using the formatting conventions of the current culture.
xtd::ustring	to_string (const ustring &format) const
	Converts the value of the current xtd::date_time object to its equivalent string representation using the specified format and the formatting conventions of the current culture.
std::time_t	to_time_t () const
	Converts the value of the current xtd::date_time object to std::time_t.
std::tm	to_tm () const
	Converts the value of the current xtd::date_time object to std::tm.
date_time	to_universal_time () const
	Converts the value of the current xtd::date_time object to Coordinated Universal Time (UTC).

Public Static Methods
static date_time	now () noexcept
	Gets a xtd::date_time object that is set to the current date and time on this computer, expressed as the local time.
static date_time	today () noexcept
	Gets the current date.
static date_time	utc_now () noexcept
	Gets a xtd::date_time object that is set to the current date and time on this computer, expressed as the Coordinated Universal Time (UTC).
static int32	days_in_month (uint32 year, month_of_year month)
	Returns the number of days in the specified month and year.
static int32	days_in_month (uint32 year, uint32 month)
	Returns the number of days in the specified month and year.
static date_time	from_binary (int64 date_data)
	Deserializes a 64-bit binary value and recreates an original serialized xtd::date_time object.
static date_time	from_file_time (int64 file_time)
	Converts the specified Windows file time to an equivalent local time.
static date_time	from_file_time_utc (int64 file_time)
	Converts the specified Windows file time to an equivalent UTC time.
static date_time	from_duration (const time_span &value)
	Converts the specified xtd::time_span to an equivalent unspecified time.
static date_time	from_duration (const time_span &value, date_time_kind kind)
	Converts the specified xtd::time_span to an equivalent to Coordinated Universal Time (UTC) or local time..
static date_time	from_time_t (std::time_t value)
	Converts the specified std::time_t to an equivalent unspecified time.
static date_time	from_time_t (std::time_t value, date_time_kind kind)
	Converts the specified std::time_t to an equivalent to Coordinated Universal Time (UTC) or local time.
static date_time	from_tm (const std::tm &value)
	Converts the specified std::tm to an equivalent unspecified time.
static date_time	from_tm (const std::tm &value, date_time_kind kind)
	Converts the specified std::tm to an equivalent to Coordinated Universal Time (UTC) or local time.
static bool	is_leap_year (uint32 year)
	Returns an indication whether the specified year is a leap year.
static date_time	parse (const xtd::ustring &s)
	Converts the string representation of a date and time to its xtd::date_time equivalent by using the conventions of the current culture.
static date_time	specify_kind (const date_time &value, date_time_kind kind)
	Creates a new xtd::date_time object that has the same number of ticks as the specified xtd::date_time, but is designated as either local time, Coordinated Universal Time (UTC), or neither, as indicated by the specified xtd::date_time_kind value.
static xtd::ustring	sprintf (const ustring &format, const date_time &value)
	Returns a xtd::ustring that represents the current xtd::date_time.
static bool	try_parse (const ustring &s, date_time &result) noexcept
	Converts the specified string representation of a date and time to its xtd::date_time equivalent and returns a value that indicates whether the conversion succeeded.

Additional Inherited Members
Public Member Functions inherited from xtd::icomparable< date_time >
Public Member Functions inherited from xtd::iequatable< date_time >
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

date_time() [1/10]

xtd::date_time::date_time ( )

default

Initializes a new instance of the xtd::date_time structure.

Remarks

xtd::date_time is initialized by default with xtd::date_time::min_value.

date_time() [2/10]

xtd::date_time::date_time ( int64  ticks )

explicit

Initializes a new instance of the xtd::date_time structure to a specified number of ticks.

Parameters

ticks

A date and time expressed in the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00.000 in the Gregorian calendar.

Exceptions

xtd::argument_out_of_range_exception

ticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Remarks

The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.

Examples

The following example demonstrates one of the xtd::date_time constructors.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Instead of using the implicit, default "G" date and time format string, we
    // use a custom format string that aligns the results and inserts leading zeroes.
    auto format = "{0}) The {1} date and time is {2:k}/{2:i}/{2:L} {2:t}";
    
    // Create a DateTime for the maximum date and time using ticks.
    auto dt1 = date_time {date_time::max_value.ticks()};
    
    // Create a DateTime for the minimum date and time using ticks.
    auto dt2 = date_time {date_time::min_value.ticks()};
    
    // Create a custom DateTime for 1/5/1971 at 21:10:30 using ticks
    auto ticks = date_time {1971, 1, 5, 21, 10, 30}.ticks();
    auto dt3 = date_time {ticks};
    
    console::write_line(format, 1, "maximum", dt1);
    console::write_line(format, 2, "minimum", dt2);
    console::write_line(format, 3, "custom ", dt3);
    console::write_line("\nThe custom date and time is created from {0} ticks.", ticks);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 1) The maximum date and time is 12/31/9999 23:59:59
// 2) The minimum date and time is 01/01/0001 00:00:00
// 3) The custom  date and time is 01/05/1971 21:10:30
//
// The custom date and time is created from 621675546300000000 ticks.

date_time() [3/10]

xtd::date_time::date_time ( xtd::ticks  ticks )

explicit

Initializes a new instance of the xtd::date_time structure to a specified number of ticks.

Parameters

ticks

A date and time expressed in the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00.000 in the Gregorian calendar.

Exceptions

xtd::argument_out_of_range_exception

ticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Remarks

The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.

Examples

The following example demonstrates one of the xtd::date_time constructors.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Instead of using the implicit, default "G" date and time format string, we
    // use a custom format string that aligns the results and inserts leading zeroes.
    auto format = "{0}) The {1} date and time is {2:k}/{2:i}/{2:L} {2:t}";
    
    // Create a DateTime for the maximum date and time using ticks.
    auto dt1 = date_time {date_time::max_value.ticks()};
    
    // Create a DateTime for the minimum date and time using ticks.
    auto dt2 = date_time {date_time::min_value.ticks()};
    
    // Create a custom DateTime for 1/5/1971 at 21:10:30 using ticks
    auto ticks = date_time {1971, 1, 5, 21, 10, 30}.ticks();
    auto dt3 = date_time {ticks};
    
    console::write_line(format, 1, "maximum", dt1);
    console::write_line(format, 2, "minimum", dt2);
    console::write_line(format, 3, "custom ", dt3);
    console::write_line("\nThe custom date and time is created from {0} ticks.", ticks);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 1) The maximum date and time is 12/31/9999 23:59:59
// 2) The minimum date and time is 01/01/0001 00:00:00
// 3) The custom  date and time is 01/05/1971 21:10:30
//
// The custom date and time is created from 621675546300000000 ticks.

date_time() [4/10]

xtd::date_time::date_time	(	int64	ticks,
		xtd::date_time_kind	kind
	)

Initializes a new instance of the xtd::date_time structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.

Parameters

ticks	A date and time expressed in the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00.000 in the Gregorian calendar.
kind	One of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.

Exceptions

xtd::argument_out_of_range_exception

ticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

date_time() [5/10]

xtd::date_time::date_time	(	xtd::ticks	ticks,
		xtd::date_time_kind	kind
	)

Initializes a new instance of the xtd::date_time structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.

Parameters

ticks	A date and time expressed in the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00.000 in the Gregorian calendar.
kind	One of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.

Exceptions

xtd::argument_out_of_range_exception

ticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

date_time() [6/10]

xtd::date_time::date_time	(	uint32	year,
		uint32	month,
		uint32	day
	)

Initializes a new instance of the xtd::date_time structure to the specified year, month, and day.

Parameters

year	The year (1 through 9999).
month	The month (1 through 12).
day	The day (1 through the number of days in month).

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999. -or- month is less than 1 or greater than 12. -or- day is less than 1 or greater than the number of days in month.

Examples

The following example uses the date_time(uint32, uint32, uint32) constructor to instantiate a xtd::date_time value. The example also illustrates that this overload creates a xtd::date_time value whose time component equals midnight (or 0:00).

date_time date1(2010, 8, 18);
console::write_line(date1.to_string());
// The example displays the following output:
//      8/18/2010 12:00:00 AM

Remarks

This constructor interprets year, month, and day as a year, month, and day in the Gregorian calendar.

date_time() [7/10]

xtd::date_time::date_time	(	uint32	year,
		uint32	month,
		uint32	day,
		uint32	hour,
		uint32	minute,
		uint32	second
	)

Initializes a new instance of the xttd::date_time structure to the specified year, month, day, hour, minute, and second.

Parameters

year	The year (1 through 9999).
month	The month (1 through 12).
day	The day (1 through the number of days in month).
hour	The hours (0 through 23).
minute	The minutes (0 through 59).
second	The seconds (0 through 59).

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999. -or- month is less than 1 or greater than 12. -or- day is less than 1 or greater than the number of days in month. -or- hour is less than 0 or greater than 23. -or- minute is less than 0 or greater than 59. -or- second is less than 0 or greater than 59.

Remarks

The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.

This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

date_time() [8/10]

xtd::date_time::date_time	(	uint32	year,
		uint32	month,
		uint32	day,
		uint32	hour,
		uint32	minute,
		uint32	second,
		date_time_kind	kind
	)

Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, and Coordinated Universal Time (UTC) or local time.

Parameters

year	The year (1 through 9999).
month	The month (1 through 12).
day	The day (1 through the number of days in month).
hour	The hours (0 through 23).
minute	The minutes (0 through 59).
second	The seconds (0 through 59).
kind	One of the enumeration values that indicates whether year, month, day, hour, minute and second specify a local time, Coordinated Universal Time (UTC), or neither.

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999. -or- month is less than 1 or greater than 12. -or- day is less than 1 or greater than the number of days in month. -or- hour is less than 0 or greater than 23. -or- minute is less than 0 or greater than 59 -or- second is less than 0 or greater than 59.

Examples

The following example uses the date_time(uint32, uint32, uint32t, uint32t, uint32, uint32, xtd::date_time_kind) constructor to instantiate a xtd::date_time value.

date_time date1(2010, 8, 18, 16, 32, 0, date_time_kind::local);
console::write_line("{0} {1}", date1, date1.kind());
// The example displays the following output, in this case for en-us culture:
//      8/18/2010 4:32:00 PM Localv

Remarks

The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.

This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

date_time() [9/10]

xtd::date_time::date_time	(	uint32	year,
		uint32	month,
		uint32	day,
		uint32	hour,
		uint32	minute,
		uint32	second,
		uint32	millisecond
	)

Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, and millisecond.

Parameters

year	The year (1 through 9999).
month	The month (1 through 12).
day	The day (1 through the number of days in month).
hour	The hours (0 through 23).
minute	The minutes (0 through 59).
second	The seconds (0 through 59).
millisecond	The milliseconds (0 through 999).

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999. -or- month is less than 1 or greater than 12. -or- day is less than 1 or greater than the number of days in month. -or- hour is less than 0 or greater than 23. -or- minute is less than 0 or greater than 59 -or- second is less than 0 or greater than 59 -or- millisecond is less than 0 or greater than 999.

Remarks

This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

date_time() [10/10]

xtd::date_time::date_time	(	uint32	year,
		uint32	month,
		uint32	day,
		uint32	hour,
		uint32	minute,
		uint32	second,
		uint32	millisecond,
		date_time_kind	kind
	)

Initializes a new instance of the xtd::date_time structure to the specified year, month, day, hour, minute, second, millisecond, and Coordinated Universal Time (UTC) or local time.

Parameters

year	The year (1 through 9999).
month	The month (1 through 12).
day	The day (1 through the number of days in month).
hour	The hours (0 through 23).
minute	The minutes (0 through 59).
second	The seconds (0 through 59).
millisecond	The milliseconds (0 through 999).
kind	One of the enumeration values that indicates whether year, month, day, hour, minute and second specify a local time, Coordinated Universal Time (UTC), or neither.

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999. -or- month is less than 1 or greater than 12. -or- day is less than 1 or greater than the number of days in month. -or- hour is less than 0 or greater than 23. -or- minute is less than 0 or greater than 59 -or- second is less than 0 or greater than 59 -or- millisecond is less than 0 or greater than 999.

Remarks

This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

Member Function Documentation

add()

date_time xtd::date_time::add

(

const xtd::time_span &

value

)

const

Returns a new xtd::date_time that adds the value of the specified xtd::time_span to the value of this instance.

Parameters

value

A positive or negative time interval.

Returns

An object whose value is the sum of the date and time represented by this instance and the time interval represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example demonstrates the xtd::date_time::add method. It calculates the day of the week that is 36 days (864 hours) from this moment.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <chrono>
 
class program {
public:
  static auto main() {
    // Calculate what day of the week is 36 days from this instant.
    auto today = xtd::date_time::now();
    auto duration = std::chrono::days {36};
    auto answer = today.add(duration);
    xtd::console::write_line("{0}", today);
    xtd::console::write_line("{0}", answer);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Wed Jan 12 14:06:34 2022
// Thu Feb 17 14:06:34 2022

Remarks

You can use the xtd::date_time::add method to add more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. This method's behavior is identical to that of the addition operator. The xtd::date_time::addxtd::date_time structure also supports specialized addition methods (such as xtd::date_time::add_days, xtd::date_time::add_hours, and xtd::date_time::add_minutes) for each time interval.

The xtd::date_time::add method takes into account leap years and the number of days in a month when performing date arithmetic.

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation. The xtd::date_time::kind property of the new xtd::date_time instance is the same as that of the current instance.

add_days()

date_time xtd::date_time::add_days

(

double

value

)

const

Returns a new xtd::date_time that adds the specified number of days to the value of this instance.

Parameters

value

A number of whole and fractional days. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of days represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example uses the xtd::date_time::add_days method to determine the day of the week 36 days after the current date.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
class program {
public:
  static auto main() {
    // Calculate what day of the week is 36 days from this instant.
    auto today = xtd::date_time::now();
    auto answer = today.add_days(36);
    xtd::console::write_line("{0}", today);
    xtd::console::write_line("{0}", answer);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Wed Jan 12 14:06:34 2022
// Thu Feb 17 14:06:34 2022

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

The fractional part of value is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds, and 0 ticks.

The xtd::date_time::add_days method takes into account leap years and the number of days in a month when performing date arithmetic.

add_hours()

date_time xtd::date_time::add_hours

(

double

value

)

const

Returns a new xtd::date_time that adds the specified number of hours to the value of this instance.

Parameters

value

A number of whole and fractional hours. The value parameter can be negative or positive.A number of whole and fractional hours. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of hours represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example uses the xtd::date_time::add_hours method to add a number of whole and fractional values to a date and time. It also illustrates the loss of precision caused by passing the method a value that includes a fractional component.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <vector>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto hours = vector {.08333, .16667, .25, .33333, .5, .66667, 1.0, 2.0, 29.0, 30.0, 31.0, 90.0, 365.0};
    auto date_value = date_time {2009, 3, 1, 12, 0, 0};
    
    for (auto hour : hours)
      console::write_line("{0:u} + {1} hour(s) = {2:u}", date_value, hour, date_value.add_hours(hour));
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 2009-03-01 12:00:00 + 0.08333 hour(s) = 2009-03-01 12:04:59
// 2009-03-01 12:00:00 + 0.16667 hour(s) = 2009-03-01 12:10:00
// 2009-03-01 12:00:00 + 0.25 hour(s) = 2009-03-01 12:15:00
// 2009-03-01 12:00:00 + 0.33333 hour(s) = 2009-03-01 12:19:59
// 2009-03-01 12:00:00 + 0.5 hour(s) = 2009-03-01 12:30:00
// 2009-03-01 12:00:00 + 0.66667 hour(s) = 2009-03-01 12:40:00
// 2009-03-01 12:00:00 + 1 hour(s) = 2009-03-01 13:00:00
// 2009-03-01 12:00:00 + 2 hour(s) = 2009-03-01 14:00:00
// 2009-03-01 12:00:00 + 29 hour(s) = 2009-03-02 17:00:00
// 2009-03-01 12:00:00 + 30 hour(s) = 2009-03-02 18:00:00
// 2009-03-01 12:00:00 + 31 hour(s) = 2009-03-02 19:00:00
// 2009-03-01 12:00:00 + 90 hour(s) = 2009-03-05 06:00:00
// 2009-03-01 12:00:00 + 365 hour(s) = 2009-03-16 17:00:00

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation. The xtd::date_time::kind property of the returned xtd::date_time object is the same as that of value.

The fractional part of value is the fractional part of an hour. For example, 4.5 is equivalent to 4 hours, 30 minutes, 0 seconds, 0 milliseconds, and 0 ticks.

Converting time intervals of less than an hour to a fraction can involve a loss of precision if the result is a non-terminating repeating decimal. (For example, one minute is 0.016667 of an hour.) If this is problematic, you can use the xtd::date_time::add method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of an hour.

add_milliseconds()

date_time xtd::date_time::add_milliseconds

(

double

value

)

const

Returns a new xtd::date_time that adds the specified number of milliseconds to the value of this instance.

Parameters

value

A number of whole and fractional milliseconds. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of milliseconds represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example uses the xtd::date_timeadd_milliseconds method to add one millisecond and 1.5 milliseconds to a xtd::date_time value. It then displays each new value and displays the difference between it and the original value. The difference is displayed both as a time span and as a number of ticks. The example makes it clear that one millisecond equals 10,000 ticks. It also shows that fractional milliseconds are rounded before performing the addition; the xtd::date_time value that results from adding 1.5 milliseconds to the original date is 2 milliseconds greater than the original date.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <xtd/ustring>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto date_format = "{0:d}/{0:t}.{0:c}"_s;
    auto date1 = date_time {2010, 9, 8, 16, 0, 0};
    console::write_line("Original date: {0} ({1:N0} ticks)\n", ustring::format(date_format, date1), date1.ticks());
    
    auto date2 = date1.add_milliseconds(1);
    console::write_line("Second date:   {0} ({1:N0} ticks)", ustring::format(date_format, date2), date2.ticks());
    console::write_line("Difference between dates: {0} ({1:N0} ticks)\n", date2 - date1, date2.ticks() - date1.ticks());
    
    auto date3 = date1.add_milliseconds(1.5);
    console::write_line("Third date:    {0} ({1:N0} ticks)", ustring::format(date_format, date3), date3.ticks());
    console::write_line("Difference between dates: {0} ({1:N0} ticks)", date3 - date1, date3.ticks() - date1.ticks());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Original date: 09/08/2010/16:00:00.0000000 (634195584000000000 ticks)
//
// Second date:   09/08/2010/16:00:00.0000000 (634195584000010000 ticks)
// Difference between dates: Mon Jan  1 00:00:00 0001 (10000 ticks)
//
// Third date:    09/08/2010/16:00:00.0005000 (634195584000015000 ticks)
// Difference between dates: Mon Jan  1 00:00:00 0001 (15000 ticks)

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

The fractional part of value is the fractional part of a millisecond. For example, 4.5 is equivalent to 4 milliseconds and 5000 ticks, where one millisecond = 10000 ticks.

The value parameter is rounded to the nearest integer.

add_minutes()

date_time xtd::date_time::add_minutes

(

double

value

)

const

Returns a new xtd::date_time that adds the specified number of minutes to the value of this instance.

Parameters

value

A number of whole and fractional minutes. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of minutes represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example uses the xtd::date_time::add_minutes method to add a number of whole and fractional values to a date and time.

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

The fractional part of value is the fractional part of a minute. For example, 4.5 is equivalent to 4 minutes, 30 seconds, 0 milliseconds, and 0 ticks.

add_months()

date_time xtd::date_time::add_months

(

int32

months

)

const

Returns a new xtd::date_time that adds the specified number of months to the value of this instance.

Parameters

months

A number of months. The months parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and months

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value. -or- months is less than -120,000 or greater than 120,000.

Examples

The following example adds between zero and fifteen months to the last day of December, 2015. In this case, the xtd::date_time::add_months method returns the date of the last day of each month, and successfully handles leap years.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto dat = date_time {2015, 12, 31};
    for (auto ctr = 0; ctr <= 15; ctr++)
      console::write_line(dat.add_months(ctr).to_string("d"));
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 12/31/2015
// 01/31/2016
// 02/29/2016
// 03/31/2016
// 04/30/2016
// 05/31/2016
// 06/30/2016
// 07/31/2016
// 08/31/2016
// 09/30/2016
// 10/31/2016
// 11/30/2016
// 12/31/2016
// 01/31/2017
// 02/28/2017
// 03/31/2017

Remarks

This method does not change the value of this xtd::date_time object. Instead, it returns a new xtd::date_time object whose value is the result of this operation.

The xtd::date_time::add_months method calculates the resulting month and year, taking into account leap years and the number of days in a month, then adjusts the day part of the resulting xtd::date_time object. If the resulting day is not a valid day in the resulting month, the last valid day of the resulting month is used. For example, March 31st + 1 month = April 30th, and March 31st - 1 month = February 28 for a non-leap year and February 29 for a leap year.

add_seconds()

date_time xtd::date_time::add_seconds

(

double

value

)

const

Returns a new xtd::date_time that adds the specified number of seconds to the value of this instance.

Parameters

value

A number of whole and fractional seconds. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of seconds represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Examples

The following example uses the xtd::date_time::add_seconds method to add 30 seconds and the number of seconds in one day to a xtd::date_time value. It then displays each new value and displays the difference between it and the original value. The difference is displayed both as a time span and as a number of ticks.

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

The fractional part of value is the fractional part of a second. For example, 4.5 is equivalent to 4 seconds, 500 milliseconds, and 0 ticks.

add_ticks()

date_time xtd::date_time::add_ticks

(

int64

value

)

const

Returns a new xtd::date_time that adds the specified number of ticks to the value of this instance.

Parameters

value

A number of 100-nanosecond ticks. The value parameter can be positive or negative.

Returns

An object whose value is the sum of the date and time represented by this instance and the time represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Remarks

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

add_years()

date_time xtd::date_time::add_years

(

int32

value

)

const

Returns a new xtd::date_time that adds the specified number of years to the value of this instance.

Parameters

value

A number of years. The value parameter can be negative or positive.

Returns

An object whose value is the sum of the date and time represented by this instance and the number of years represented by value.

Exceptions

xtd::argument_out_of_range_exception

The resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Remarks

This method does not change the value of this xtd::date_time object. Instead, it returns a new xtd::date_time object whose value is the result of this operation.

The xtd::date_time::add_years method calculates the resulting year taking into account leap years. The month and time-of-day part of the resulting xtd::date_time object remains the same as this instance.

If the current instance represents the leap day in a leap year, the return value depends on the target date:

• If value + xtd::date_time::year() is also a leap year, the return value represents the leap day in that year. For example, if four years is added to February 29, 2012, the date returned is February 29, 2016.
• If value + xtd::date_time::year() is not a leap year, the return value represents the day before the leap day in that year. For example, if one year is added to February 29, 2012, the date returned is February 28, 2013.

Examples

The following example illustrates using the xtd::date_time::add_years method with a xtd::date_time value that represents a leap year day. It displays the date for the fifteen years prior to and the fifteen years that follow February 29, 2000.

Examples

date_time_day_of_year.cpp.

compare_to()

int32 xtd::date_time::compare_to ( const date_time &  obj ) const

overridevirtualnoexcept

Compares the current instance with another object of the same type.

Parameters

obj	An object to compare with this instance.

Returns

A 32-bit signed integer that indicates the relative order of the objects being compared. The return value has these meanings:

Value	Condition
Less than zero	This instance is less than obj.
Zero	This instance is equal to obj.
Greater than zero	This instance is greater than obj.

Implements xtd::icomparable< date_time >.

date()

date_time xtd::date_time::date ( ) const

noexcept

Gets the date component of this instance.

Returns

A new object with the same date as this instance, and the time value set to 12:00:00 midnight (00:00:00).

Examples

The following example uses the xtd::date_time::date property to extract the date component of a xtd::date_time value with its time component set to zero (or 0:00:00, or midnight). It also illustrates that, depending on the format string used when displaying the xtd::date_time value, the time component can continue to appear in formatted output.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto date1 = date_time {2008, 6, 1, 7, 47, 0};
    console::write_line(date1.to_string());
    
    // Get date-only portion of date, without its time.
    auto date_only = date1.date();
    // Display date using short date string.
    console::write_line(date_only.to_string("d"));
    // Display date using 24-hour clock.
    console::write_line(date_only.to_string("g"));
    console::write_line(date_only.to_string("u"));
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
// Sun Jun  1 07:47:00 2008
// 06/01/2008
// Sun Jun  1 00:00:00 2008
// 2008-06-01 00:00:00

Remarks

The value of the xtd::date_time::kind property of the returned xtd::date_time value is the same as that of the current instance.

Because the xtd::date_time type represents both dates and times in a single type, it is important to avoid misinterpreting a date returned by the xtd::date property as a date and time.

day()

uint32 xtd::date_time::day ( ) const

noexcept

Gets the day of the month represented by this instance.

Returns

The day component, expressed as a value between 1 and 31.

Examples

The following example demonstrates the xtd::date_time::day property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = momentour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

Remarks

The xtd::date_time::day property always returns the day of the month in the Gregorian calendar.

day_of_week()

xtd::day_of_week xtd::date_time::day_of_week ( ) const

noexcept

Gets the day of the week represented by this instance.

Returns

An enumerated constant that indicates the day of the week of this xtd::date_time value.

Examples

The following example demonstrates the xtd::date_time::day_of_week property and the xtd::day_of_week enumeration.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Create a DateTime for the first of May, 2003.
    auto dt = date_time {2003, 5, 1};
    console::write_line("Is Thursday the day of the week for {0:d}?: {1}", dt, dt.day_of_week() == day_of_week::thursday);
    console::write_line("The day of the week for {0:d} is {1}.", dt, dt.day_of_week());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Is Thursday the day of the week for 05/01/2003?: true
// The day of the week for 05/01/2003 is thursday.

Remarks

The value of the constants in the xtd::day_of_week enumeration ranges from xtd::day_of_week::sunday to xtd::day_of_week::saturday. If cast to an integer, its value ranges from zero (which indicates xtd::day_of_week::sunday) to six (which indicates xtd::day_of_week::saturday).

The xtd::date_time::day_of_week property returns an enumerated constant; it does not reflect a system's regional and language settings. To retrieve a string representing a localized weekday name for a particular date, call one of the overloads of the xtd::date_time::to_string method that includes a format parameter and pass it either the "h" or "H" format strings.

day_of_year()

uint32 xtd::date_time::day_of_year ( ) const

noexcept

Gets the day of the year represented by this instance.

Returns

The day of the year, expressed as a value between 1 and 366.

Examples

The following example displays the day of the year of December 31 for the years 2010-2020 in the Gregorian calendar. Note that the example shows that December 31 is the 366th day of the year in leap years.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto dec31 = date_time {2010, 12, 31};
    for (auto ctr = 0u; ctr <= 10u; ctr++) {
      auto date_to_display = dec31.add_years(ctr);
      console::write_line("{0:d}: day {1} of {2} {3}", date_to_display, date_to_display.day_of_year(), date_to_display.year(), date_time::is_leap_year(date_to_display.year()) ? "(Leap Year)" : "");
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 12/31/2010: day 365 of 2010
// 12/31/2011: day 365 of 2011
// 12/31/2012: day 366 of 2012 (Leap Year)
// 12/31/2013: day 365 of 2013
// 12/31/2014: day 365 of 2014
// 12/31/2015: day 365 of 2015
// 12/31/2016: day 366 of 2016 (Leap Year)
// 12/31/2017: day 365 of 2017
// 12/31/2018: day 365 of 2018
// 12/31/2019: day 365 of 2019
// 12/31/2020: day 366 of 2020 (Leap Year)

Remarks

The xtd::date_time::day_of_year property takes leap years into account when it calculates the day of the year. The property value always reflects the day of the year in the Gregorian calendar, regardless of the current culture's current calendar.

days_in_month() [1/2]

static int32 xtd::date_time::days_in_month ( uint32  year, month_of_year  month  )

static

Returns the number of days in the specified month and year.

Parameters

year	The year.
month	The month (one of xtd::month_of_year values).

Returns

The number of days in month for the specified year.
For example, if month equals 2 for February, the return value is 28 or 29 depending upon whether year is a leap year.

Exceptions

xtd::argument_out_of_range_exception

month is less than 1 or greater than 12. -or- year is less than 1 or greater than 9999.

Examples

The following example demonstrates how to use the xtd::date_time::days_in_month method to determine the number of days in July 2001, February 1998 (a non-leap year), and February 1996 (a leap year).

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
class program {
public:
  static auto main() {
    auto days_in_july = xtd::date_time::days_in_month(2001, xtd::month_of_year::july);
    xtd::console::write_line(days_in_july);
    
    // days_in_feb gets 28 because the year 1998 was not a leap year.
    auto days_in_feb = xtd::date_time::days_in_month(1998, xtd::month_of_year::february);
    xtd::console::write_line(days_in_feb);
    
    // days_in_feb_leap gets 29 because the year 1996 was a leap year.
    auto days_in_feb_leap = xtd::date_time::days_in_month(1996, xtd::month_of_year::february);
    xtd::console::write_line(days_in_feb_leap);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 31
// 28
// 29

Examples

The following example displays the number of days in each month of a year specified in an integer array.

#include <xtd/as>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <array>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto years = array<unsigned int, 2> {2012, 2014};
    console::write_line("Days in the Month for the Gregorian calendar\n");
    console::write_line("{0,-10}{1,-15}{2,4}\n", "Year", "Month", "Days");
    
    for (auto year : years) {
      for (auto ctr = 1u; ctr <= 12u; ctr++)
        console::write_line("{0,-10}{1,-15}{2,4}", year, as<month_of_year>(ctr), date_time::days_in_month(year, ctr));
      console::write_line();
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
//  Days in the Month for the en-US culture using the Gregorian calendar
//
//  Year      Month          Days
//
//  2012      january          31
//  2012      february         29
//  2012      march            31
//  2012      april            30
//  2012      may              31
//  2012      june             30
//  2012      july             31
//  2012      august           31
//  2012      september        30
//  2012      october          31
//  2012      november         30
//  2012      december         31
//
//  2014      january          31
//  2014      february         28
//  2014      march            31
//  2014      april            30
//  2014      may              31
//  2014      june             30
//  2014      july             31
//  2014      august           31
//  2014      september        30
//  2014      october          31
//  2014      november         30
//  2014      december         31

Remarks

The xtd::date_time::days_in_month method always interprets month and year as the month and year of the Gregorian calendar.

Examples

date_time_days_in_month.cpp.

days_in_month() [2/2]

static int32 xtd::date_time::days_in_month ( uint32  year, uint32  month  )

static

Returns the number of days in the specified month and year.

Parameters

year	The year.
month	The month (a number ranging from 1 to 12).

Returns

The number of days in month for the specified year.
For example, if month equals 2 for February, the return value is 28 or 29 depending upon whether year is a leap year.

Exceptions

xtd::argument_out_of_range_exception

month is less than 1 or greater than 12. -or- year is less than 1 or greater than 9999.

Examples

The following example demonstrates how to use the xtd::date_time::days_in_month method to determine the number of days in July 2001, February 1998 (a non-leap year), and February 1996 (a leap year).

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
class program {
public:
  static auto main() {
    auto days_in_july = xtd::date_time::days_in_month(2001, xtd::month_of_year::july);
    xtd::console::write_line(days_in_july);
    
    // days_in_feb gets 28 because the year 1998 was not a leap year.
    auto days_in_feb = xtd::date_time::days_in_month(1998, xtd::month_of_year::february);
    xtd::console::write_line(days_in_feb);
    
    // days_in_feb_leap gets 29 because the year 1996 was a leap year.
    auto days_in_feb_leap = xtd::date_time::days_in_month(1996, xtd::month_of_year::february);
    xtd::console::write_line(days_in_feb_leap);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 31
// 28
// 29

Examples

The following example displays the number of days in each month of a year specified in an integer array.

#include <xtd/as>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <array>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto years = array<unsigned int, 2> {2012, 2014};
    console::write_line("Days in the Month for the Gregorian calendar\n");
    console::write_line("{0,-10}{1,-15}{2,4}\n", "Year", "Month", "Days");
    
    for (auto year : years) {
      for (auto ctr = 1u; ctr <= 12u; ctr++)
        console::write_line("{0,-10}{1,-15}{2,4}", year, as<month_of_year>(ctr), date_time::days_in_month(year, ctr));
      console::write_line();
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
//  Days in the Month for the en-US culture using the Gregorian calendar
//
//  Year      Month          Days
//
//  2012      january          31
//  2012      february         29
//  2012      march            31
//  2012      april            30
//  2012      may              31
//  2012      june             30
//  2012      july             31
//  2012      august           31
//  2012      september        30
//  2012      october          31
//  2012      november         30
//  2012      december         31
//
//  2014      january          31
//  2014      february         28
//  2014      march            31
//  2014      april            30
//  2014      may              31
//  2014      june             30
//  2014      july             31
//  2014      august           31
//  2014      september        30
//  2014      october          31
//  2014      november         30
//  2014      december         31

Remarks

The xtd::date_time::days_in_month method always interprets month and year as the month and year of the Gregorian calendar.

equals()

bool xtd::date_time::equals ( const date_time &  ) const

overridevirtualnoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters

obj	An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< date_time >.

from_binary()

static date_time xtd::date_time::from_binary ( int64  date_data )

static

Deserializes a 64-bit binary value and recreates an original serialized xtd::date_time object.

Parameters

date_data

A 64-bit signed integer that encodes the xtd::date_time::kind property in a 2-bit field and the xtd::date_time::ticks property in a 62-bit field.

Returns

An object that is equivalent to the xtd::date_time object that was serialized by the xtd::date_time::to_binary() method.

Exceptions

xtd::argument_exception

date_data is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

Remarks

Use the xtd::date_time::to_binary method to convert the value of the current xtd::date_time object to a binary value. Subsequently, use the binary value and the xtd::date_time::from_binary method to recreate the original xtd::date_time object.

Note

In some cases, the xtd::date_time value returned by the xtd::date_time::from_binary method is not identical to the original xtd::date_time value supplied to the xtd::date_time::to_binary method.

from_duration() [1/2]

static date_time xtd::date_time::from_duration ( const time_span &  value )

static

Converts the specified xtd::time_span to an equivalent unspecified time.

Parameters

value

A time interval from the start of the Clock's epoch.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the file_time parameter.

Exceptions

xtd::argument_out_of_range_exception

value is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

from_duration() [2/2]

static date_time xtd::date_time::from_duration ( const time_span &  value, date_time_kind  kind  )

static

Converts the specified xtd::time_span to an equivalent to Coordinated Universal Time (UTC) or local time..

Parameters

value	A time interval from the start of the Clock's epoch.
kind	One of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the file_time parameter.

Exceptions

xtd::argument_out_of_range_exception

value is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

from_file_time()

static date_time xtd::date_time::from_file_time ( int64  file_time )

static

Converts the specified Windows file time to an equivalent local time.

Parameters

file_time

A Windows file time expressed in ticks.

Returns

An object that represents the local time equivalent of the date and time represented by the file_time parameter.

Exceptions

xtd::argument_out_of_range_exception

file_time is less than 0 or represents a time greater than xtd::date_time:max_value.

Examples

The following example demonstrates the xtd::date_time::from_file_time method.

xtd::ticks file_age(int64 file_creation_time) {
  xtd::date_time now = xtd::date_time::now();
  try {
    xtd::date_time fcreation_fime = xtd::date_time::from_file_time(file_creation_time);
    xtd::ticks file_age = now.subtract(fcreation_time);
    return file_age;
  } catch (const xtd::argument_out_of_range_exception&) {
    // file_creation_time is not valid, so re-throw the exception.
    throw;
  }
}

Remarks

A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file.

The file_time parameter specifies a file time expressed in 100-nanosecond ticks.

The return value is a xtd::date_time whose xtd::date_time::kind property is xtd::date_time_kind::local.

from_file_time_utc()

static date_time xtd::date_time::from_file_time_utc ( int64  file_time )

static

Converts the specified Windows file time to an equivalent UTC time.

Parameters

file_time

A Windows file time expressed in ticks.

Returns

An object that represents the UTC time equivalent of the date and time represented by the file_time parameter.

Exceptions

xtd::argument_out_of_range_exception

file_time is less than 0 or represents a time greater than xtd::date_time:max_value.

Remarks

A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file.

The file_time parameter specifies a file time expressed in 100-nanosecond ticks.

The return value is a xtd::date_time whose xtd::date_time::kind property is xtd::date_time:utc.

from_time_t() [1/2]

static date_time xtd::date_time::from_time_t ( std::time_t  value )

static

Converts the specified std::time_t to an equivalent unspecified time.

Parameters

value

A time interval from the start of the Clock's epoch.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the value parameter.

Exceptions

xtd::argument_out_of_range_exception

value is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

Remarks

std::time_t is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

from_time_t() [2/2]

static date_time xtd::date_time::from_time_t ( std::time_t  value, date_time_kind  kind  )

static

Converts the specified std::time_t to an equivalent to Coordinated Universal Time (UTC) or local time.

Parameters

value	A time interval from the start of the Clock's epoch.
kind	One of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the value parameter.

Exceptions

xtd::argument_out_of_range_exception

value is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

Remarks

std::time_t is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

from_tm() [1/2]

static date_time xtd::date_time::from_tm ( const std::tm &  value )

static

Converts the specified std::tm to an equivalent unspecified time.

Parameters

value

A std::tm struct.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the value parameter.

Exceptions

xtd::argument_out_of_range_exception

value.ttm_year is less than 1 or greater than 9999. -or- tvalue.tm_mon is less than 1 or greater than 12. -or- value.tm_mday is less than 1 or greater than the number of days in month. -or- value.tm_hour is less than 0 or greater than 23. -or- value.tm_min is less than 0 or greater than 59 -or- vale.tm_sec is less than 0 or greater than 59.

Remarks

std::tm is a structure holding a calendar date and time broken down into its components. is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

from_tm() [2/2]

static date_time xtd::date_time::from_tm ( const std::tm &  value, date_time_kind  kind  )

static

Converts the specified std::tm to an equivalent to Coordinated Universal Time (UTC) or local time.

Parameters

value	A std::tm struct.
kind	One of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.

Returns

An object that represents the unspecified time equivalent of the date and time represented by the value parameter.

Exceptions

xtd::argument_out_of_range_exception

value.ttm_year is less than 1 or greater than 9999. -or- tvalue.tm_mon is less than 1 or greater than 12. -or- value.tm_mday is less than 1 or greater than the number of days in month. -or- value.tm_hour is less than 0 or greater than 23. -or- value.tm_min is less than 0 or greater than 59 -or- vale.tm_sec is less than 0 or greater than 59.

Remarks

std::tm is a structure holding a calendar date and time broken down into its components. is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

get_date_time_formats()

std::vector< ustring > xtd::date_time::get_date_time_formats ( ) const

noexcept

Converts the value of this instance to all the string representations supported by the standard date and time format specifiers.

Returns

A string array where each element is the representation of the value of this instance formatted with one of the standard date and time format specifiers.

hour()

uint32 xtd::date_time::hour ( ) const

noexcept

Gets the hour component of the date represented by this instance.

Returns

The hour component, expressed as a value between 0 and 23.

Examples

The following example demonstrates the xtd::date_time::hour property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

Remarks

The value of the xtd::date_time::hour property is always expressed using a 24-hour clock. To retrieve a string that represents the hour of a date and time using a 12-hour clock, call the xtd::date_time::to_string(ustring) method with the "x" format specifier. For example:

date_time date1(2008, 4, 1, 18, 53, 0);
console::write_line(date1.to_string("X"));                                   // Displays 6
console::write_line("{0}, {1}", date1.to_string("X"), date1.to_string("a")); // Displays 6 PM

is_daylight_saving_time()

bool xtd::date_time::is_daylight_saving_time ( ) const

noexcept

Indicates whether this instance of xtd::date_time is within the daylight saving time range for the current time zone.

Returns

true if the value of the xtd::date_time::kind property is xtd::date_time_kind::local or xtd::date_time_kind::unspecified and the value of this instance ofxtd::date_time is within the daylight saving time range for the local time zone; false if xtd::date_time::kind is xtd::date_time_kind::utc.

Remarks

This method determines whether the current xtd::date_time value falls within the daylight saving time range of the local time zone, which is returned by the xtd::time_zone_info::local property. You can determine whether a time zone supports daylight saving time by retrieving the value of its xtd::time_zone_info::supports_daylight_saving_time property. For time zones that observe daylight saving time, you can determine when the transition to and from daylight saving time occurs by retrieving the xtd::time_zone_info::adjustment_rule array returned by the time zone's xtd::time_zone_info::get_adjustmen_rules property.

If the current xtd::date_time value represents either an ambiguous or an invalid time in the local time zone, the method returns false.

is_leap_year()

static bool xtd::date_time::is_leap_year ( uint32  year )

static

Returns an indication whether the specified year is a leap year.

Parameters

year	A 4-digit year.

Returns

true if year is a leap year; otherwise, false.

Exceptions

xtd::argument_out_of_range_exception

year is less than 1 or greater than 9999.

kind()

date_time_kind xtd::date_time::kind ( ) const

noexcept

Gets a value that indicates whether the time represented by this instance is based on local time, Coordinated Universal Time (UTC), or neither.

Returns

One of the enumeration values that indicates what the current time represents. The default is xtd::date_time_kind::unspecified.

Examples

The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Get the date and time for the current moment, adjusted
    // to the local time zone.
    
    auto save_now = date_time::now();
    
    // Get the date and time for the current moment expressed
    // as coordinated universal time (UTC).
    
    auto save_utc_now = date_time::utc_now();
    auto my_dt = date_time {};
    
    // display the value and kind property of the current moment
    // expressed as UTC and local time.
    
    display_now("utc_now: ...........", save_utc_now);
    display_now("now: ...............", save_now);
    console::write_line();
    
    // Change the kind property of the current moment to
    // date_time_kind::utc and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
    display("utc: ...............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::local and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::local);
    display("local: .............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::unspecified and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
    display("unspecified: .......", my_dt);
  }
  
  // display the value and kind() property of a date_time structure, the
  // date_time structure converted to local time, and the date_time
  // structure converted to universal time.
  
  static void display(const ustring& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = ustring::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
    
    // Convert input_dt to local time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was universal time.
    
    disp_dt = input_dt.to_local_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_local_time:     {0}, kind = {1}", dt_string, disp_dt.kind());
    
    // Convert input_dt to universal time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was local time.
    
    disp_dt = input_dt.to_universal_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
    console::write_line();
  }
  
  // display the value and kind property for date_time::now() and date_time::utc_now().
  
  static void display_now(const ustring& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
//   to_local_time:     2021-12-31 19:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc

Remarks

You can explicitly set the xtd::date_time::xtd::date_time::kind property of a new xtd::date_time value to a particular xtd::date_time_kind value by calling the xtd::date_time::specify_kind method.

The xtd::date_time::kind property allows a xtd::date_time value to clearly reflect either Coordinated Universal Time (UTC) or the local time. In contrast, the xtd::date_time_offset structure can unambiguously reflect any time in any time zone as a single point in time.

Examples

date_time_specify_kind.cpp.

millisecond()

uint32 xtd::date_time::millisecond ( ) const

noexcept

Gets the milliseconds component of the date represented by this instance.

Returns

The milliseconds component, expressed as a value between 0 and 999.

Examples

The following example demonstrates the xtd::date_time::millisecond property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

Remarks

You can display the string representation of the xtd::date::time::millisecond property by using the "b" or "B" format specifier. For example, the following code displays a string that contains the number of milliseconds in a date and time to the console.

date_time date1(2008, 1, 1, 0, 30, 45, 125);
console::write_line("milliseconds: {0:b}", date1); // displays milliseconds: 125

You can also display the millisecond component together with the other components of a date and time value by using the "s" standard format specifier. For example:

date_time date2(2008, 1, 1, 0, 30, 45, 125);
Console.WriteLine("Date: {0:s}", date2);
// Displays the following output to the console:
//      Date: 2008-01-01T00:30:45.1250000

minute()

uint32 xtd::date_time::minute ( ) const

noexcept

Gets the minute component of the date represented by this instance.

Returns

The minute component, expressed as a value between 0 and 59.

Examples

The following example demonstrates the xtd::date_time::minute property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

month()

uint32 xtd::date_time::month ( ) const

noexcept

Gets the month component of the date represented by this instance.

Returns

The month component, expressed as a value between 1 and 12.

Examples

The following example demonstrates the xtd::date_time::month property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

now()

static date_time xtd::date_time::now ( )

staticnoexcept

Gets a xtd::date_time object that is set to the current date and time on this computer, expressed as the local time.

Returns

An object whose value is the current local date and time.

Examples

The following example uses the xtd::date_time::now and xtd::date_time::utc_now properties to retrieve the current local date and time and the current universal coordinated (UTC) date and time. It then uses the formatting conventions of a number of locale to display the strings, along with the values of the their xtd::datte_time::kind properties.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <vector>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto local_date = date_time::now();
    auto utc_date = date_time::utc_now();
    auto locale_names = vector {"en_US", "en_GB", "fr_FR", "de_DE", "ru_RU"};
    
    for (auto locale_name : locale_names) {
      try {
        locale::global(locale {locale_name + ".utf-8"_s});
        console::write_line("{}:", locale_name);
        console::write_line("   Local date and time: {}, {}", local_date.to_string(), local_date.kind());
        console::write_line("   UTC date and time: {}, {}\n", utc_date.to_string(), utc_date.kind());
      } catch (const exception& e) {
        console::write_line(ustring::format("Make sure {} locale is installed on your system :\n\n{}\n", locale_name, e.what()), "Exception");
      }
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// en_US
//    Local date and time: Sun Jan  2 09:50:36 2022, local
//    UTC date and time: Sun Jan  2 08:50:36 2022, utc
//
// en_GB
//    Local date and time: Sun  2 Jan 09:50:36 2022, local
//    UTC date and time: Sun  2 Jan 08:50:36 2022, utc
//
// fr_FR
//    Local date and time: Dim  2 jan 09:50:36 2022, local
//    UTC date and time: Dim  2 jan 08:50:36 2022, utc
//
// de_DE
//    Local date and time: So  2 Jan 09:50:36 2022, local
//    UTC date and time: So  2 Jan 08:50:36 2022, utc
//
// ru_RU
//    Local date and time: воскресенье,  2 января 2022 г. 09:50:36, local
//    UTC date and time: воскресенье,  2 января 2022 г. 08:50:36, utc

Remarks

The xtd::date_time::now property returns a xtd::date_time value that represents the current date and time on the local computer. Note that there is a difference between a xtd::date_time value, which represents the number of ticks that have elapsed since midnight of January 1, 0001, and the string representation of that xtd::date_time value, which expresses a date and time value in a culture-specific-specific format. For information on formatting date and time values, see the to_string method. The following example displays the short date and time string in a number of culture-specific formats.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto local_date = date_time::now();
    auto locale_names = vector {"en_US", "en_GB", "fr_FR", "de_DE", "ru_RU"};
    
    for (auto locale_name : locale_names) {
      try {
        locale::global(locale {locale_name + ".utf-8"_s});
        console::write_line("{}: {}", locale_name, date_time::sprintf("%x %T", local_date));
      } catch (const exception& e) {
        console::write_line(ustring::format("Make sure {} locale is installed on your system :\n\n{}\n", locale_name, e.what()), "Exception");
      }
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// en_US: 01/02/2022 10:59:07
// en_GB: 02/01/2022 10:59:07
// fr_FR: 02.01.2022 10:59:07
// de_DE: 02.01.2022 10:59:07
// ru_RU: 02.01.2022 10:59:07

Examples

date_time_add.cpp, date_time_add_days.cpp, and sprintf_date_time.cpp.

parse()

static date_time xtd::date_time::parse ( const xtd::ustring &  s )

static

Converts the string representation of a date and time to its xtd::date_time equivalent by using the conventions of the current culture.

Parameters

s	A string that contains a date and time to convert. See The string to parse for more information.

Returns

An object that is equivalent to the date and time contained in s.

Exceptions

xtd::format_exception

s does not contain a valid string representation of a date and time.

Remarks

If s contains time zone information, this method returns a xtd::date_time value whose xtd::date_time::kind property is xtd::date_time_kind::local and converts the date and time in s to local time. Otherwise, it performs no time zone conversion and returns a xtd::date_time value whose Kind property is DateTimeKind.Unspecified.

This overload attempts to parse s by using the formatting conventions of the current culture. The current culture is indicated by the CurrentCulture property. To parse a string using the formatting conventions of a specific culture, call the Parse(String, IFormatProvider) or the Parse(String, IFormatProvider, DateTimeStyles) overloads.

This overload attempts to parse s by using DateTimeStyles.AllowWhiteSpaces style.

second()

uint32 xtd::date_time::second ( ) const

noexcept

Gets the seconds component of the date represented by this instance.

Returns

The seconds component, expressed as a value between 0 and 59.

Examples

The following example demonstrates the xtd::date_time::second property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

specify_kind()

static date_time xtd::date_time::specify_kind ( const date_time &  value, date_time_kind  kind  )

static

Creates a new xtd::date_time object that has the same number of ticks as the specified xtd::date_time, but is designated as either local time, Coordinated Universal Time (UTC), or neither, as indicated by the specified xtd::date_time_kind value.

Parameters

value	A date and time.
kind	One of the enumeration values that indicates whether the new object represents local time, UTC, or neither.

Returns

A new object that has the same number of ticks as the object represented by the value parameter and the xtd::date_time_kind value specified by the kind parameter.

Examples

The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Get the date and time for the current moment, adjusted
    // to the local time zone.
    
    auto save_now = date_time::now();
    
    // Get the date and time for the current moment expressed
    // as coordinated universal time (UTC).
    
    auto save_utc_now = date_time::utc_now();
    auto my_dt = date_time {};
    
    // display the value and kind property of the current moment
    // expressed as UTC and local time.
    
    display_now("utc_now: ...........", save_utc_now);
    display_now("now: ...............", save_now);
    console::write_line();
    
    // Change the kind property of the current moment to
    // date_time_kind::utc and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
    display("utc: ...............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::local and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::local);
    display("local: .............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::unspecified and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
    display("unspecified: .......", my_dt);
  }
  
  // display the value and kind() property of a date_time structure, the
  // date_time structure converted to local time, and the date_time
  // structure converted to universal time.
  
  static void display(const ustring& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = ustring::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
    
    // Convert input_dt to local time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was universal time.
    
    disp_dt = input_dt.to_local_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_local_time:     {0}, kind = {1}", dt_string, disp_dt.kind());
    
    // Convert input_dt to universal time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was local time.
    
    disp_dt = input_dt.to_universal_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
    console::write_line();
  }
  
  // display the value and kind property for date_time::now() and date_time::utc_now().
  
  static void display_now(const ustring& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
//   to_local_time:     2021-12-31 19:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc

sprintf()

static xtd::ustring xtd::date_time::sprintf ( const ustring &  format, const date_time &  value  )

static

Returns a xtd::ustring that represents the current xtd::date_time.

Parameters

format	Format-control String.
value	The xtd::date_time object to format.

Returns

A xtd::ustring that represents the current xtd::date_time.

Examples

The foloowwing example shows how to use xtd::date_time::sprintf with differentt formats.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto date1 = date_time {2008, 4, 1, 18, 7, 5, 16};
    console::write_line(date_time::sprintf("%a", date1));  // Tue
    console::write_line(date_time::sprintf("%A", date1));  // Tuesday
    console::write_line(date_time::sprintf("%b", date1));  // Apr
    console::write_line(date_time::sprintf("%B", date1));  // April
    console::write_line(date_time::sprintf("%c", date1));  // Tue Apr  1 18:07:05 2008
    console::write_line(date_time::sprintf("%C", date1));  // 20
    console::write_line(date_time::sprintf("%d", date1));  // 01
    console::write_line(date_time::sprintf("%D", date1));  // 04/01/08
    console::write_line(date_time::sprintf("%e", date1));  //  1
    console::write_line(date_time::sprintf("%Ec", date1)); // Tue Apr  1 18:07:05 2008
    console::write_line(date_time::sprintf("%EC", date1)); // 20
    console::write_line(date_time::sprintf("%Ex", date1)); // 04/01/08
    console::write_line(date_time::sprintf("%EX", date1)); // 18:07:05
    console::write_line(date_time::sprintf("%Ey", date1)); // 08
    console::write_line(date_time::sprintf("%EY", date1)); // 2008
    console::write_line(date_time::sprintf("%F", date1));  // 2008-04-01
    console::write_line(date_time::sprintf("%g", date1));  // 08
    console::write_line(date_time::sprintf("%G", date1));  // 2008
    console::write_line(date_time::sprintf("%h", date1));  // Apr
    console::write_line(date_time::sprintf("%H", date1));  // 18
    console::write_line(date_time::sprintf("%I", date1));  // 06
    console::write_line(date_time::sprintf("%j", date1));  // 093
    console::write_line(date_time::sprintf("%m", date1));  // 04
    console::write_line(date_time::sprintf("%M", date1));  // 07
    console::write_line(date_time::sprintf("%p", date1));  // PM
    console::write_line(date_time::sprintf("%r", date1));  // 06:07:05 PM
    console::write_line(date_time::sprintf("%R", date1));  // 18:07
    console::write_line(date_time::sprintf("%S", date1));  // 05
    console::write_line(date_time::sprintf("%T", date1));  // 18:07:05
    console::write_line(date_time::sprintf("%u", date1));  // 2
    console::write_line(date_time::sprintf("%U", date1));  // 13
    console::write_line(date_time::sprintf("%V", date1));  // 14
    console::write_line(date_time::sprintf("%w", date1));  // 2
    console::write_line(date_time::sprintf("%W", date1));  // 14
    console::write_line(date_time::sprintf("%x", date1));  // 04/01/08
    console::write_line(date_time::sprintf("%X", date1));  // 18:07:05
    console::write_line(date_time::sprintf("%y", date1));  // 08
    console::write_line(date_time::sprintf("%Y", date1));  // 2008
    console::write_line(date_time::sprintf("%z", date1));  // +0100
    console::write_line(date_time::sprintf("%Z", date1));  // CET
    console::write_line(date_time::sprintf("%Od", date1)); // 01
    console::write_line(date_time::sprintf("%Oe", date1)); //  1
    console::write_line(date_time::sprintf("%OH", date1)); // 18
    console::write_line(date_time::sprintf("%OI", date1)); // 06
    console::write_line(date_time::sprintf("%Om", date1)); // 04
    console::write_line(date_time::sprintf("%OM", date1)); // 07
    console::write_line(date_time::sprintf("%OS", date1)); // 05
    console::write_line(date_time::sprintf("%Ou", date1)); // 2
    console::write_line(date_time::sprintf("%OU", date1)); // 13
    console::write_line(date_time::sprintf("%OV", date1)); // 14
    console::write_line(date_time::sprintf("%Ow", date1)); // 2
    console::write_line(date_time::sprintf("%OW", date1)); // 14
    console::write_line(date_time::sprintf("%Oy", date1)); // 08
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Tue
// Tuesday
// Apr
// April
// Tue Apr  1 18:07:05 2008
// 20
// 01
// 04/01/08
//  1
// Tue Apr  1 18:07:05 2008
// 20
// 04/01/08
// 18:07:05
// 08
// 2008
// 2008-04-01
// 08
// 2008
// Apr
// 18
// 06
// 093
// 04
// 07
// PM
// 06:07:05 PM
// 18:07
// 05
// 18:07:05
// 2
// 13
// 14
// 2
// 14
// 04/01/08
// 18:07:05
// 08
// 2008
// +0100
// CET
// 01
//  1
// 18
// 06
// 04
// 07
// 05
// 2
// 13
// 14
// 2
// 14
// 08

Remarks

The formatting codes for sprintf are listed below:

Format	Print
%a	writes abbreviated weekday name, e.g. Fri (locale dependent).
%A	writes full weekday name, e.g. Friday (locale dependent).
%b	writes abbreviated month name, e.g. Oct (locale dependent)
%B	writes full month name, e.g. October (locale dependent).
%c	writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
%C	writes first 2 digits of year as a decimal number (range [00,99]).
%d	writes day of the month as a decimal number (range [01,31]).
%D	equivalent to "%m/%d/%y".
%e	writes day of the month as a decimal number (range [1,31]).
%Ec	writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%EC	Writes name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP
%Ex	writes alternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%EX	writes alternative time representation (locale dependent).
%Ey	writes year as offset from locale's alternative calendar period EC.
%EY	writes year in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%F	equivalent to "%Y-%m-%d" (the ISO 8601 date format).
%g	writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]).
%G	writes ISO 8601 week-based year, i.e. the year that contains the specified week.
%h	synonym of b.
%H	writes hour as a decimal number, 24 hour clock (range [00-23]).
%I	writes hour as a decimal number, 12 hour clock (range [01,12]).
%j	writes day of the year as a decimal number (range [001,366]).
%m	writes month as a decimal number (range [01,12]).
%M	writes minute as a decimal number (range [00,59]).
%Od	writes zero-based day of the month using the alternative numeric system, e.g 二十七 instead of 27 in ja_JP locale.
%Oe	writes one-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale.
%OH	writes hour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale.
%OI	writes hour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale.
%Om	writes month using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale.
%OM	writes minute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale.
%OS	writes second using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale.
%Ou	writes weekday, where Monday is 1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale.
%OU	writes week of the year, as by U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%OV	writes week of the year, as by V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%Ow	writes weekday, where Sunday is 0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale.
%OW	writes week of the year, as by W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%Oy	writes last 2 digits of year using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale.
%p	writes localized a.m. or p.m. (locale dependent).
%r	writes localized 12-hour clock time (locale dependent).
%R	equivalent to "%H:%M".
%S	writes second as a decimal number (range [00,60]).
%T	equivalent to "%H:%M:%S" (the ISO 8601 time format)
%u	writes weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).
%U	writes week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).
%V	writes ISO 8601 week of the year (range [01,53]).
%w	writes weekday as a decimal number, where Sunday is 0 (range [0-6]).
%W	writes week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).
%x	writes localized date representation (locale dependent).
%X	writes localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent).
%y	writes last 2 digits of year as a decimal number (range [00,99]).
%Y	writes year as a decimal number, e.g. 2017.
%z	writes offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available.
%Z	writes locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available.
%%	writes literal %. The full conversion specification must be %%.
%n	writes newline character.
%t	writes horizontal tab character.

See std::put_time for more information.

subtract() [1/2]

xtd::time_span xtd::date_time::subtract

(

const date_time &

value

)

const

Returns a new xtd::time_span that subtracts the specified date and time from the value of this instance.

Parameters

value

The date and time value to subtract.

Returns

A time interval that is equal to the date and time represented by this instance minus the date and time represented by value.

Exceptions

xtd::argument_out_of_range_exception

The result is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

Examples

The following example demonstrates the xtd::date_time::subtract method and the subtraction operator.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
class program {
public:
  static auto main() {
    auto date1 = xtd::date_time {1996, 6, 3, 22, 15, 0};
    xtd::console::write_line("date1 = {:u}", date1);
    auto date2 = xtd::date_time {1996, 12, 6, 13, 2, 0};
    xtd::console::write_line("date2 = {:u}", date2);
    auto date3 = xtd::date_time {1996, 10, 12, 8, 42, 0};
    xtd::console::write_line("date3 = {:u}", date3);
    
    // diff1 gets 185 days, 14 hours, and 47 minutes.
    auto diff1 = date2.subtract(date1);
    xtd::console::write_line("diff1 = {}", diff1);
    
    // date4 gets 4/9/1996 5:55:00 PM.
    auto date4 = date3.subtract(diff1);
    xtd::console::write_line("date4 = {:u}", date4);
    
    // diff2 gets 55 days 4 hours and 20 minutes.
    auto diff2 = date2 - date3;
    xtd::console::write_line("diff2 = {}", diff2);
    
    // date5 gets 4/9/1996 5:55:00 PM.
    auto date5 = date1 - diff2;
    xtd::console::write_line("date5 = {:u}", date5);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// date1 = 1996-06-03 22:15:00
// date2 = 1996-12-06 13:02:00
// date3 = 1996-10-12 08:42:00
// diff1 = 185.14:47:00
// date4 = 1996-04-09 17:55:00
// diff2 = Sun Feb 25 04:20:00 0001
// date5 = 1996-04-09 17:55:00
 

Remarks

The xtd::date_time::subtract(const xtd::date_time&) method determines the difference between two dates. To subtract a time interval from the current instance, call the xtd::date_time::subtract(xtd::time_span) method. To subtract a particular time interval from the current instance, call the method that adds that time interval to the current date, and supply a negative value as the method argument. For example, to subtract two months from the current date, call the xtd::date_time::add_months method with a value of -2.

If the date and time of the current instance is earlier than value, the method returns a xtd::time_span object that represents a negative time span. That is, the value of all of its non-zero properties (such as xtd::date_time::days or xtd::date_time::ticks) is negative.

The xtd::date_time::subtract(const xtd::date_time&) method does not consider the value of the xtd::date_time::kind property of the two xtd::date_time values when performing the subtraction. Before subtracting xtd::date_time::date_time objects, ensure that the objects represent times in the same time zone. Otherwise, the result will include the difference between time zones.

Note

The xtd::date_time_offset::subtract(const xtd::date_time_offset&) method does consider the difference between time zones when performing the subtraction.

subtract() [2/2]

date_time xtd::date_time::subtract

(

const xtd::time_span &

value

)

const

Returns a new xtd::date_time that subtracts the specified duration from the value of this instance.

Parameters

value

The time interval to subtract.

Returns

An object that is equal to the date and time represented by this instance minus the time interval represented by value.

Exceptions

xtd::argument_out_of_range_exception

The result is less than xtd::date_time:min_value or represents a time greater than xtd::date_time:max_value.

Examples

The following example demonstrates the xtd::date_time::subtract method and the subtraction operator.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
class program {
public:
  static auto main() {
    auto date1 = xtd::date_time {1996, 6, 3, 22, 15, 0};
    xtd::console::write_line("date1 = {:u}", date1);
    auto date2 = xtd::date_time {1996, 12, 6, 13, 2, 0};
    xtd::console::write_line("date2 = {:u}", date2);
    auto date3 = xtd::date_time {1996, 10, 12, 8, 42, 0};
    xtd::console::write_line("date3 = {:u}", date3);
    
    // diff1 gets 185 days, 14 hours, and 47 minutes.
    auto diff1 = date2.subtract(date1);
    xtd::console::write_line("diff1 = {}", diff1);
    
    // date4 gets 4/9/1996 5:55:00 PM.
    auto date4 = date3.subtract(diff1);
    xtd::console::write_line("date4 = {:u}", date4);
    
    // diff2 gets 55 days 4 hours and 20 minutes.
    auto diff2 = date2 - date3;
    xtd::console::write_line("diff2 = {}", diff2);
    
    // date5 gets 4/9/1996 5:55:00 PM.
    auto date5 = date1 - diff2;
    xtd::console::write_line("date5 = {:u}", date5);
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// date1 = 1996-06-03 22:15:00
// date2 = 1996-12-06 13:02:00
// date3 = 1996-10-12 08:42:00
// diff1 = 185.14:47:00
// date4 = 1996-04-09 17:55:00
// diff2 = Sun Feb 25 04:20:00 0001
// date5 = 1996-04-09 17:55:00
 

Remarks

The xtd::date_time::subtract(xtd::time_span) method returns the date that is a specified time interval difference from the current instance. To determine the time interval between two dates, call the xtd::date_time::subtract(const xtd::date_time&) method. To subtract a particular time interval from the current instance, call the method that adds that time interval to the current date, and supply a negative value as the method argument. For example, to subtract two months from the current date, call the xtd::date_time::add_months method with a value of -2.

This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.

Ordinarily, the xtd::date_time::subtract(xtd::time_span) method subtracts a xtd::time_span object that represents a positive time span and returns a xtd::date_time value that is earlier than the date and time of the current instance. However, if the xtd::time_span object represents a negative time span, the xtd::date_time::subtract(xtd::time_span) method returns a xtd::date_time value that is later than the date and time of the current instance.

The xtd::date_time::subtract(xtd::time_span) method allows you to subtract a time interval that consists of more than one unit of time (such as a given number of hours and a given number of minutes). To subtract a single unit of time (such as years, months, or days) from the xtd::date_time instance, you can pass a negative numeric value as a parameter to any of the following methods:

• xtd::date_time::add_years, to subtract a specific number of years from the current date and time instance.
• xtd::date_time::add_months, to subtract a specific number of months from the current date and time instance.
• xtd::date_time::add_days, to subtract a specific number of days from the current date and time instance.
• xtd::date_time::add_hours, to subtract a specific number of hours from the current date and time instance.
• xtd::date_time::add_minutes, to subtract a specific number of minutes from the current date and time instance.
• xtd::date_time::add_seconds, to subtract a specific number of seconds from the current date and time instance.
• xtd::date_time::add_milliseconds, to subtract a specific number of milliseconds from the current date and time instance.
• xtd::date_time::add_ticks, to subtract a specific number of ticks from the current date and time instance.

ticks()

int64 xtd::date_time::ticks ( ) const

noexcept

Gets the number of ticks that represent the date and time of this instance.

Returns

The number of ticks that represent the date and time of this instance. The value is between xtd::date_time::min_value.ticks and xtd::date_time::max_value.ticks.

Examples

The following example uses the xtd::date_time::ticks property to display the number of ticks that have elapsed since the beginning of the century.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace std::chrono;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto century_begin = date_time {2001, 1, 1};
    auto current_date = date_time::now();
    
    auto elapsed_ticks = current_date.ticks() - century_begin.ticks();
    auto elapsed_span = time_span {elapsed_ticks};
 
    console::write_line("Elapsed from the beginning of the century to {:f}:", current_date);
    console::write_line("   {:N0} nanoseconds", elapsed_ticks * 100);
    console::write_line("   {:N0} ticks", elapsed_ticks);
    console::write_line("   {:N2} seconds", elapsed_span.total_seconds());
    console::write_line("   {:N2} minutes", elapsed_span.total_minutes());
    console::write_line("   {:N0} days, {} hours, {} minutes, {} seconds", elapsed_span.days(), elapsed_span.hours(),
                        elapsed_span.minutes(), elapsed_span.seconds());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Elapsed from the beginning of the century to Wed Aug 16 22:46:16 2023:
//    713918776070706048 nanoseconds
//    7139187760707060 ticks
//    713918776.07 seconds
//    11898646.27 minutes
//    8262 days, 22 hours, 46 minutes, 16 seconds

Examples

date_time_ticks.cpp.

ticks_duration()

xtd::ticks xtd::date_time::ticks_duration ( ) const

noexcept

Gets the number of ticks that represent the date and time of this instance.

Returns

The number of ticks that represent the date and time of this instance. The value is between xtd::date_time::min_value.ticks and xtd::date_time::max_value.ticks.

Examples

The following example uses the xtd::date_time::ticks property to display the number of ticks that have elapsed since the beginning of the century.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace std::chrono;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto century_begin = date_time {2001, 1, 1};
    auto current_date = date_time::now();
    
    auto elapsed_ticks = current_date.ticks() - century_begin.ticks();
    auto elapsed_span = time_span {elapsed_ticks};
 
    console::write_line("Elapsed from the beginning of the century to {:f}:", current_date);
    console::write_line("   {:N0} nanoseconds", elapsed_ticks * 100);
    console::write_line("   {:N0} ticks", elapsed_ticks);
    console::write_line("   {:N2} seconds", elapsed_span.total_seconds());
    console::write_line("   {:N2} minutes", elapsed_span.total_minutes());
    console::write_line("   {:N0} days, {} hours, {} minutes, {} seconds", elapsed_span.days(), elapsed_span.hours(),
                        elapsed_span.minutes(), elapsed_span.seconds());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Elapsed from the beginning of the century to Wed Aug 16 22:46:16 2023:
//    713918776070706048 nanoseconds
//    7139187760707060 ticks
//    713918776.07 seconds
//    11898646.27 minutes
//    8262 days, 22 hours, 46 minutes, 16 seconds

time_of_day()

xtd::time_span xtd::date_time::time_of_day ( ) const

noexcept

Gets the time of day for this instance.

Returns

A time interval that represents the fraction of the day that has elapsed since midnight.

Examples

The following example displays the value of the xtd::date_time::time_of_day property for an array of xtd::date_time values. It also contrasts the return value with the string returned by the "t" standard format string in a composite formatting operation.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Get the current date.
    auto this_day = date_time::today();
    // Display the date in the default (general) format.
    console::write_line(this_day.to_string());
    console::write_line();
    // Display the date in a variety of formats.
    console::write_line(this_day.to_string("d"));
    console::write_line(this_day.to_string("D"));
    console::write_line(this_day.to_string("g"));
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Wed Jan 12 00:00:00 2022
//
// 01/12/2022
// 1/12/2022
// Wed Jan 12 00:00:00 2022

Remarks

Unlike the xtd::date_time::date property. which returns a xtd::date_time value that represents a date without its time component, the xtd::date_time::time_of_day property returns a xtd::time_span value that represents a xtd::date_time value's time component.

If you want to display the time of day or retrieve the string representation of the time of day of a xtd::date_time value, you can instead call an overload of the ToString method that has a format parameter or use the composite formatting feature with the "t" or "T" standard format string.

to_binary()

int64 xtd::date_time::to_binary

(

)

const

Serializes the current xtd::date_time object to a 64-bit binary value that subsequently can be used to recreate the xtd::date_time object.

Returns

A 64-bit signed integer that encodes the xtd::date_time::kind and xtd::date_time::ticks properties.

Remarks

Use the xtd::date_time::to_binary method to convert the value of the current xtd::date_time object to a binary value. Subsequently, use the binary value and the xtd::date_time::from_binary method to recreate the original xtd::date_time object.

to_file_time()

int64 xtd::date_time::to_file_time

(

)

const

Converts the value of the current xtd::date_time object to a Windows file time.

Returns

The value of the current xtd::date_time object expressed as a Windows file time.

Exceptions

xtd::argument_out_of_range_exception

The resulting file time would represent a date and time before 12:00 midnight January 1, 1601 C.E. UTC.

Remarks

A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file.

The xtd::date_time::to_file_time method uses the xtd::date_time::kind property to determine whether the current xtd::date_time object is a local time, a UTC time, or an unspecified kind of time which is treated as a local time.

to_file_time_utc()

int64 xtd::date_time::to_file_time_utc

(

)

const

Converts the value of the current xtd::date_time object to a Windows file time.

Returns

The value of the current xtd::date_time object expressed as a Windows file time.

Exceptions

xtd::argument_out_of_range_exception

The resulting file time would represent a date and time before 12:00 midnight January 1, 1601 C.E. UTC.

Remarks

A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file.

The xtd::date_time::to_file_time_utc method uses the xtd::date_time::to_file_timextd::date_time::kind property to determine whether the current xtd::date_time object is a local time, a UTC time, or an unspecified kind of time which is treated as a UTC time. If it is a local time, it converts the time to UTC before performing the conversion to a Windows file time.

to_local_time()

date_time xtd::date_time::to_local_time

(

)

const

Converts the value of the current xtd::date_time object to local time.

Returns

An object whose xtd::date_time::kind property is xtd::date_time_kind::local, and whose value is the local time equivalent to the value of the current xtd::date_time object, or xtd::date_time::max_value if the converted value is too large to be represented by a xtd::date_time object, or xtd::date_time::min_value if the converted value is too small to be represented as a xtd::date_time object.

Examples

The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Get the date and time for the current moment, adjusted
    // to the local time zone.
    
    auto save_now = date_time::now();
    
    // Get the date and time for the current moment expressed
    // as coordinated universal time (UTC).
    
    auto save_utc_now = date_time::utc_now();
    auto my_dt = date_time {};
    
    // display the value and kind property of the current moment
    // expressed as UTC and local time.
    
    display_now("utc_now: ...........", save_utc_now);
    display_now("now: ...............", save_now);
    console::write_line();
    
    // Change the kind property of the current moment to
    // date_time_kind::utc and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
    display("utc: ...............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::local and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::local);
    display("local: .............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::unspecified and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
    display("unspecified: .......", my_dt);
  }
  
  // display the value and kind() property of a date_time structure, the
  // date_time structure converted to local time, and the date_time
  // structure converted to universal time.
  
  static void display(const ustring& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = ustring::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
    
    // Convert input_dt to local time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was universal time.
    
    disp_dt = input_dt.to_local_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_local_time:     {0}, kind = {1}", dt_string, disp_dt.kind());
    
    // Convert input_dt to universal time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was local time.
    
    disp_dt = input_dt.to_universal_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
    console::write_line();
  }
  
  // display the value and kind property for date_time::now() and date_time::utc_now().
  
  static void display_now(const ustring& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
//   to_local_time:     2021-12-31 19:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc

Remarks

The local time is equal to the Coordinated Universal Time (UTC) time plus the UTC offset. For more information about the UTC offset, see xtd::time_zone_info::get_utc_offset. The conversion also takes into account the daylight saving time rule that applies to the time represented by the current xtd::date_time object.

The value returned by the xtd::date_time::to_local_time method is determined by the xtd::date_time::kind property of the current xtd::date_time object. The following table describes the possible results.

Kind	Results
xtd::date_time_kind::utc	This instance of xtd::date_timextd::date_time is converted to local time.
xtd::date_time_kind::local	No conversion is performed.
xtd::date_time_kind::unspecified	This instance of xtd::date_time is assumed to be a UTC time, and the conversion is performed as if xtd::date_time::kind were xtd::date_time_kind::utc.

Note

The xtd::date_time::to_local_time method converts a xtd::date_time:: value from UTC to local time. To convert the time in any designated time zone to local time, use the xtd::time_zone_info::convert_time method.

Remarks

The value returned by the conversion is a xtd::date_time whose xtd::date_time::Kind property always returns xtd::date_time_kind::local. Consequently, a valid result is returned even if xtd::date_time::to_local_time is applied repeatedly to the same xtd::date_time.

Examples

date_time_specify_kind.cpp.

to_long_date_string()

const xtd::ustring xtd::date_time::to_long_date_string

(

)

const

Converts the value of the current xtd::date_time object to its equivalent long date string representation.

Returns

A string that contains the long date string representation of the current xtd::date_time object.

Remarks

The return value is identical to the value returned by specifying the "n" standard xtd::date_time format string with the xtd::date_time::to_string(const xtd::ustring&) method.

to_long_time_string()

const xtd::ustring xtd::date_time::to_long_time_string

(

)

const

Converts the value of the current xtd::date_time object to its equivalent long time string representation.

Returns

A string that contains the long time string representation of the current xtd::date_time object.

Remarks

The return value is identical to the value returned by specifying the "T" standard xtd::date_time format string with the xtd::date_time::to_string(const xtd::ustring&) method.

to_short_date_string()

const xtd::ustring xtd::date_time::to_short_date_string

(

)

const

Converts the value of the current xtd::date_time object to its equivalent short date string representation.

Returns

A string that contains the short date string representation of the current xtd::date_time object.

Remarks

The return value is identical to the value returned by specifying the "D" standard xtd::date_time format string with the xtd::date_time::to_string(const xtd::ustring&) method.

to_short_time_string()

const xtd::ustring xtd::date_time::to_short_time_string

(

)

const

Converts the value of the current xtd::date_time object to its equivalent short time string representation.

Returns

A string that contains the short time string representation of the current xtd::date_time object.

Remarks

The return value is identical to the value returned by specifying the "V" standard xtd::date_time format string with the xtd::date_time::to_string(const xtd::ustring&) method.

to_string() [1/2]

xtd::ustring xtd::date_time::to_string ( ) const

overridevirtualnoexcept

Converts the value of the current xtd::date_time object to its equivalent string representation using the formatting conventions of the current culture.

Returns

A string representation of the value of the current xtd::date_time object.

Remarks

The return value is identical to the value returned by specifying the "G" standard xtd::date_time format string with the xtd::date_time::to_string(const xtd::ustring&) method.

Reimplemented from xtd::object.

Examples

date_time_specify_kind.cpp.

to_string() [2/2]

xtd::ustring xtd::date_time::to_string

(

const ustring &

format

)

const

Converts the value of the current xtd::date_time object to its equivalent string representation using the specified format and the formatting conventions of the current culture.

Parameters

format

A standard or custom date and time format string.

Returns

A string representation of value of the current xtd::date_time object as specified by format.

Exceptions

xtd::format_excpetion

The length of format is 1, and it is not a valid format characters -or- The length si greater than 1.

Examples

The foloowwing example shows how to use xtd::date_time::to_string(const xtd::ustring&) with differentt formats.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto date1 = date_time {2008, 4, 1, 18, 7, 5, 16};
    console::write_line(date1.to_string("a")); // PM
    console::write_line(date1.to_string("b")); // 016
    console::write_line(date1.to_string("B")); // 16
    console::write_line(date1.to_string("c")); // 0160000
    console::write_line(date1.to_string("c")); // 160000
    console::write_line(date1.to_string("d")); // 04/01/2008
    console::write_line(date1.to_string("D")); // 4/01/2008
    console::write_line(date1.to_string("e")); // 05
    console::write_line(date1.to_string("E")); // 5
    console::write_line(date1.to_string("f")); // Tue Apr  1 18:07:05 2008
    console::write_line(date1.to_string("F")); // Tue Apr  1 18:07:05 2008
    console::write_line(date1.to_string("g")); // Tue Apr  1 18:07:05 2008
    console::write_line(date1.to_string("G")); // Tue Apr  1 18:07:05 2008
    console::write_line(date1.to_string("h")); // Tue
    console::write_line(date1.to_string("H")); // Tuesday
    console::write_line(date1.to_string("i")); // 01
    console::write_line(date1.to_string("I")); // 1
    console::write_line(date1.to_string("j")); // Apr
    console::write_line(date1.to_string("J")); // April
    console::write_line(date1.to_string("k")); // 04
    console::write_line(date1.to_string("K")); // 4
    console::write_line(date1.to_string("l")); // 08
    console::write_line(date1.to_string("L")); // 2008
    console::write_line(date1.to_string("m")); // 2008
    console::write_line(date1.to_string("M")); // April 1
    console::write_line(date1.to_string("n")); // Tuesday, 1 April 2008
    console::write_line(date1.to_string("N")); // Tuesday, 1 April 2008 18:07:05
    console::write_line(date1.to_string("o")); // 1 April 2008
    console::write_line(date1.to_string("O")); // 1 April 2008
    console::write_line(date1.to_string("p")); // 07
    console::write_line(date1.to_string("P")); // 7
    console::write_line(date1.to_string("s")); // 2008-04-01T18:07:05.0160000
    console::write_line(date1.to_string("t")); // 18:07:05
    console::write_line(date1.to_string("T")); // 18:07:05
    console::write_line(date1.to_string("u")); // 2008-04-01 18:07:05
    console::write_line(date1.to_string("U")); // Tuesday, 1 April 2008 18:07:05
    console::write_line(date1.to_string("v")); // 18:07
    console::write_line(date1.to_string("V")); // 18:07
    console::write_line(date1.to_string("w")); // 18
    console::write_line(date1.to_string("W")); // 18
    console::write_line(date1.to_string("x")); // 06
    console::write_line(date1.to_string("X")); // 6
    console::write_line(date1.to_string("y")); // April 8
    console::write_line(date1.to_string("Y")); // April 2008
    console::write_line(date1.to_string("z")); // UTC
    console::write_line(date1.to_string("Z")); // UTC
    
    // Other format generate a xtd::format_exception exception
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// PM
// 016
// 16
// 0160000
// 160000
// 04/01/2008
// 4/01/2008
// 05
// 5
// Tue Apr  1 18:07:05 2008
// Tue Apr  1 18:07:05 2008
// Tue Apr  1 18:07:05 2008
// Tue Apr  1 18:07:05 2008
// Tue
// Tuesday
// 01
// 1
// Apr
// April
// 04
// 4
// 08
// 2008
// 2008
// April 1
// Tuesday, 1 April 2008
// Tuesday, 1 April 2008 18:07:05
// 1 April 2008
// 1 April 2008
// 07
// 7
// 2008-04-01T18:07:05.0160000
// 18:07:05
// 18:07:05
// 2008-04-01 18:07:05
// Tuesday, 1 April 2008 18:07:05
// 18:07
// 18:07
// 18
// 18
// 06
// 6
// April 8
// April 2008
// UTC
// UTC

Remarks

The formatting codes for xtd::date_time::to_string (const xtd::ustring&) are listed below:

Format	Print
'a'	writes "PM" or "AM"
'b'	writes 3 digit millisecond, e.G. 012
'B'	wrties millisecond, eg 12
'c'	writes 7 digit tick, e.G. 0000123
'C'	writes tick, e.G. 123
'd'	writes date MM/dd/y, e.g. 01/05/42
'D'	writes date M/dd/y, e.g. 1/055/42
'e'	writes 2 digit second, e.G. 03
'B'	writes second, e.G. 3
'f'	writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'F'	writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'g'	writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'G'	writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'h'	writes abbreviated weekday name, e.g. Fri (locale dependent).
'H'	writes full weekday name, e.g. Friday (locale dependent).
'i'	writes 2 digit day, e.g. 05
'I'	writes day, e.G. 5
'j'	writes abbreviated month name, e.g. Oct (locale dependent)
'J'	writes full month name, e.g. October (locale dependent).
'k'	writes 2 digit month, e.g. 01
'K'	writes month, e.g. 1
'l'	writes 2 digit year, e.g. 71
'L'	writes 4 digit year, e.g. 1971
'm'	writes year, e.g. 42
'M'	writes full month name and day, e.g. October, 5 (locale dependent).
'n'	writes full weekday name, day, fulll month and year, e.g. Tuesday, 1 April 2008
'N'	writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'o'	writes day, full month and year, e.g. 5 January 42
'O'	writes day, full month and year, e.g. 5 January 42
'p'	writes 2 digit minute, e.G. 06
'P'	writes minute, e.G. 6
's'	writes sortable date/time pattern yyyy-MM-ddThh:mm:ss.ttttttt. e.g. 1971-05-01T21:32:24:42.004567
't'	writes time hh/mm/ss, e.g. 02:04:06
'T'	writes time h/mm/ss, e.g. 2:04:06
'u'	writes sortable short date/time pattern y-MM-dd hh:mm:ss. e.g. 1971-05-01 9:32:24:42
'U'	writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'v'	writes time hh/mm, e.g. 02:04
'V'	writes time h/mm, e.g. 2:04
'w'	writes 2 digit hour (24H), e.g. 07
'W'	writes hour (24H), e.g. 7
'x'	writes 2 digit hour (12H), e.g. 07
'X'	writes hour (12H), e.g. 7
'y'	writes full month name and year, e.g. October, 71 (locale dependent).
'Y'	writes full month name and year, e.g. October, 1971 (locale dependent).
'z'	writes time zone "local" or "UTC".
'Z'	writes time zone "local" or "UTC".

to_time_t()

std::time_t xtd::date_time::to_time_t

(

)

const

Converts the value of the current xtd::date_time object to std::time_t.

Returns

The value of the current xtd::date_time object expressed as std::time_t.

Remarks

std::time_t is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

to_tm()

std::tm xtd::date_time::to_tm

(

)

const

Converts the value of the current xtd::date_time object to std::tm.

Returns

The value of the current xtd::date_time object expressed as std::tm.

Remarks

std::tm is a structure holding a calendar date and time broken down into its components. is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

See <std::chrono for more information.

to_universal_time()

date_time xtd::date_time::to_universal_time

(

)

const

Converts the value of the current xtd::date_time object to Coordinated Universal Time (UTC).

Returns

An object whose xtd::date_time::kind property is xtd::date_time_kind::utc, and whose value is the UTC equivalent to the value of the current xtd::date_time object, or xtd::date_time::max_value if the converted value is too large to be represented by a xtd::date_time object, or xtd::date_time::min_value if the converted value is too small to be represented by a xtd::date_time object.

Examples

The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Get the date and time for the current moment, adjusted
    // to the local time zone.
    
    auto save_now = date_time::now();
    
    // Get the date and time for the current moment expressed
    // as coordinated universal time (UTC).
    
    auto save_utc_now = date_time::utc_now();
    auto my_dt = date_time {};
    
    // display the value and kind property of the current moment
    // expressed as UTC and local time.
    
    display_now("utc_now: ...........", save_utc_now);
    display_now("now: ...............", save_now);
    console::write_line();
    
    // Change the kind property of the current moment to
    // date_time_kind::utc and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
    display("utc: ...............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::local and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::local);
    display("local: .............", my_dt);
    
    // Change the kind property of the current moment to
    // date_time_kind::unspecified and display the result.
    
    my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
    display("unspecified: .......", my_dt);
  }
  
  // display the value and kind() property of a date_time structure, the
  // date_time structure converted to local time, and the date_time
  // structure converted to universal time.
  
  static void display(const ustring& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = ustring::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
    
    // Convert input_dt to local time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was universal time.
    
    disp_dt = input_dt.to_local_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_local_time:     {0}, kind = {1}", dt_string, disp_dt.kind());
    
    // Convert input_dt to universal time and display the result.
    // If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
    // If input_dt.kind() is date_time_kind::local, the conversion is performed.
    // If input_dt.kind() is date_time_kind::unspecified, the conversion is
    // performed as if input_dt was local time.
    
    disp_dt = input_dt.to_universal_time();
    dt_string = disp_dt.to_string("u");
    console::write_line("  to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
    console::write_line();
  }
  
  // display the value and kind property for date_time::now() and date_time::utc_now().
  
  static void display_now(const ustring& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string("u");
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
//   to_local_time:     2021-12-31 18:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
//   to_local_time:     2021-12-31 19:08:41, Kind = local
//   to_universal_time: 2021-12-31 17:08:41, Kind = utc

Remarks

The Coordinated Universal Time (UTC) is equal to the local time minus the UTC offset. For more information about the UTC offset, see xtd::time_zone_info::get_utc_offset. The conversion also takes into account the daylight saving time rule that applies to the time represented by the current xtd::date_time object.

The value returned by the xtd::date_time::to_universal_time method is determined by the xtd::date_time::kind property of the current xtd::date_time object. The following table describes the possible results.

Kind	Results
xtd::date_time_kind::utc	No conversion is performed.
xtd::date_time_kind::local	The current xtd::date_time object is converted to UTC.
xtd::date_time_kind::unspecified	The current xtd::date_time object is assumed to be a local time, and the conversion is performed as if xtd::date_time::kind were Local.

Examples

date_time_specify_kind.cpp.

today()

static date_time xtd::date_time::today ( )

staticnoexcept

Gets the current date.

Returns

An object that is set to today's date, with the time component set to 00:00:00.

Examples

The following example uses the xtd::date_time::date property to retrieve the current date. It also illustrates how a xtd::date_time value can be formatted using some of the standard date and time format strings. Note that the output produced by the third call to the xtd::date_time::to_string(const xtd::ustring&) method uses the g format specifier to include the time component, which is zero.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <vector>
 
using namespace std;
using namespace xtd;
 
class program {
public:
  static auto main() {
    auto dates = vector {date_time::now(), date_time {2013, 9, 14, 9, 28, 0}, date_time {2011, 5, 28, 10, 35, 0}, date_time {1979, 12, 25, 14, 30, 0}};
    for (auto date : dates) {
      console::write_line("Day: {0:d} Time: {1:g}", date.date(), date.time_of_day());
      console::write_line("Day: {0:d} Time: {0:t}\n", date);
    }
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// Day: 01/12/2022 Time: 12:51:49
// Day: 01/12/2022 Time: 12:51:49
//
// Day: 09/14/2013 Time: 9:28:00
// Day: 09/14/2013 Time: 09:28:00
//
// Day: 05/28/2011 Time: 10:35:00
// Day: 05/28/2011 Time: 10:35:00
//
// Day: 12/25/1979 Time: 14:30:00
// Day: 12/25/1979 Time: 14:30:00

Remarks

The return value is a xtd::date_time whose xtd::date_time::kind property returns xtd::date_time_kind::local.

Because it returns the current date without the current time, the xtd::date_time::today property is suitable for use in applications that work with dates only. In contrast, the xtd::date_time::time_of_day property returns the current time without the current date, and the xtd::date_timextd::date_timextd::date_time::now property returns both the current date and the current time.

try_parse()

static bool xtd::date_time::try_parse ( const ustring &  s, date_time &  result  )

staticnoexcept

Converts the specified string representation of a date and time to its xtd::date_time equivalent and returns a value that indicates whether the conversion succeeded.

Parameters

s	A string containing a date and time to convert.
result	When this method returns, contains the xtd::date_time value equivalent to the date and time contained in s, if the conversion succeeded, or xtd::date_time::min_value if the conversion failed. The conversion fails if the s parameter is an empty string (""), or does not contain a valid string representation of a date and time.

Returns

true if the s parameter was converted successfully; otherwise, false.

Remarks

The xtd::date_time::try_parse method is similar to the xtd::date_time::parse method, except that the xtd::date_time::try_parse method does not throw an exception if the conversion fails.

utc_now()

static date_time xtd::date_time::utc_now ( )

staticnoexcept

Gets a xtd::date_time object that is set to the current date and time on this computer, expressed as the Coordinated Universal Time (UTC).

Returns

An object whose value is the current UTC date and time.

Examples

The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.

Remarks

The resolution of this property depends on the system timer, which depends on the underlying operating system. It tends to be between 0.5 and 15 milliseconds.

The return value is a xtd::date_time whose xtd::date_time::kind property returns xtd::date_time_kind::utc.

An alternative to using xtd::date_time::utc_now is xtd::date_time_offset::utc_now. While the former indicates that a date and time value is Coordinated Universal Time (UTC) by assigning xtd::date_time_kind::utc to its xtd::date_time::kind property, the latter assigns the date and time value the UTC time's offset (equal to xtd::ticks(0)).

year()

uint32 xtd::date_time::year ( ) const

noexcept

Gets the year component of the date represented by this instance.

Returns

The year, between 1 and 9999.

Examples

The following example demonstrates the xtd::date_time::year property.

xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
 
// month gets 1 (January).
uint23_t month = moment.month();
 
// day gets 13.
uint23_t day = moment.day();
 
// hour gets 3.
uint23_t hour = moment.hour();
 
// minute gets 57.
uint23_t minute = moment.minute();
 
// second gets 32.
uint23_t second = moment.second();
 
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

Remarks

The xtd::date_time::year property returns the year of the current instance in the Gregorian calendar.

Member Data Documentation

max_value

const date_time xtd::date_time::max_value

static

Represents the largest possible value of xtd::date_time. This field is read-only.

Remarks

The value of this constant is equivalent to 23:59:59.9999999 UTC, December 31, 9999 in the Gregorian calendar, exactly one 100-nanosecond tick before 00:00:00 UTC, January 1, 10000.

Examples

The following example instantiates a xtd::date_time object by passing its constructor an xtd::ticks value that represents a number of ticks. Before invoking the constructor, the example ensures that this value is greater than or equal to date_time::min_value.ticks() and less than or equal to date_time::max_value.ticks(). If not, it throws an xtd::argument_out_of_range_exception.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/int64_object>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Attempt to assign an out-of-range value to a date_time constructor.
    auto number_of_ticks = int64_object::max_value;
    auto valid_date = date_time {};
    
    // Validate the value.
    if (number_of_ticks >= date_time::min_value.ticks() && number_of_ticks <= date_time::max_value.ticks()) {
      valid_date = date_time(number_of_ticks);
      console::write_line("{0} is valid.", valid_date.ticks());
    } else if (number_of_ticks < date_time::min_value.ticks())
      console::write_line("{0} is less than {1} ticks.", number_of_ticks, date_time::min_value.ticks());
    else
      console::write_line("{0} is greater than {1} ticks.", number_of_ticks, date_time::max_value.ticks());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 9223372036854775807 is greater than 3155378975999999999 ticks.

min_value

const date_time xtd::date_time::min_value

static

Represents the smallest possible value of xtd::date_time. This field is read-only.

Examples

The following example instantiates a xtd::date_time object by passing its constructor an xtd::ticks value that represents a number of ticks. Before invoking the constructor, the example ensures that this value is greater than or equal to date_time::min_value.ticks() and less than or equal to date_time::max_value.ticks(). If not, it throws an xtd::argument_out_of_range_exception.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/int64_object>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Attempt to assign an out-of-range value to a date_time constructor.
    auto number_of_ticks = int64_object::max_value;
    auto valid_date = date_time {};
    
    // Validate the value.
    if (number_of_ticks >= date_time::min_value.ticks() && number_of_ticks <= date_time::max_value.ticks()) {
      valid_date = date_time(number_of_ticks);
      console::write_line("{0} is valid.", valid_date.ticks());
    } else if (number_of_ticks < date_time::min_value.ticks())
      console::write_line("{0} is less than {1} ticks.", number_of_ticks, date_time::min_value.ticks());
    else
      console::write_line("{0} is greater than {1} ticks.", number_of_ticks, date_time::max_value.ticks());
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 9223372036854775807 is greater than 3155378975999999999 ticks.

Remarks

The value of this constant is equivalent to 00:00:00.0000000 UTC, January 1, 0001, in the Gregorian calendar.

xtd::date_time::min_value defines the date and time that is assigned to an uninitialized xtd::date_time variable. The following example illustrates this.

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
 
class program {
public:
  static auto main() {
    // Define an uninitialized date.
    auto date1 = date_time {};
    console::write("{:u}", date1);
    if (date1.equals(date_time::min_value))
      console::write_line("  (Equals date_time.min_value)");
  }
};
 
startup_(program::main);
 
// This code can produces the following output:
//
// 01/01/0001 00:00:00  (Equals date_time.min_value)

---

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

• xtd.core/include/xtd/date_time.h