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::string 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::string to its equivalent date and time value. The following example uses the xtd::date_time::parse method to parse a xtd::string and convert it to a xtd::date_time value.

  string 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::string 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/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 produces the following output :
//
// d1 (10/23/2025 1:04:56 AM) ~= d1 (10/23/2025 1:04:56 AM): true
// d1 (10/23/2025 1:04:56 AM) ~= d2 (10/23/2025 1:05:16 AM): false
// d1 (10/23/2025 1:04:56 AM) ~= d3 (10/23/2025 1:04:36 AM): false
// d1 (10/23/2025 1:04:56 AM) ~= d4 (10/23/2025 1:05:01 AM): true
// d1 (10/23/2025 1:04:56 AM) ~= d5 (10/23/2025 1:04:51 AM): true
// d1 (10/23/2025 1:04:56 AM) ~= d6 (10/23/2025 3:05:16 AM): false
// d1 (10/23/2025 1:04:56 AM) ~= d7 (10/23/2025 3:04:36 AM): false
// d1 (10/23/2025 1:04:56 AM) ~= d8 (10/23/2025 3:05:01 AM): true
// d1 (10/23/2025 1:04:56 AM) ~= d9 (10/23/2025 3:04:51 AM): true

Examples

date_time_subtract.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.
template<class clock_t, class duration_t = clock_t::duration>
	date_time (const std::chrono::time_point< clock_t, duration_t > &time_point)
	Initializes a new instance of the xtd::date_time structure to a specified time point.
template<class clock_t, class duration_t = clock_t::duration>
	date_time (const std::chrono::time_point< clock_t, duration_t > &time_point, date_time_kind kind)
	Initializes a new instance of the xtd::date_time structure to a specified time point, 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 object &obj) const noexcept override
	Determines whether the specified object is equal to the current object.
bool	equals (const date_time &other) const noexcept override
	Indicates whether the current object is equal to another object of the same type.
xtd::size	get_hash_code () const noexcept override
	Serves as a hash function for a particular type.
array< string >	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::string	to_long_date_string () const
	Converts the value of the current xtd::date_time object to its equivalent long date string representation.
const xtd::string	to_long_time_string () const
	Converts the value of the current xtd::date_time object to its equivalent long time string representation.
const xtd::string	to_short_date_string () const
	Converts the value of the current xtd::date_time object to its equivalent short date string representation.
const xtd::string	to_short_time_string () const
	Converts the value of the current xtd::date_time object to its equivalent short time string representation.
xtd::string	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::string	to_string (const string &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.
xtd::string	to_string (const string &format, const xtd::globalization::culture_info &culture) const override
	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.
xtd::string	to_string (const xtd::globalization::culture_info &culture) const
	Converts the value of the current xtd::date_time object to its equivalent string representation using the specified 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::string &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	parse (const xtd::string &s, const xtd::globalization::culture_info &culture)
	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::string	sprintf (const string &format, const date_time &value)
	Returns a xtd::string that represents the current xtd::date_time.
static xtd::string	sprintf (const string &format, const date_time &value, const xtd::globalization::culture_info &culture)
	Returns a xtd::string that represents the current xtd::date_time.
static bool	try_parse (const string &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.
static bool	try_parse (const string &s, date_time &result, const xtd::globalization::culture_info &culture) 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.
static bool	try_parse_exact (const string &text, const string &format, date_time &result) noexcept
static bool	try_parse_exact (const string &text, const string &format, date_time &result, const xtd::globalization::culture_info &culture) noexcept
static bool	try_parse_exact (const string &text, const array< string > &formats, date_time &result) noexcept
static bool	try_parse_exact (const string &text, const array< string > &formats, date_time &result, const xtd::globalization::culture_info &culture) noexcept

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

date_time() [1/12]

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/12]

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/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 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/12]

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/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 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/12]

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/12]

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/12]

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/12]

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/12]

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/12]

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/12]

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.

date_time() [11/12]

template<class clock_t, class duration_t = clock_t::duration>

xtd::date_time::date_time ( const std::chrono::time_point< clock_t, duration_t > & time_point )

inline

Initializes a new instance of the xtd::date_time structure to a specified time point.

Parameters

time_point

A std::chrono::time_point value.

Remarks

This constructor can be used for example to convert std::chrono::system_clock::time_point to xtd::date_time.

date_time() [12/12]

template<class clock_t, class duration_t = clock_t::duration>

xtd::date_time::date_time ( const std::chrono::time_point< clock_t, duration_t > & time_point, date_time_kind kind )

inline

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

Parameters

time_point	A std::chrono::time_point value.
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.

Remarks

This constructor can be used for example to convert std::chrono::system_clock::time_point to xtd::date_time.

Member Function Documentation

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/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("MM/dd/yyyy HH:mm"));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// 6/1/2008 7:47:00 AM
// 6/1/2008
// 6/1/2008 0:00 AM
// 06/01/2008 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/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 produces the following output :
//
// Is Thursday the day of the week for 5/1/2003?: true
// The day of the week for 5/1/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/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 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.

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(string) 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

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/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.
  
  inline static const string date_patt = "M/d/yyyy hh:mm:ss tt";  
  static void display(const string& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = string::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("");
    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(date_patt);
    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(date_patt);
    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 string& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string(date_patt);
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// utc_now: ........... 10/24/2025 08:59:24 PM, kind = utc
// now: ............... 10/24/2025 10:59:24 PM, kind = local
//
// utc: ............... 10/24/2025 8:59:24 PM, kind = utc
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// local: ............. 10/24/2025 10:59:24 PM, kind = local
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// unspecified: ....... 10/24/2025 10:59:24 PM, kind = unspecified
//   to_local_time:     10/25/2025 00:59:24 AM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, 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.

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();

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();

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/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 produce 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

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/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 produce 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/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 produce 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.

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.

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 produce the following output :
//
// 10/23/2025 1:06:03 AM
// 11/28/2025 1:06:03 AM

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 produce the following output :
//
// 10/23/2025 1:06:35 AM
// 11/28/2025 1:06:35 AM

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/xtd>
 
class program {
public:
  static auto main() {
    auto hours = list {.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} + {1} hour(s) = {2}", date_value, hour, date_value.add_hours(hour));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// 3/1/2009 12:00:00 PM + 0.08333 hour(s) = 3/1/2009 12:04:59 PM
// 3/1/2009 12:00:00 PM + 0.16667 hour(s) = 3/1/2009 12:10:00 PM
// 3/1/2009 12:00:00 PM + 0.25 hour(s) = 3/1/2009 12:15:00 PM
// 3/1/2009 12:00:00 PM + 0.33333 hour(s) = 3/1/2009 12:19:59 PM
// 3/1/2009 12:00:00 PM + 0.5 hour(s) = 3/1/2009 12:30:00 PM
// 3/1/2009 12:00:00 PM + 0.66667 hour(s) = 3/1/2009 12:40:00 PM
// 3/1/2009 12:00:00 PM + 1 hour(s) = 3/1/2009 1:00:00 PM
// 3/1/2009 12:00:00 PM + 2 hour(s) = 3/1/2009 2:00:00 PM
// 3/1/2009 12:00:00 PM + 29 hour(s) = 3/2/2009 5:00:00 PM
// 3/1/2009 12:00:00 PM + 30 hour(s) = 3/2/2009 6:00:00 PM
// 3/1/2009 12:00:00 PM + 31 hour(s) = 3/2/2009 7:00:00 PM
// 3/1/2009 12:00:00 PM + 90 hour(s) = 3/5/2009 6:00:00 AM
// 3/1/2009 12:00:00 PM + 365 hour(s) = 3/16/2009 5:00:00 PM

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/xtd>
 
class program {
public:
  static auto main() {
    auto date_format = "MM/dd/yyyy hh:mm:ss.fffffff";
    auto date1 = date_time {2010, 9, 8, 16, 0, 0};
    console::write_line("Original date: {0} ({1:N0} ticks)\n", date1.to_string(date_format), date1.ticks());
    
    auto date2 = date1.add_milliseconds(1);
    console::write_line("Second date:   {0} ({1:N0} ticks)", date2.to_string(date_format), 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)", date3.to_string(date_format), date3.ticks());
    console::write_line("Difference between dates: {0} ({1:N0} ticks)", date3 - date1, date3.ticks() - date1.ticks());
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// Original date: 09/08/2010 04:00:00.0000000 (634195584000000000 ticks)
//
// Second date:   09/08/2010 04:00:00.0010000 (634195584000009984 ticks)
// Difference between dates: 00:00:00.0010000 (10000 ticks)
//
// Third date:    09/08/2010 04:00:00.0015000 (634195584000014976 ticks)
// Difference between dates: 00:00:00.0015000 (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/xtd>
 
class program {
public:
  static auto main() {
    auto date = date_time {2015, 12, 31};
    for (auto ctr = 0; ctr <= 15; ctr++)
      console::write_line(date.add_months(ctr).to_string("d"));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// 12/31/2015
// 1/31/2016
// 2/29/2016
// 3/31/2016
// 4/30/2016
// 5/31/2016
// 6/30/2016
// 7/31/2016
// 8/31/2016
// 9/30/2016
// 10/31/2016
// 11/30/2016
// 12/31/2016
// 1/31/2017
// 2/28/2017
// 3/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.

compare_to()

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

overridevirtualnoexcept

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

Parameters

value

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 >.

equals() [1/2]

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

overridevirtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Reimplemented from xtd::object.

equals() [2/2]

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

overridevirtualnoexcept

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

Parameters

other

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 >.

get_hash_code()

xtd::size xtd::date_time::get_hash_code ( ) const

overridevirtualnoexcept

Serves as a hash function for a particular type.

Returns

A hash code for the current object.

Reimplemented from xtd::object.

get_date_time_formats()

array< string > 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.

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.

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 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 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.

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/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.
  
  inline static const string date_patt = "M/d/yyyy hh:mm:ss tt";  
  static void display(const string& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = string::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("");
    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(date_patt);
    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(date_patt);
    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 string& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string(date_patt);
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// utc_now: ........... 10/24/2025 08:59:24 PM, kind = utc
// now: ............... 10/24/2025 10:59:24 PM, kind = local
//
// utc: ............... 10/24/2025 8:59:24 PM, kind = utc
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// local: ............. 10/24/2025 10:59:24 PM, kind = local
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// unspecified: ....... 10/24/2025 10:59:24 PM, kind = unspecified
//   to_local_time:     10/25/2025 00:59:24 AM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, 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.

to_long_date_string()

const xtd::string 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::string&) method.

to_long_time_string()

const xtd::string 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::string&) method.

to_short_date_string()

const xtd::string 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::string&) method.

to_short_time_string()

const xtd::string 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::string&) method.

to_string() [1/4]

xtd::string 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::string&) method.

Reimplemented from xtd::object.

to_string() [2/4]

xtd::string xtd::date_time::to_string

(

const string &

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_exception

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

Examples

The following example shows how to use xtd::date_time::to_string with different formats.

#include <xtd/xtd>
 
class program {
public:
  static auto main() {
    auto date_value = date_time {2008, 6, 15, 21, 15, 07};
    // Create an array of standard format strings.
    auto standard_fmts = {"d", "D", "f", "F", "g", "G", "m", "o", "R", "s", "t", "T", "u", "U", "y"};
    // Output date and time using each standard format string.
    for (auto standard_fmt : standard_fmts)
      console::write_line("{}: {}", standard_fmt, date_value.to_string(standard_fmt));
    console::write_line();
    
    // Create an array of some custom format strings.
    auto custom_fmts = {"h:mm:ss.ff t", "d MMM yyyy", "HH:mm:ss.f", "dd MMM HH:mm:ss", "\\Mon\\t\\h\\: M", "HH:mm:ss.ffffzzz"};
    // Output date and time using each custom format string.
    for (auto custom_fmt : custom_fmts)
      console::write_line("'{0}': {1}", custom_fmt, date_value.to_string(custom_fmt));
    console::write_line();
 
    // Create an array of some put time format strings.
    auto put_time_fmts = {"%I:%M:%S %p", "%e %b %G", "%H:%M:%S", "%e %b %H:%M:%S", "%%Month: %m", "%H:%M:%S%z"};
    // Output date and time using each custom format string.
    for (auto put_time_fmt : put_time_fmts)
      console::write_line("'{0}': {1}", put_time_fmt, date_value.to_string(put_time_fmt));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// d: 6/15/2008
// D: Sunday, June 15, 2008
// f: Sunday, June 15, 2008 21:15
// F: Sunday, June 15, 2008 21:15:07
// g: 6/15/2008 21:15
// G: 6/15/2008 21:15:07
// m: June 15
// o: 2008-06-15T21:15:07.0000000Z
// R: Sun, 15 Jun 2008 21:15:07 GMT
// s: 2008-06-15T21:15:07
// t: 21:15
// T: 21:15:07
// u: 2008-06-15 21:15:07Z
// U: Sunday, June 15, 2008 21:15:07
// y: June 2008
//
// 'h:mm:ss.ff t': 9:15:07.00 P
// 'd MMM yyyy': 15 Jun 2008
// 'HH:mm:ss.f': 21:15:07.0
// 'dd MMM HH:mm:ss': 15 Jun 21:15:07
// '\Mon\t\h\: M': Month: 6
// 'HH:mm:ss.ffffzzz': 21:15:07.0000+02:00
//
// '%I:%M:%S %p': 09:15:07 PM
// '%e %b %G': 15 Jun 2008
// '%H:%M:%S': 21:15:07
// '%e %b %H:%M:%S': 15 Jun 21:15:07
// '%%Month: %m': %Month: 06
// '%H:%M:%S%z': 21:15:07+0100

Remarks

The standard formatting codes for xtd::date_time::to_string (const xtd::string& format) are listed below:

Format	Description	Examples
"d"	Short date pattern.	2009-06-15T13:45:30 -> 6/15/2009 (en-US) 2009-06-15T13:45:30 -> 15/06/2009 (fr-FR) 2009-06-15T13:45:30 -> 2009/06/15 (ja-JP)
"D"	Long date pattern.	2009-06-15T13:45:30 -> Monday, June 15, 2009 (en-US) 2009-06-15T13:45:30 -> понедельник, 15 июня 2009 г. (ru-RU) 2009-06-15T13:45:30 -> Montag, 15. Juni 2009 (de-DE)
"f"	Full date/time pattern (short time).	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45 μμ (el-GR)
"F"	Full date/time pattern (long time).	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45:30 μμ (el-GR)
"g"	General date/time pattern (short time).	2009-06-15T13:45:30 -> 6/15/2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45 (zh-CN)
"G"	General date/time pattern (long time).	2009-06-15T13:45:30 -> 6/15/2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45:30 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45:30 (zh-CN)
"M", "m"	Month/day pattern.	2009-06-15T13:45:30 -> June 15 (en-US) 2009-06-15T13:45:30 -> 15. juni (da-DK) 2009-06-15T13:45:30 -> 15 Juni (id-ID)
"O", "o"	round-trip date/time pattern. ISO 8601	2009-06-15T13:45:30 (date_time_kind::local) -> 2009-06-15T13:45:30.0000000-07:00 2009-06-15T13:45:30 (date_time_kind::utc) -> 2009-06-15T13:45:30.0000000Z 2009-06-15T13:45:30 (date_time_kind::unspecified) -> 2009-06-15T13:45:30.0000000
"R", "r"	RFC1123 pattern.	2009-06-15T13:45:30 -> Mon, 15 Jun 2009 13:45:30 GMT
"s"	Sortable date/time pattern.	2009-06-15T13:45:30 (date_time_kind::local) -> 2009-06-15T13:45:30 2009-06-15T13:45:30 (date_time_kind::utc) -> 2009-06-15T13:45:30
"t"	Short time pattern.	2009-06-15T13:45:30 -> 1:45 PM (en-US) 2009-06-15T13:45:30 -> 13:45 (hr-HR) 2009-06-15T13:45:30 -> 01:45 م (ar-EG)
"T"	Long time pattern.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (hr-HR) 2009-06-15T13:45:30 -> 01:45:30 م (ar-EG)
"u"	Universal sortable date/time pattern.	2009-06-15T13:45:30 -> 2009-06-15 13:45:30Z
"U"	Universal full date/time pattern.	2009-06-15T13:45:30 -> Monday, June 15, 2009 8:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 20:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 8:45:30 μμ (el-GR)
"Y", "y"	Year month pattern.	2009-06-15T13:45:30 -> June 2009 (en-US) 2009-06-15T13:45:30 -> juni 2009 (da-DK) 2009-06-15T13:45:30 -> Juni 2009 (id-ID)
Any other single character	Unknown specifier.	Throws a run-time xtd::format_exception.

The custom formatting codes for xtd::date_time::to_string (const xtd::string& format) are listed below:

Format	Description	Examples
"d"	The day of the month, from 1 to 31.	2009-06-01T13:45:30 -> 1
"dd"	The day of the month, from 01 to 31.	2009-06-01T13:45:30 -> 01
"ddd"	The abbreviated name of the day of the week.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
"dddd"	The full name of the day of the week.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 ->понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
"f"	The tenths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 6 2009-06-15T13:45:30.05 -> 0
"ff"	The hundredths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 61 2009-06-15T13:45:30.0050000 -> 00
"fff"	The milliseconds in a date and time value.	6/15/2009 13:45:30.617 -> 617 6/15/2009 13:45:30.0005 -> 000
"ffff"	The ten thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175000 -> 6175 6/15/2009 13:45:30.000005 -> 0000
"fffff"	The hundred thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175400 -> 61754 6/15/2009 13:45:30.000005 -> 00000
"ffffff"	The millionths of a second in a date and time value.	2009-06-15T13:45:30.6175420 -> 617542 2009-06-15T13:45:30.0000005 -> 000000
"fffffff"	The ten millionths of a second in a date and time value.	2009-06-15T13:45:30.6175425 -> 6175425 2009-06-15T13:45:30.0001150 -> 0001150
"F"	If non-zero, the tenths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 6 2009-06-15T13:45:30.0500000 -> (no output)
"FF"	If non-zero, the hundredths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 61 2009-06-15T13:45:30.0050000 -> (no output)
"FFF"	If non-zero, the milliseconds in a date and time value.	2009-06-15T13:45:30.6170000 -> 617 2009-06-15T13:45:30.0005000 -> (no output)
"FFFF"	If non-zero, the ten thousandths of a second in a date and time value.	2009-06-15T13:45:30.5275000 -> 5275 2009-06-15T13:45:30.0000500 -> (no output)
"FFFFF"	If non-zero, the hundred thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175400 -> 61754 2009-06-15T13:45:30.0000050 -> (no output)
"FFFFFF"	If non-zero, the millionths of a second in a date and time value.	2009-06-15T13:45:30.6175420 -> 617542 2009-06-15T13:45:30.0000005 -> (no output)
"FFFFFFF"	If non-zero, the ten millionths of a second in a date and time value.	2009-06-15T13:45:30.6175425 -> 6175425 2009-06-15T13:45:30.0001150 -> 000115
"g", "gg"	The period or era.	2009-06-15T13:45:30.6170000 -> A.D.
"h"	The hour, using a 12-hour clock from 1 to 12.	2009-06-15T01:45:30 -> 1 2009-06-15T13:45:30 -> 1
"hh"	The hour, using a 12-hour clock from 01 to 12.	2009-06-15T01:45:30 -> 01 2009-06-15T13:45:30 -> 01
"H"	The hour, using a 24-hour clock from 0 to 23.	2009-06-15T01:45:30 -> 1 2009-06-15T13:45:30 -> 13
"HH"	The hour, using a 24-hour clock from 00 to 23.	2009-06-15T01:45:30 -> 01 2009-06-15T13:45:30 -> 13
"k"	Time zone information.	2009-06-15T13:45:30, Kind Unspecified -> 2009-06-15T13:45:30, Kind Utc -> Z 2009-06-15T13:45:30, Kind Local -> -07:00 (depends on local computer settings)
"m"	The minute, from 0 to 59.	2009-06-15T01:09:30 -> 9 2009-06-15T13:29:30 -> 29
"mm"	The minute, from 00 to 59.	2009-06-15T01:09:30 -> 09 2009-06-15T13:29:30 -> 29
"M"	The month, from 1 to 12.	2009-06-15T13:45:30 -> 6
"MM"	The month, from 01 to 12.	2009-06-15T13:45:30 -> 06
"MMM"	The abbreviated name of the month.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
"MMMM"	The full name of the month.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
"s"	The second, from 0 to 59.	2009-06-15T13:45:09 -> 9
"ss"	The second, from 00 to 59.	2009-06-15T13:45:09 -> 09
"t"	The first character of the AM/PM designator.	2009-06-15T13:45:30 -> P (en-US) 2009-06-15T13:45:30 -> 午 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
"tt"	The AM/PM designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
"y"	The year, from 0 to 99.	0001-01-01T00:00:00 -> 1 0900-01-01T00:00:00 -> 0 1900-01-01T00:00:00 -> 0 2009-06-15T13:45:30 -> 9 2019-06-15T13:45:30 -> 19
"yy"	The year, from 00 to 99.	0001-01-01T00:00:00 -> 01 0900-01-01T00:00:00 -> 00 1900-01-01T00:00:00 -> 00 2019-06-15T13:45:30 -> 19
"yyy"	The year, with a minimum of three digits.	0001-01-01T00:00:00 -> 001 0900-01-01T00:00:00 -> 000 1900-01-01T00:00:00 -> 900 2019-06-15T13:45:30 -> 019
"yyyy"	The year as a four-digit number.	0001-01-01T00:00:00 -> 0001 0900-01-01T00:00:00 -> 0900 1900-01-01T00:00:00 -> 1900 2019-06-15T13:45:30 -> 2019
"yyyyy"	The year as a five-digit number.	0001-01-01T00:00:00 -> 00001 2009-06-15T13:45:30 -> 02009
"z"	Hours offset from UTC, with no leading zeros.	2009-06-15T13:45:30-07:00 -> -7
"zz"	Hours offset from UTC, with a leading zero for a single-digit value.	2009-06-15T13:45:30-07:00 -> -07
"zzz"	Hours and minutes offset from UTC.	2009-06-15T13:45:30-07:00 -> -07:00
":"	The time separator.	2009-06-15T13:45:30 -> : (en-US) 2009-06-15T13:45:30 -> . (it-IT) 2009-06-15T13:45:30 -> : (ja-JP)
"/"	The date separator.	2009-06-15T13:45:30 -> / (en-US) 2009-06-15T13:45:30 -> - (ar-DZ) 2009-06-15T13:45:30 -> . (tr-TR)
"\"	The escape character.	2009-06-15T13:45:30 (h \h) -> 1 h
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr hh:mm t) -> arr 01:45 A

The put string formatting codes for xtd::date_time::to_string (const xtd::string& format) are listed below (See std::put_time for more information.) :

Format	Description	Examples
%a	The abbreviated weekday name.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
%A	The full weekday name.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 -> понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
%b	The abbreviated month name.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%B	The full month name.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
%c	The standard date and time string.	2009-06-15T13:45:30 -> Mon Jun 15 13:45:30 2009 (en-US) 2009-06-15T13:45:30 -> 月 6/15 13:45:30 2009 (ja-JP) 2009-06-15T13:45:30 -> lun. 15 juin 13:45:30 2009 (fr-FR)
%C	The first 2 digits of year as a decimal number (range [00,99]).	0001-01-01T00:00:00 -> 00 0900-01-01T00:00:00 -> 09 1900-01-01T00:00:00 -> 19 2019-06-15T13:45:30 -> 20
%d	The day of the month as a decimal number (range [01,31]).	2009-06-01T13:45:30 -> 01
%D	The equivalent of %m/%d/%y.	2009-06-01T13:45:30 -> 06/01/09
%e	The day of the month as a decimal number (range [1,31]).	2009-06-01T13:45:30 -> 1
%Ec	The alternative date and time string.	2009-06-01T13:45:30 -> Mon Jun 1 13:45:30 2009 (en-US) 2009-06-01T13:45:30 -> 月 6/ 1 13:45:30 2009 (jp-JA) 2009-06-01T13:45:30 -> lun. 1 juin 13:45:30 2009 (fr-FR)
%EC	The name of the base year (period) in the alternative representation.	2009-06-01T13:45:30 -> 20 (en-US) 2009-06-01T13:45:30 -> 20 (jp-JA) 2009-06-01T13:45:30 -> 20 (fr-FR)
%Ex	The alternative date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%EX	The alternative time representation.	2009-06-01T13:45:30 -> 1:45:30 PM (en-US) 2009-06-01T13:45:30 -> 13:45:30 (jp-JA) 2009-06-01T13:45:30 -> 13:45:30 (fr-FR)
%Ey	The year as offset from alternative calendar period %EC.	2009-06-01T13:45:30 -> 09 (en-US) 2009-06-01T13:45:30 -> 09 (jp-JA) 2009-06-01T13:45:30 -> 09 (fr-FR)
%EY	The year in the alternative representation.	2009-06-01T13:45:30 -> 2009 (en-US) 2009-06-01T13:45:30 -> 2009 (jp-JA) 2009-06-01T13:45:30 -> 2009 (fr-FR)
%F	The equivalent of %Y-%m-%d (the ISO 8601 date format).	2009-06-01T13:45:30 -> 2009-06-01
%g	The last 2 digits of ISO 8601 week-based year.	2009-06-01T13:45:30 -> 09
%G	The ISO 8601 week-based year.	2009-06-01T13:45:30 -> 2009
%h	The %b synonym.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%H	The hour as a decimal number, 24 hour clock (range [00-23]).	2009-06-01T13:45:30 -> 13
%I	The hour as a decimal number, 12 hour clock (range [01,12]).	2009-06-01T13:45:30 -> 01
%j	The day of the year as a decimal number (range [001,366]).	2009-06-01T13:45:30 -> 153
%m	The month as a decimal number (range [01,12]).	2009-06-01T13:45:30 -> 06
%M	The minute as a decimal number (range [00,59]).	2009-06-01T13:45:30 -> 30
%Od	The zero-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 01
%Oe	The one-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OH	The hour from 24-hour clock using the alternative numeric system.	2009-06-15T13:45:30 -> 13
%OI	The hour from 12-hour clock using the alternative numeric system	2009-06-15T13:45:30 -> 01
%Om	The month using the alternative numeric system.	2009-06-15T13:45:30 -> 06
%OM	The minute using the alternative numeric system.	2009-06-15T13:45:30 -> 45
%OS	The second using the alternative numeric system.	2009-06-15T13:45:30 -> 30
%Ou	The weekday, where Monday is 1, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OU	The week of the year, as by %U, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%OV	The week of the year, as by %V, using the alternative numeric system.	2009-06-01T13:45:30 -> 23
%Ow	The weekday, where Sunday is 0, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OW	The week of the year, as by %W, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%Oy	The last 2 digits of year using the alternative numeric system.	2009-06-01T13:45:30 -> 09
%p	The a.m. / p.m. designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
%r	The localized 12-hour clock time.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%R	The equivalent of %H:%M.	2009-06-15T13:45:30 -> 13:45
%S	The second as a decimal number (range [00,60]).	2009-06-15T13:45:30 -> 30
%T	The equivalent of %H:%M:%S (the ISO 8601 time format).	2009-06-15T13:45:30 -> 13:45:30
%u	The weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).	2009-06-01T13:45:30 -> 1
%U	The week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%V	The ISO 8601 week of the year (range [01,53]).	2009-06-01T13:45:30 -> 23
%w	The weekday as a decimal number, where Sunday is 0 (range [0-6]).	2009-06-01T13:45:30 -> 1
%W	The week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%x	The localized date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%X	The localized time representation.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%y	The last 2 digits of year as a decimal number (range [00,99]).	2009-06-01T13:45:30 -> 09
%Y	The year as a decimal number.	2009-06-01T13:45:30 -> 2009
%z	The offset from UTC in the ISO 8601 format.	2009-06-15T13:45:30+01:00 -> +0100
%Z	The time zone name or abbreviation.	2009-06-15T13:45:30+01:00 -> Romance Standard Time
%%	The literal %. The full conversion specification must be %%.	2009-06-15T13:45:30 (%H %%) -> 13 %
%n	The newline character.	2009-06-15T13:45:30 (%H%nM) -> 13 45
%t	The horizontal tab character.	2009-06-15T13:45:30 (%H%tM) -> 13 45
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr %H:%MT) -> arr 13:45T

to_string() [3/4]

xtd::string xtd::date_time::to_string ( const string & format, const xtd::globalization::culture_info & culture ) const

overridevirtual

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.
culture	An xtd::globalization::culture_info object that contains culture information.

Returns

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

Exceptions

xtd::format_exception

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

Examples

The following example shows how to use xtd::date_time::to_string with different formats.

#include <xtd/xtd>
 
class program {
public:
  static auto main() {
    auto date_value = date_time {2008, 6, 15, 21, 15, 07};
    // Create an array of standard format strings.
    auto standard_fmts = {"d", "D", "f", "F", "g", "G", "m", "o", "R", "s", "t", "T", "u", "U", "y"};
    // Output date and time using each standard format string.
    for (auto standard_fmt : standard_fmts)
      console::write_line("{}: {}", standard_fmt, date_value.to_string(standard_fmt));
    console::write_line();
    
    // Create an array of some custom format strings.
    auto custom_fmts = {"h:mm:ss.ff t", "d MMM yyyy", "HH:mm:ss.f", "dd MMM HH:mm:ss", "\\Mon\\t\\h\\: M", "HH:mm:ss.ffffzzz"};
    // Output date and time using each custom format string.
    for (auto custom_fmt : custom_fmts)
      console::write_line("'{0}': {1}", custom_fmt, date_value.to_string(custom_fmt));
    console::write_line();
 
    // Create an array of some put time format strings.
    auto put_time_fmts = {"%I:%M:%S %p", "%e %b %G", "%H:%M:%S", "%e %b %H:%M:%S", "%%Month: %m", "%H:%M:%S%z"};
    // Output date and time using each custom format string.
    for (auto put_time_fmt : put_time_fmts)
      console::write_line("'{0}': {1}", put_time_fmt, date_value.to_string(put_time_fmt));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// d: 6/15/2008
// D: Sunday, June 15, 2008
// f: Sunday, June 15, 2008 21:15
// F: Sunday, June 15, 2008 21:15:07
// g: 6/15/2008 21:15
// G: 6/15/2008 21:15:07
// m: June 15
// o: 2008-06-15T21:15:07.0000000Z
// R: Sun, 15 Jun 2008 21:15:07 GMT
// s: 2008-06-15T21:15:07
// t: 21:15
// T: 21:15:07
// u: 2008-06-15 21:15:07Z
// U: Sunday, June 15, 2008 21:15:07
// y: June 2008
//
// 'h:mm:ss.ff t': 9:15:07.00 P
// 'd MMM yyyy': 15 Jun 2008
// 'HH:mm:ss.f': 21:15:07.0
// 'dd MMM HH:mm:ss': 15 Jun 21:15:07
// '\Mon\t\h\: M': Month: 6
// 'HH:mm:ss.ffffzzz': 21:15:07.0000+02:00
//
// '%I:%M:%S %p': 09:15:07 PM
// '%e %b %G': 15 Jun 2008
// '%H:%M:%S': 21:15:07
// '%e %b %H:%M:%S': 15 Jun 21:15:07
// '%%Month: %m': %Month: 06
// '%H:%M:%S%z': 21:15:07+0100

Remarks

The standard formatting codes for xtd::date_time::to_string (const xtd::string& format, const xtd::globalization::culture_info& culture) are listed below:

Format	Description	Examples
"d"	Short date pattern.	2009-06-15T13:45:30 -> 6/15/2009 (en-US) 2009-06-15T13:45:30 -> 15/06/2009 (fr-FR) 2009-06-15T13:45:30 -> 2009/06/15 (ja-JP)
"D"	Long date pattern.	2009-06-15T13:45:30 -> Monday, June 15, 2009 (en-US) 2009-06-15T13:45:30 -> понедельник, 15 июня 2009 г. (ru-RU) 2009-06-15T13:45:30 -> Montag, 15. Juni 2009 (de-DE)
"f"	Full date/time pattern (short time).	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45 μμ (el-GR)
"F"	Full date/time pattern (long time).	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45:30 μμ (el-GR)
"g"	General date/time pattern (short time).	2009-06-15T13:45:30 -> 6/15/2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45 (zh-CN)
"G"	General date/time pattern (long time).	2009-06-15T13:45:30 -> 6/15/2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45:30 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45:30 (zh-CN)
"M", "m"	Month/day pattern.	2009-06-15T13:45:30 -> June 15 (en-US) 2009-06-15T13:45:30 -> 15. juni (da-DK) 2009-06-15T13:45:30 -> 15 Juni (id-ID)
"O", "o"	round-trip date/time pattern. ISO 8601	2009-06-15T13:45:30 (date_time_kind::local) -> 2009-06-15T13:45:30.0000000-07:00 2009-06-15T13:45:30 (date_time_kind::utc) -> 2009-06-15T13:45:30.0000000Z 2009-06-15T13:45:30 (date_time_kind::unspecified) -> 2009-06-15T13:45:30.0000000
"R", "r"	RFC1123 pattern.	2009-06-15T13:45:30 -> Mon, 15 Jun 2009 13:45:30 GMT
"s"	Sortable date/time pattern.	2009-06-15T13:45:30 (date_time_kind::local) -> 2009-06-15T13:45:30 2009-06-15T13:45:30 (date_time_kind::utc) -> 2009-06-15T13:45:30
"t"	Short time pattern.	2009-06-15T13:45:30 -> 1:45 PM (en-US) 2009-06-15T13:45:30 -> 13:45 (hr-HR) 2009-06-15T13:45:30 -> 01:45 م (ar-EG)
"T"	Long time pattern.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (hr-HR) 2009-06-15T13:45:30 -> 01:45:30 م (ar-EG)
"u"	Universal sortable date/time pattern.	2009-06-15T13:45:30 -> 2009-06-15 13:45:30Z
"U"	Universal full date/time pattern.	2009-06-15T13:45:30 -> Monday, June 15, 2009 8:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 20:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 8:45:30 μμ (el-GR)
"Y", "y"	Year month pattern.	2009-06-15T13:45:30 -> June 2009 (en-US) 2009-06-15T13:45:30 -> juni 2009 (da-DK) 2009-06-15T13:45:30 -> Juni 2009 (id-ID)
Any other single character	Unknown specifier.	Throws a run-time xtd::format_exception.

The custom formatting codes for xtd::date_time::to_string (const xtd::string& format, const xtd::globalization::culture_info& culture) are listed below:

Format	Description	Examples
"d"	The day of the month, from 1 to 31.	2009-06-01T13:45:30 -> 1
"dd"	The day of the month, from 01 to 31.	2009-06-01T13:45:30 -> 01
"ddd"	The abbreviated name of the day of the week.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
"dddd"	The full name of the day of the week.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 ->понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
"f"	The tenths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 6 2009-06-15T13:45:30.05 -> 0
"ff"	The hundredths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 61 2009-06-15T13:45:30.0050000 -> 00
"fff"	The milliseconds in a date and time value.	6/15/2009 13:45:30.617 -> 617 6/15/2009 13:45:30.0005 -> 000
"ffff"	The ten thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175000 -> 6175 6/15/2009 13:45:30.000005 -> 0000
"fffff"	The hundred thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175400 -> 61754 6/15/2009 13:45:30.000005 -> 00000
"ffffff"	The millionths of a second in a date and time value.	2009-06-15T13:45:30.6175420 -> 617542 2009-06-15T13:45:30.0000005 -> 000000
"fffffff"	The ten millionths of a second in a date and time value.	2009-06-15T13:45:30.6175425 -> 6175425 2009-06-15T13:45:30.0001150 -> 0001150
"F"	If non-zero, the tenths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 6 2009-06-15T13:45:30.0500000 -> (no output)
"FF"	If non-zero, the hundredths of a second in a date and time value.	2009-06-15T13:45:30.6170000 -> 61 2009-06-15T13:45:30.0050000 -> (no output)
"FFF"	If non-zero, the milliseconds in a date and time value.	2009-06-15T13:45:30.6170000 -> 617 2009-06-15T13:45:30.0005000 -> (no output)
"FFFF"	If non-zero, the ten thousandths of a second in a date and time value.	2009-06-15T13:45:30.5275000 -> 5275 2009-06-15T13:45:30.0000500 -> (no output)
"FFFFF"	If non-zero, the hundred thousandths of a second in a date and time value.	2009-06-15T13:45:30.6175400 -> 61754 2009-06-15T13:45:30.0000050 -> (no output)
"FFFFFF"	If non-zero, the millionths of a second in a date and time value.	2009-06-15T13:45:30.6175420 -> 617542 2009-06-15T13:45:30.0000005 -> (no output)
"FFFFFFF"	If non-zero, the ten millionths of a second in a date and time value.	2009-06-15T13:45:30.6175425 -> 6175425 2009-06-15T13:45:30.0001150 -> 000115
"g", "gg"	The period or era.	2009-06-15T13:45:30.6170000 -> A.D.
"h"	The hour, using a 12-hour clock from 1 to 12.	2009-06-15T01:45:30 -> 1 2009-06-15T13:45:30 -> 1
"hh"	The hour, using a 12-hour clock from 01 to 12.	2009-06-15T01:45:30 -> 01 2009-06-15T13:45:30 -> 01
"H"	The hour, using a 24-hour clock from 0 to 23.	2009-06-15T01:45:30 -> 1 2009-06-15T13:45:30 -> 13
"HH"	The hour, using a 24-hour clock from 00 to 23.	2009-06-15T01:45:30 -> 01 2009-06-15T13:45:30 -> 13
"k"	Time zone information.	2009-06-15T13:45:30, Kind Unspecified -> 2009-06-15T13:45:30, Kind Utc -> Z 2009-06-15T13:45:30, Kind Local -> -07:00 (depends on local computer settings)
"m"	The minute, from 0 to 59.	2009-06-15T01:09:30 -> 9 2009-06-15T13:29:30 -> 29
"mm"	The minute, from 00 to 59.	2009-06-15T01:09:30 -> 09 2009-06-15T13:29:30 -> 29
"M"	The month, from 1 to 12.	2009-06-15T13:45:30 -> 6
"MM"	The month, from 01 to 12.	2009-06-15T13:45:30 -> 06
"MMM"	The abbreviated name of the month.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
"MMMM"	The full name of the month.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
"s"	The second, from 0 to 59.	2009-06-15T13:45:09 -> 9
"ss"	The second, from 00 to 59.	2009-06-15T13:45:09 -> 09
"t"	The first character of the AM/PM designator.	2009-06-15T13:45:30 -> P (en-US) 2009-06-15T13:45:30 -> 午 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
"tt"	The AM/PM designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
"y"	The year, from 0 to 99.	0001-01-01T00:00:00 -> 1 0900-01-01T00:00:00 -> 0 1900-01-01T00:00:00 -> 0 2009-06-15T13:45:30 -> 9 2019-06-15T13:45:30 -> 19
"yy"	The year, from 00 to 99.	0001-01-01T00:00:00 -> 01 0900-01-01T00:00:00 -> 00 1900-01-01T00:00:00 -> 00 2019-06-15T13:45:30 -> 19
"yyy"	The year, with a minimum of three digits.	0001-01-01T00:00:00 -> 001 0900-01-01T00:00:00 -> 000 1900-01-01T00:00:00 -> 900 2019-06-15T13:45:30 -> 019
"yyyy"	The year as a four-digit number.	0001-01-01T00:00:00 -> 0001 0900-01-01T00:00:00 -> 0900 1900-01-01T00:00:00 -> 1900 2019-06-15T13:45:30 -> 2019
"yyyyy"	The year as a five-digit number.	0001-01-01T00:00:00 -> 00001 2009-06-15T13:45:30 -> 02009
"z"	Hours offset from UTC, with no leading zeros.	2009-06-15T13:45:30-07:00 -> -7
"zz"	Hours offset from UTC, with a leading zero for a single-digit value.	2009-06-15T13:45:30-07:00 -> -07
"zzz"	Hours and minutes offset from UTC.	2009-06-15T13:45:30-07:00 -> -07:00
":"	The time separator.	2009-06-15T13:45:30 -> : (en-US) 2009-06-15T13:45:30 -> . (it-IT) 2009-06-15T13:45:30 -> : (ja-JP)
"/"	The date separator.	2009-06-15T13:45:30 -> / (en-US) 2009-06-15T13:45:30 -> - (ar-DZ) 2009-06-15T13:45:30 -> . (tr-TR)
"\"	The escape character.	2009-06-15T13:45:30 (h \h) -> 1 h
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr hh:mm t) -> arr 01:45 A

The put string formatting codes for xtd::date_time::to_string (const xtd::string& format, const xtd::globalization::culture_info& culture) are listed below (See std::put_time for more information.) :

Format	Description	Examples
%a	The abbreviated weekday name.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
%A	The full weekday name.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 -> понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
%b	The abbreviated month name.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%B	The full month name.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
%c	The standard date and time string.	2009-06-15T13:45:30 -> Mon Jun 15 13:45:30 2009 (en-US) 2009-06-15T13:45:30 -> 月 6/15 13:45:30 2009 (ja-JP) 2009-06-15T13:45:30 -> lun. 15 juin 13:45:30 2009 (fr-FR)
%C	The first 2 digits of year as a decimal number (range [00,99]).	0001-01-01T00:00:00 -> 00 0900-01-01T00:00:00 -> 09 1900-01-01T00:00:00 -> 19 2019-06-15T13:45:30 -> 20
%d	The day of the month as a decimal number (range [01,31]).	2009-06-01T13:45:30 -> 01
%D	The equivalent of %m/%d/%y.	2009-06-01T13:45:30 -> 06/01/09
%e	The day of the month as a decimal number (range [1,31]).	2009-06-01T13:45:30 -> 1
%Ec	The alternative date and time string.	2009-06-01T13:45:30 -> Mon Jun 1 13:45:30 2009 (en-US) 2009-06-01T13:45:30 -> 月 6/ 1 13:45:30 2009 (jp-JA) 2009-06-01T13:45:30 -> lun. 1 juin 13:45:30 2009 (fr-FR)
%EC	The name of the base year (period) in the alternative representation.	2009-06-01T13:45:30 -> 20 (en-US) 2009-06-01T13:45:30 -> 20 (jp-JA) 2009-06-01T13:45:30 -> 20 (fr-FR)
%Ex	The alternative date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%EX	The alternative time representation.	2009-06-01T13:45:30 -> 1:45:30 PM (en-US) 2009-06-01T13:45:30 -> 13:45:30 (jp-JA) 2009-06-01T13:45:30 -> 13:45:30 (fr-FR)
%Ey	The year as offset from alternative calendar period %EC.	2009-06-01T13:45:30 -> 09 (en-US) 2009-06-01T13:45:30 -> 09 (jp-JA) 2009-06-01T13:45:30 -> 09 (fr-FR)
%EY	The year in the alternative representation.	2009-06-01T13:45:30 -> 2009 (en-US) 2009-06-01T13:45:30 -> 2009 (jp-JA) 2009-06-01T13:45:30 -> 2009 (fr-FR)
%F	The equivalent of %Y-%m-%d (the ISO 8601 date format).	2009-06-01T13:45:30 -> 2009-06-01
%g	The last 2 digits of ISO 8601 week-based year.	2009-06-01T13:45:30 -> 09
%G	The ISO 8601 week-based year.	2009-06-01T13:45:30 -> 2009
%h	The %b synonym.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%H	The hour as a decimal number, 24 hour clock (range [00-23]).	2009-06-01T13:45:30 -> 13
%I	The hour as a decimal number, 12 hour clock (range [01,12]).	2009-06-01T13:45:30 -> 01
%j	The day of the year as a decimal number (range [001,366]).	2009-06-01T13:45:30 -> 153
%m	The month as a decimal number (range [01,12]).	2009-06-01T13:45:30 -> 06
%M	The minute as a decimal number (range [00,59]).	2009-06-01T13:45:30 -> 30
%Od	The zero-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 01
%Oe	The one-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OH	The hour from 24-hour clock using the alternative numeric system.	2009-06-15T13:45:30 -> 13
%OI	The hour from 12-hour clock using the alternative numeric system	2009-06-15T13:45:30 -> 01
%Om	The month using the alternative numeric system.	2009-06-15T13:45:30 -> 06
%OM	The minute using the alternative numeric system.	2009-06-15T13:45:30 -> 45
%OS	The second using the alternative numeric system.	2009-06-15T13:45:30 -> 30
%Ou	The weekday, where Monday is 1, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OU	The week of the year, as by %U, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%OV	The week of the year, as by %V, using the alternative numeric system.	2009-06-01T13:45:30 -> 23
%Ow	The weekday, where Sunday is 0, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OW	The week of the year, as by %W, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%Oy	The last 2 digits of year using the alternative numeric system.	2009-06-01T13:45:30 -> 09
%p	The a.m. / p.m. designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
%r	The localized 12-hour clock time.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%R	The equivalent of %H:%M.	2009-06-15T13:45:30 -> 13:45
%S	The second as a decimal number (range [00,60]).	2009-06-15T13:45:30 -> 30
%T	The equivalent of %H:%M:%S (the ISO 8601 time format).	2009-06-15T13:45:30 -> 13:45:30
%u	The weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).	2009-06-01T13:45:30 -> 1
%U	The week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%V	The ISO 8601 week of the year (range [01,53]).	2009-06-01T13:45:30 -> 23
%w	The weekday as a decimal number, where Sunday is 0 (range [0-6]).	2009-06-01T13:45:30 -> 1
%W	The week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%x	The localized date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%X	The localized time representation.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%y	The last 2 digits of year as a decimal number (range [00,99]).	2009-06-01T13:45:30 -> 09
%Y	The year as a decimal number.	2009-06-01T13:45:30 -> 2009
%z	The offset from UTC in the ISO 8601 format.	2009-06-15T13:45:30+01:00 -> +0100
%Z	The time zone name or abbreviation.	2009-06-15T13:45:30+01:00 -> Romance Standard Time
%%	The literal %. The full conversion specification must be %%.	2009-06-15T13:45:30 (%H %%) -> 13 %
%n	The newline character.	2009-06-15T13:45:30 (%H%nM) -> 13 45
%t	The horizontal tab character.	2009-06-15T13:45:30 (%H%tM) -> 13 45
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr %H:%MT) -> arr 13:45T

Implements xtd::iformatable.

to_string() [4/4]

xtd::string xtd::date_time::to_string

(

const xtd::globalization::culture_info &

culture

)

const

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

Parameters

culture

An xtd::globalization::culture_info object that contains culture information.

Returns

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

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/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.
  
  inline static const string date_patt = "M/d/yyyy hh:mm:ss tt";  
  static void display(const string& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = string::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("");
    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(date_patt);
    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(date_patt);
    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 string& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string(date_patt);
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// utc_now: ........... 10/24/2025 08:59:24 PM, kind = utc
// now: ............... 10/24/2025 10:59:24 PM, kind = local
//
// utc: ............... 10/24/2025 8:59:24 PM, kind = utc
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// local: ............. 10/24/2025 10:59:24 PM, kind = local
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// unspecified: ....... 10/24/2025 10:59:24 PM, kind = unspecified
//   to_local_time:     10/25/2025 00:59:24 AM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, 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.

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/xtd>
 
using namespace xtd::globalization;
 
class program {
public:
  static auto main() {
    auto local_date = date_time::now();
    auto utc_date = date_time::utc_now();
    auto culture_names = array {"en-US", "en-GB", "fr-FR", "de-DE", "ru-RU"};
    
    for (auto culture_name : culture_names) {
      auto culture = culture_info {culture_name};
      console::write_line("{}:", culture.native_name());
      console::write_line("   Local date and time: {}, {}", local_date.to_string(culture), local_date.kind());
      console::write_line("   UTC date and time: {}, {}\n", utc_date.to_string(culture), utc_date.kind());
    }
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// English (United States):
//    Local date and time: 10/23/2025 0:59:10 AM, local
//    UTC date and time: 10/22/2025 10:59:10 PM, utc
//
// English (United Kingdom):
//    Local date and time: 23/10/2025 00:59:10, local
//    UTC date and time: 22/10/2025 22:59:10, utc
//
// français (France):
//    Local date and time: 23/10/2025 00:59:10, local
//    UTC date and time: 22/10/2025 22:59:10, utc
//
// Deutsch (Deutschland):
//    Local date and time: 23.10.2025 00:59:10, local
//    UTC date and time: 22.10.2025 22:59:10, utc
//
// русский (Россия):
//    Local date and time: 23.10.2025 00:59:10, local
//    UTC date and time: 22.10.2025 22:59:10, 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/xtd>
 
using namespace xtd::globalization;
 
class program {
public:
  static auto main() {
    auto local_date = date_time::now();
    auto culture_names = array {"en-US", "en-GB", "fr-FR", "de-DE", "ru-RU"};
    
    for (auto culture_name : culture_names) {
      auto culture = culture_info {culture_name};
      console::write_line("{}: {}", culture_name, local_date.to_string(culture));
    }
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// en-US: 10/23/2025 1:02:39 AM
// en-GB: 23/10/2025 01:02:39
// fr-FR: 23/10/2025 01:02:39
// de-DE: 23.10.2025 01:02:39
// ru-RU: 23.10.2025 01:02:39

Examples

date_time_add.cpp, date_time_add_days.cpp, and sprintf_date_time.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::string&) method uses the g format specifier to include the time component, which is zero.

#include <xtd/xtd>
 
class program {
public:
  static auto main() {
    auto dates = array {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 produce 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.

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)).

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 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/xtd>
 
class program {
public:
  static auto main() {
    auto years = array<uint32> {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 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 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/xtd>
 
class program {
public:
  static auto main() {
    auto years = array<uint32> {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 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.

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_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_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_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.

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.

parse() [1/2]

static date_time xtd::date_time::parse ( const xtd::string & 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.

parse() [2/2]

static date_time xtd::date_time::parse ( const xtd::string & s, const xtd::globalization::culture_info & culture )

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.

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/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.
  
  inline static const string date_patt = "M/d/yyyy hh:mm:ss tt";  
  static void display(const string& title, const date_time& input_dt) {
    auto disp_dt = input_dt;
    auto dt_string = string::empty_string;
    
    // display the original date_time.
    
    dt_string = disp_dt.to_string("");
    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(date_patt);
    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(date_patt);
    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 string& title, const date_time& input_dt) {
    auto dt_string = input_dt.to_string(date_patt);
    console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
  }
};
 
startup_(program::main);
 
// This code can produce the following output :
//
// utc_now: ........... 10/24/2025 08:59:24 PM, kind = utc
// now: ............... 10/24/2025 10:59:24 PM, kind = local
//
// utc: ............... 10/24/2025 8:59:24 PM, kind = utc
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// local: ............. 10/24/2025 10:59:24 PM, kind = local
//   to_local_time:     10/24/2025 10:59:24 PM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc
//
// unspecified: ....... 10/24/2025 10:59:24 PM, kind = unspecified
//   to_local_time:     10/25/2025 00:59:24 AM, kind = local
//   to_universal_time: 10/24/2025 08:59:24 PM, kind = utc

sprintf() [1/2]

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

static

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

Parameters

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

Returns

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

Examples

The following example shows how to use xtd::date_time::sprintf with different formats.

#include <xtd/xtd>
 
class program {
public:
  static auto main() {
    auto date_value = date_time {2008, 6, 15, 21, 15, 07};
 
    // Create an array of standard format strings.
    auto standard_fmts = {"%a", "%A", "%b", "%B", "%c", "%C", "%d", "%D", "%e", "%Ec", "%EC", "%Ex", "%EX", "%Ey",
      "%EY", "%F", "%g", "%G", "%h", "%H", "%I", "%j", "%m", "%M", "%p", "%r", "%R", "%S", "%T", "%u", "%U", "%V",
      "%w", "%W", "%x", "%X", "%y", "%Y", "%z", "%Z", "%Od", "%Oe", "%OH", "%OI", "%Om", "%OM", "%OS", "%Ou",
      "%OU", "%OV", "%Ow", "%OW", "%Oy"};
    // Output date and time using each standard format string.
    for (auto standard_fmt : standard_fmts)
      console::write_line("{}: {}", standard_fmt, date_time::sprintf(standard_fmt, date_value));
    console::write_line();
 
    // Create an array of some custom format strings.
    auto custom_fmts = {"%I:%M:%S %p", "%e %b %G", "%H:%M:%S", "%e %b %H:%M:%S", "%%Month: %m", "%H:%M:%S%z"};
    // Output date and time using each custom format string.
    for (auto custom_fmt : custom_fmts)
      console::write_line("'{0}': {1}", custom_fmt, date_time::sprintf(custom_fmt, date_value));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// %a: Sun
// %A: Sunday
// %b: Jun
// %B: June
// %c: Sun Jun 15 21:15:07 2008
// %C: 20
// %d: 15
// %D: 06/15/08
// %e: 15
// %Ec: Sun Jun 15 21:15:07 2008
// %EC: 20
// %Ex: 06/15/08
// %EX: 21:15:07
// %Ey: 08
// %EY: 2008
// %F: 2008-06-15
// %g: 08
// %G: 2008
// %h: Jun
// %H: 21
// %I: 09
// %j: 168
// %m: 06
// %M: 15
// %p: PM
// %r: 09:15:07 PM
// %R: 21:15
// %S: 07
// %T: 21:15:07
// %u: 7
// %U: 24
// %V: 24
// %w: 0
// %W: 24
// %x: 06/15/08
// %X: 21:15:07
// %y: 08
// %Y: 2008
// %z: +0100
// %Z: CET
// %Od: 15
// %Oe: 15
// %OH: 21
// %OI: 09
// %Om: 06
// %OM: 15
// %OS: 07
// %Ou: 7
// %OU: 24
// %OV: 24
// %Ow: 0
// %OW: 24
// %Oy: 08
//
// '%I:%M:%S %p': 09:15:07 PM
// '%e %b %G': 15 Jun 2008
// '%H:%M:%S': 21:15:07
// '%e %b %H:%M:%S': 15 Jun 21:15:07
// '%%Month: %m': %Month: 06
// '%H:%M:%S%z': 21:15:07+0100

Remarks

The put string formatting codes for xtd::date_time::sprintf (const xtd::string& format, const xtd::date_time& value) are listed below (See std::put_time for more information.) :

Format	Description	Examples
%a	The abbreviated weekday name.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
%A	The full weekday name.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 -> понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
%b	The abbreviated month name.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%B	The full month name.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
%c	The standard date and time string.	2009-06-15T13:45:30 -> Mon Jun 15 13:45:30 2009 (en-US) 2009-06-15T13:45:30 -> 月 6/15 13:45:30 2009 (ja-JP) 2009-06-15T13:45:30 -> lun. 15 juin 13:45:30 2009 (fr-FR)
%C	The first 2 digits of year as a decimal number (range [00,99]).	0001-01-01T00:00:00 -> 00 0900-01-01T00:00:00 -> 09 1900-01-01T00:00:00 -> 19 2019-06-15T13:45:30 -> 20
%d	The day of the month as a decimal number (range [01,31]).	2009-06-01T13:45:30 -> 01
%D	The equivalent of %m/%d/%y.	2009-06-01T13:45:30 -> 06/01/09
%e	The day of the month as a decimal number (range [1,31]).	2009-06-01T13:45:30 -> 1
%Ec	The alternative date and time string.	2009-06-01T13:45:30 -> Mon Jun 1 13:45:30 2009 (en-US) 2009-06-01T13:45:30 -> 月 6/ 1 13:45:30 2009 (jp-JA) 2009-06-01T13:45:30 -> lun. 1 juin 13:45:30 2009 (fr-FR)
%EC	The name of the base year (period) in the alternative representation.	2009-06-01T13:45:30 -> 20 (en-US) 2009-06-01T13:45:30 -> 20 (jp-JA) 2009-06-01T13:45:30 -> 20 (fr-FR)
%Ex	The alternative date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%EX	The alternative time representation.	2009-06-01T13:45:30 -> 1:45:30 PM (en-US) 2009-06-01T13:45:30 -> 13:45:30 (jp-JA) 2009-06-01T13:45:30 -> 13:45:30 (fr-FR)
%Ey	The year as offset from alternative calendar period %EC.	2009-06-01T13:45:30 -> 09 (en-US) 2009-06-01T13:45:30 -> 09 (jp-JA) 2009-06-01T13:45:30 -> 09 (fr-FR)
%EY	The year in the alternative representation.	2009-06-01T13:45:30 -> 2009 (en-US) 2009-06-01T13:45:30 -> 2009 (jp-JA) 2009-06-01T13:45:30 -> 2009 (fr-FR)
%F	The equivalent of %Y-%m-%d (the ISO 8601 date format).	2009-06-01T13:45:30 -> 2009-06-01
%g	The last 2 digits of ISO 8601 week-based year.	2009-06-01T13:45:30 -> 09
%G	The ISO 8601 week-based year.	2009-06-01T13:45:30 -> 2009
%h	The %b synonym.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%H	The hour as a decimal number, 24 hour clock (range [00-23]).	2009-06-01T13:45:30 -> 13
%I	The hour as a decimal number, 12 hour clock (range [01,12]).	2009-06-01T13:45:30 -> 01
%j	The day of the year as a decimal number (range [001,366]).	2009-06-01T13:45:30 -> 153
%m	The month as a decimal number (range [01,12]).	2009-06-01T13:45:30 -> 06
%M	The minute as a decimal number (range [00,59]).	2009-06-01T13:45:30 -> 30
%Od	The zero-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 01
%Oe	The one-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OH	The hour from 24-hour clock using the alternative numeric system.	2009-06-15T13:45:30 -> 13
%OI	The hour from 12-hour clock using the alternative numeric system	2009-06-15T13:45:30 -> 01
%Om	The month using the alternative numeric system.	2009-06-15T13:45:30 -> 06
%OM	The minute using the alternative numeric system.	2009-06-15T13:45:30 -> 45
%OS	The second using the alternative numeric system.	2009-06-15T13:45:30 -> 30
%Ou	The weekday, where Monday is 1, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OU	The week of the year, as by %U, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%OV	The week of the year, as by %V, using the alternative numeric system.	2009-06-01T13:45:30 -> 23
%Ow	The weekday, where Sunday is 0, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OW	The week of the year, as by %W, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%Oy	The last 2 digits of year using the alternative numeric system.	2009-06-01T13:45:30 -> 09
%p	The a.m. / p.m. designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
%r	The localized 12-hour clock time.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%R	The equivalent of %H:%M.	2009-06-15T13:45:30 -> 13:45
%S	The second as a decimal number (range [00,60]).	2009-06-15T13:45:30 -> 30
%T	The equivalent of %H:%M:%S (the ISO 8601 time format).	2009-06-15T13:45:30 -> 13:45:30
%u	The weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).	2009-06-01T13:45:30 -> 1
%U	The week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%V	The ISO 8601 week of the year (range [01,53]).	2009-06-01T13:45:30 -> 23
%w	The weekday as a decimal number, where Sunday is 0 (range [0-6]).	2009-06-01T13:45:30 -> 1
%W	The week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%x	The localized date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%X	The localized time representation.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%y	The last 2 digits of year as a decimal number (range [00,99]).	2009-06-01T13:45:30 -> 09
%Y	The year as a decimal number.	2009-06-01T13:45:30 -> 2009
%z	The offset from UTC in the ISO 8601 format.	2009-06-15T13:45:30+01:00 -> +0100
%Z	The time zone name or abbreviation.	2009-06-15T13:45:30+01:00 -> Romance Standard Time
%%	The literal %. The full conversion specification must be %%.	2009-06-15T13:45:30 (%H %%) -> 13 %
%n	The newline character.	2009-06-15T13:45:30 (%H%nM) -> 13 45
%t	The horizontal tab character.	2009-06-15T13:45:30 (%H%tM) -> 13 45
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr %H:%MT) -> arr 13:45T

sprintf() [2/2]

static xtd::string xtd::date_time::sprintf ( const string & format, const date_time & value, const xtd::globalization::culture_info & culture )

static

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

Parameters

format	Format-control String.
value	The xtd::date_time object to format.
culture	An xtd::globalization::culture_info object that contains culture information.

Returns

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

Examples

The following example shows how to use xtd::date_time::sprintf with different formats.

#include <xtd/xtd>
 
class program {
public:
  static auto main() {
    auto date_value = date_time {2008, 6, 15, 21, 15, 07};
 
    // Create an array of standard format strings.
    auto standard_fmts = {"%a", "%A", "%b", "%B", "%c", "%C", "%d", "%D", "%e", "%Ec", "%EC", "%Ex", "%EX", "%Ey",
      "%EY", "%F", "%g", "%G", "%h", "%H", "%I", "%j", "%m", "%M", "%p", "%r", "%R", "%S", "%T", "%u", "%U", "%V",
      "%w", "%W", "%x", "%X", "%y", "%Y", "%z", "%Z", "%Od", "%Oe", "%OH", "%OI", "%Om", "%OM", "%OS", "%Ou",
      "%OU", "%OV", "%Ow", "%OW", "%Oy"};
    // Output date and time using each standard format string.
    for (auto standard_fmt : standard_fmts)
      console::write_line("{}: {}", standard_fmt, date_time::sprintf(standard_fmt, date_value));
    console::write_line();
 
    // Create an array of some custom format strings.
    auto custom_fmts = {"%I:%M:%S %p", "%e %b %G", "%H:%M:%S", "%e %b %H:%M:%S", "%%Month: %m", "%H:%M:%S%z"};
    // Output date and time using each custom format string.
    for (auto custom_fmt : custom_fmts)
      console::write_line("'{0}': {1}", custom_fmt, date_time::sprintf(custom_fmt, date_value));
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// %a: Sun
// %A: Sunday
// %b: Jun
// %B: June
// %c: Sun Jun 15 21:15:07 2008
// %C: 20
// %d: 15
// %D: 06/15/08
// %e: 15
// %Ec: Sun Jun 15 21:15:07 2008
// %EC: 20
// %Ex: 06/15/08
// %EX: 21:15:07
// %Ey: 08
// %EY: 2008
// %F: 2008-06-15
// %g: 08
// %G: 2008
// %h: Jun
// %H: 21
// %I: 09
// %j: 168
// %m: 06
// %M: 15
// %p: PM
// %r: 09:15:07 PM
// %R: 21:15
// %S: 07
// %T: 21:15:07
// %u: 7
// %U: 24
// %V: 24
// %w: 0
// %W: 24
// %x: 06/15/08
// %X: 21:15:07
// %y: 08
// %Y: 2008
// %z: +0100
// %Z: CET
// %Od: 15
// %Oe: 15
// %OH: 21
// %OI: 09
// %Om: 06
// %OM: 15
// %OS: 07
// %Ou: 7
// %OU: 24
// %OV: 24
// %Ow: 0
// %OW: 24
// %Oy: 08
//
// '%I:%M:%S %p': 09:15:07 PM
// '%e %b %G': 15 Jun 2008
// '%H:%M:%S': 21:15:07
// '%e %b %H:%M:%S': 15 Jun 21:15:07
// '%%Month: %m': %Month: 06
// '%H:%M:%S%z': 21:15:07+0100

Remarks

The put string formatting codes for xtd::date_time::sprintf (const xtd::string& format, const xtd::date_time& value, const xtd::globalization::culture_info& culture) are listed below (See std::put_time for more information.) :

Format	Description	Examples
%a	The abbreviated weekday name.	2009-06-15T13:45:30 -> Mon (en-US) 2009-06-15T13:45:30 -> Пн (ru-RU) 2009-06-15T13:45:30 -> lun. (fr-FR)
%A	The full weekday name.	2009-06-15T13:45:30 -> Monday (en-US) 2009-06-15T13:45:30 -> понедельник (ru-RU) 2009-06-15T13:45:30 -> lundi (fr-FR)
%b	The abbreviated month name.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%B	The full month name.	2009-06-15T13:45:30 -> June (en-US) 2009-06-15T13:45:30 -> juni (da-DK) 2009-06-15T13:45:30 -> uJuni (zu-ZA)
%c	The standard date and time string.	2009-06-15T13:45:30 -> Mon Jun 15 13:45:30 2009 (en-US) 2009-06-15T13:45:30 -> 月 6/15 13:45:30 2009 (ja-JP) 2009-06-15T13:45:30 -> lun. 15 juin 13:45:30 2009 (fr-FR)
%C	The first 2 digits of year as a decimal number (range [00,99]).	0001-01-01T00:00:00 -> 00 0900-01-01T00:00:00 -> 09 1900-01-01T00:00:00 -> 19 2019-06-15T13:45:30 -> 20
%d	The day of the month as a decimal number (range [01,31]).	2009-06-01T13:45:30 -> 01
%D	The equivalent of %m/%d/%y.	2009-06-01T13:45:30 -> 06/01/09
%e	The day of the month as a decimal number (range [1,31]).	2009-06-01T13:45:30 -> 1
%Ec	The alternative date and time string.	2009-06-01T13:45:30 -> Mon Jun 1 13:45:30 2009 (en-US) 2009-06-01T13:45:30 -> 月 6/ 1 13:45:30 2009 (jp-JA) 2009-06-01T13:45:30 -> lun. 1 juin 13:45:30 2009 (fr-FR)
%EC	The name of the base year (period) in the alternative representation.	2009-06-01T13:45:30 -> 20 (en-US) 2009-06-01T13:45:30 -> 20 (jp-JA) 2009-06-01T13:45:30 -> 20 (fr-FR)
%Ex	The alternative date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%EX	The alternative time representation.	2009-06-01T13:45:30 -> 1:45:30 PM (en-US) 2009-06-01T13:45:30 -> 13:45:30 (jp-JA) 2009-06-01T13:45:30 -> 13:45:30 (fr-FR)
%Ey	The year as offset from alternative calendar period %EC.	2009-06-01T13:45:30 -> 09 (en-US) 2009-06-01T13:45:30 -> 09 (jp-JA) 2009-06-01T13:45:30 -> 09 (fr-FR)
%EY	The year in the alternative representation.	2009-06-01T13:45:30 -> 2009 (en-US) 2009-06-01T13:45:30 -> 2009 (jp-JA) 2009-06-01T13:45:30 -> 2009 (fr-FR)
%F	The equivalent of %Y-%m-%d (the ISO 8601 date format).	2009-06-01T13:45:30 -> 2009-06-01
%g	The last 2 digits of ISO 8601 week-based year.	2009-06-01T13:45:30 -> 09
%G	The ISO 8601 week-based year.	2009-06-01T13:45:30 -> 2009
%h	The %b synonym.	2009-06-15T13:45:30 -> Jun (en-US) 2009-06-15T13:45:30 -> juin (fr-FR) 2009-06-15T13:45:30 -> Jun (zu-ZA)
%H	The hour as a decimal number, 24 hour clock (range [00-23]).	2009-06-01T13:45:30 -> 13
%I	The hour as a decimal number, 12 hour clock (range [01,12]).	2009-06-01T13:45:30 -> 01
%j	The day of the year as a decimal number (range [001,366]).	2009-06-01T13:45:30 -> 153
%m	The month as a decimal number (range [01,12]).	2009-06-01T13:45:30 -> 06
%M	The minute as a decimal number (range [00,59]).	2009-06-01T13:45:30 -> 30
%Od	The zero-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 01
%Oe	The one-based day of the month using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OH	The hour from 24-hour clock using the alternative numeric system.	2009-06-15T13:45:30 -> 13
%OI	The hour from 12-hour clock using the alternative numeric system	2009-06-15T13:45:30 -> 01
%Om	The month using the alternative numeric system.	2009-06-15T13:45:30 -> 06
%OM	The minute using the alternative numeric system.	2009-06-15T13:45:30 -> 45
%OS	The second using the alternative numeric system.	2009-06-15T13:45:30 -> 30
%Ou	The weekday, where Monday is 1, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OU	The week of the year, as by %U, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%OV	The week of the year, as by %V, using the alternative numeric system.	2009-06-01T13:45:30 -> 23
%Ow	The weekday, where Sunday is 0, using the alternative numeric system.	2009-06-01T13:45:30 -> 1
%OW	The week of the year, as by %W, using the alternative numeric system.	2009-06-01T13:45:30 -> 22
%Oy	The last 2 digits of year using the alternative numeric system.	2009-06-01T13:45:30 -> 09
%p	The a.m. / p.m. designator.	2009-06-15T13:45:30 -> PM (en-US) 2009-06-15T13:45:30 -> 午後 (ja-JP) 2009-06-15T13:45:30 -> (fr-FR)
%r	The localized 12-hour clock time.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%R	The equivalent of %H:%M.	2009-06-15T13:45:30 -> 13:45
%S	The second as a decimal number (range [00,60]).	2009-06-15T13:45:30 -> 30
%T	The equivalent of %H:%M:%S (the ISO 8601 time format).	2009-06-15T13:45:30 -> 13:45:30
%u	The weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).	2009-06-01T13:45:30 -> 1
%U	The week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%V	The ISO 8601 week of the year (range [01,53]).	2009-06-01T13:45:30 -> 23
%w	The weekday as a decimal number, where Sunday is 0 (range [0-6]).	2009-06-01T13:45:30 -> 1
%W	The week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).	2009-06-01T13:45:30 -> 22
%x	The localized date representation.	2009-06-01T13:45:30 -> 6/1/2009 (en-US) 2009-06-01T13:45:30 -> 2009/06/01 (jp-JA) 2009-06-01T13:45:30 -> 01/06/2009 (fr-FR)
%X	The localized time representation.	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (ja-JP) 2009-06-15T13:45:30 -> 13:45:30 (fr-FR)
%y	The last 2 digits of year as a decimal number (range [00,99]).	2009-06-01T13:45:30 -> 09
%Y	The year as a decimal number.	2009-06-01T13:45:30 -> 2009
%z	The offset from UTC in the ISO 8601 format.	2009-06-15T13:45:30+01:00 -> +0100
%Z	The time zone name or abbreviation.	2009-06-15T13:45:30+01:00 -> Romance Standard Time
%%	The literal %. The full conversion specification must be %%.	2009-06-15T13:45:30 (%H %%) -> 13 %
%n	The newline character.	2009-06-15T13:45:30 (%H%nM) -> 13 45
%t	The horizontal tab character.	2009-06-15T13:45:30 (%H%tM) -> 13 45
Any other character	The character is copied to the result string unchanged.	2009-06-15T01:45:30 (arr %H:%MT) -> arr 13:45T

try_parse() [1/2]

static bool xtd::date_time::try_parse ( const string & 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.

try_parse() [2/2]

static bool xtd::date_time::try_parse ( const string & s, date_time & result, const xtd::globalization::culture_info & culture )

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.

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/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 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/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 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/xtd>
 
class program {
public:
  static auto main() {
    // Define an uninitialized date.
    auto date1 = date_time {};
    console::write(date1);
    if (date1.equals(date_time::min_value))
      console::write_line("  (equals date_time::min_value)");
  }
};
 
startup_(program::main);
 
// This code produces the following output :
//
// 1/1/0001 0:00:00 AM  (equals date_time::min_value)

---

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

• xtd.core/include/xtd/date_time.hpp