xtd 0.2.0
Loading...
Searching...
No Matches
xtd::date_time Class Reference
Inheritance diagram for xtd::date_time:
xtd::object xtd::icomparable< date_time > xtd::iequatable< date_time > xtd::iformatable xtd::interface xtd::comparison_operators< type_t, comparable_t > xtd::interface xtd::equality_operators< type_t, equatable_t > xtd::interface

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
Represents an instant in time, typically expressed as a date and time of day.
Definition date_time.h:85
Defines a generalized comparison method that a value type or class implements to create a type-specif...
Definition icomparable.h:21
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:22
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
#define core_export_
Define shared library export.
Definition core_export.h:13
Inheritance
xtd::objectxtd::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:
Remarks
For more information about xtd::date_time, see Date and time.
Examples
The following example demonstrates how to compare roughly equivalent xtd::date_time values, accepting a small margin of difference when declaring them equal.
#include <xtd/console>
#include <xtd/convert>
#include <xtd/date_time>
#include <xtd/math>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto window = 10;
auto freq = 60 * 60 * 2; // 2 hours;
auto d1 = date_time::now();
auto d2 = d1.add_seconds(2 * window);
auto d3 = d1.add_seconds(-2 * window);
auto d4 = d1.add_seconds(window / 2);
auto d5 = d1.add_seconds(-window / 2);
auto d6 = (d1.add_hours(2)).add_seconds(2 * window);
auto d7 = (d1.add_hours(2)).add_seconds(-2 * window);
auto d8 = (d1.add_hours(2)).add_seconds(window / 2);
auto d9 = (d1.add_hours(2)).add_seconds(-window / 2);
console::write_line("d1 ({0}) ~= d1 ({1}): {2}", d1, d1, roughly_equals(d1, d1, window, freq));
console::write_line("d1 ({0}) ~= d2 ({1}): {2}", d1, d2, roughly_equals(d1, d2, window, freq));
console::write_line("d1 ({0}) ~= d3 ({1}): {2}", d1, d3, roughly_equals(d1, d3, window, freq));
console::write_line("d1 ({0}) ~= d4 ({1}): {2}", d1, d4, roughly_equals(d1, d4, window, freq));
console::write_line("d1 ({0}) ~= d5 ({1}): {2}", d1, d5, roughly_equals(d1, d5, window, freq));
console::write_line("d1 ({0}) ~= d6 ({1}): {2}", d1, d6, roughly_equals(d1, d6, window, freq));
console::write_line("d1 ({0}) ~= d7 ({1}): {2}", d1, d7, roughly_equals(d1, d7, window, freq));
console::write_line("d1 ({0}) ~= d8 ({1}): {2}", d1, d8, roughly_equals(d1, d8, window, freq));
console::write_line("d1 ({0}) ~= d9 ({1}): {2}", d1, d9, roughly_equals(d1, d9, window, freq));
}
private:
static bool roughly_equals(const date_time& time, const date_time& time_with_window, int window_in_seconds, int frequency_in_seconds) {
auto delta = convert::to_int32((time_with_window - time).total_seconds_duration().count()) % frequency_in_seconds;
delta = delta > window_in_seconds ? frequency_in_seconds - delta : delta;
return math::abs(delta) < window_in_seconds;
}
};
startup_(program::main);
// This code produces the following output :
//
// d1 (Thu Dec 30 16:18:10 2021) ~= d1 (Thu Dec 30 16:18:10 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d2 (Thu Dec 30 16:18:30 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d3 (Thu Dec 30 16:17:50 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d4 (Thu Dec 30 16:18:15 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d5 (Thu Dec 30 16:18:05 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d6 (Thu Dec 30 18:18:30 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d7 (Thu Dec 30 18:17:50 2021): false
// d1 (Thu Dec 30 16:18:10 2021) ~= d8 (Thu Dec 30 18:18:15 2021): true
// d1 (Thu Dec 30 16:18:10 2021) ~= d9 (Thu Dec 30 18:18:05 2021): true
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
@ d6
The 6 key.
@ d8
The 8 key.
@ d9
The 9 key.
@ d1
The 1 key.
@ d4
The 4 key.
@ d2
The 2 key.
@ d5
The 5 key.
@ d3
The 3 key.
@ d7
The 7 key.
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
Examples
any.cpp, any_info.cpp, date_time.cpp, date_time_add_hours.cpp, date_time_add_milliseconds.cpp, date_time_add_minutes.cpp, date_time_add_months.cpp, date_time_add_seconds.cpp, date_time_add_years.cpp, date_time_date.cpp, date_time_day_of_week.cpp, date_time_day_of_year.cpp, date_time_max_value.cpp, date_time_min_value.cpp, date_time_specify_kind.cpp, date_time_sprintf.cpp, date_time_subtract.cpp, date_time_ticks.cpp, date_time_ticks2.cpp, date_time_to_string_format.cpp, date_time_today.cpp, format_date_time.cpp, graph_control.cpp, and time_span.cpp.

Public Fields

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

Public Constructors

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

Public Properties

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

Public Methods

date_time add (const xtd::time_span &value) const
 Returns a new xtd::date_time that adds the value of the specified xtd::time_span to the value of this instance.
 
date_time add_days (double value) const
 Returns a new xtd::date_time that adds the specified number of days to the value of this instance.
 
date_time add_hours (double value) const
 Returns a new xtd::date_time that adds the specified number of hours to the value of this instance.
 
date_time add_milliseconds (double value) const
 Returns a new xtd::date_time that adds the specified number of milliseconds to the value of this instance.
 
date_time add_minutes (double value) const
 Returns a new xtd::date_time that adds the specified number of minutes to the value of this instance.
 
date_time add_months (int32 months) const
 Returns a new xtd::date_time that adds the specified number of months to the value of this instance.
 
date_time add_seconds (double value) const
 Returns a new xtd::date_time that adds the specified number of seconds to the value of this instance.
 
date_time add_ticks (int64 value) const
 Returns a new xtd::date_time that adds the specified number of ticks to the value of this instance.
 
date_time add_years (int32 value) const
 Returns a new xtd::date_time that adds the specified number of years to the value of this instance.
 
int32 compare_to (const date_time &value) const noexcept override
 Compares the current instance with another object of the same type.
 
bool equals (const date_time &) const noexcept override
 Indicates whether the current object is equal to another object of the same type.
 
std::vector< stringget_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 std::locale &loc) 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.
 
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).
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
template<typename object_a_t , typename 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.
 

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

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
- Public Member Functions inherited from xtd::icomparable< date_time >
- Public Member Functions inherited from xtd::iequatable< date_time >
- Public Member Functions inherited from xtd::iformatable
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename 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<typename object_a_t , typename 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/10]

xtd::date_time::date_time ( )
default

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

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

◆ date_time() [2/10]

xtd::date_time::date_time ( int64  ticks)
explicit

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

Parameters
ticksA 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_exceptionticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
Remarks
The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.
Examples
The following example demonstrates one of the xtd::date_time constructors.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Instead of using the implicit, default "G" date and time format string, we
// use a custom format string that aligns the results and inserts leading zeroes.
auto format = "{0}) The {1} date and time is {2:k}/{2:i}/{2:L} {2:t}";
// Create a DateTime for the maximum date and time using ticks.
auto dt1 = date_time {date_time::max_value.ticks()};
// Create a DateTime for the minimum date and time using ticks.
auto dt2 = date_time {date_time::min_value.ticks()};
// Create a custom DateTime for 1/5/1971 at 21:10:30 using ticks
auto ticks = date_time {1971, 1, 5, 21, 10, 30}.ticks();
auto dt3 = date_time {ticks};
console::write_line(format, 1, "maximum", dt1);
console::write_line(format, 2, "minimum", dt2);
console::write_line(format, 3, "custom ", dt3);
console::write_line("\nThe custom date and time is created from {0} ticks.", ticks);
}
};
startup_(program::main);
// This code 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.
int64 ticks() const noexcept
Gets the number of ticks that represent the date and time of this instance.
std::chrono::duration< int64, tick > ticks
Represents a tick duration.
Definition ticks.h:21

◆ date_time() [3/10]

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

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

Parameters
ticksA 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_exceptionticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
Remarks
The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.
Examples
The following example demonstrates one of the xtd::date_time constructors.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Instead of using the implicit, default "G" date and time format string, we
// use a custom format string that aligns the results and inserts leading zeroes.
auto format = "{0}) The {1} date and time is {2:k}/{2:i}/{2:L} {2:t}";
// Create a DateTime for the maximum date and time using ticks.
auto dt1 = date_time {date_time::max_value.ticks()};
// Create a DateTime for the minimum date and time using ticks.
auto dt2 = date_time {date_time::min_value.ticks()};
// Create a custom DateTime for 1/5/1971 at 21:10:30 using ticks
auto ticks = date_time {1971, 1, 5, 21, 10, 30}.ticks();
auto dt3 = date_time {ticks};
console::write_line(format, 1, "maximum", dt1);
console::write_line(format, 2, "minimum", dt2);
console::write_line(format, 3, "custom ", dt3);
console::write_line("\nThe custom date and time is created from {0} ticks.", ticks);
}
};
startup_(program::main);
// This code produces the following output :
//
// 1) The maximum date and time is 12/31/9999 23:59:59
// 2) The minimum date and time is 01/01/0001 00:00:00
// 3) The custom date and time is 01/05/1971 21:10:30
//
// The custom date and time is created from 621675546300000000 ticks.

◆ date_time() [4/10]

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

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

Parameters
ticksA 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.
kindOne of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.
Exceptions
xtd::argument_out_of_range_exceptionticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

◆ date_time() [5/10]

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

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

Parameters
ticksA 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.
kindOne of the enumeration values that indicates whether ticks specifies a local time, Coordinated Universal Time (UTC), or neither.
Exceptions
xtd::argument_out_of_range_exceptionticks is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.

◆ date_time() [6/10]

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

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

Parameters
yearThe year (1 through 9999).
monthThe month (1 through 12).
dayThe day (1 through the number of days in month).
Exceptions
xtd::argument_out_of_range_exceptionyear is less than 1 or greater than 9999.
-or-
month is less than 1 or greater than 12.
-or-
day is less than 1 or greater than the number of days in month.
Examples
The following example uses the date_time(uint32, uint32, uint32) constructor to instantiate a xtd::date_time value. The example also illustrates that this overload creates a xtd::date_time value whose time component equals midnight (or 0:00).
date_time date1(2010, 8, 18);
console::write_line(date1.to_string());
// The example displays the following output:
// 8/18/2010 12:00:00 AM
Remarks
This constructor interprets year, month, and day as a year, month, and day in the Gregorian calendar.

◆ date_time() [7/10]

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

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

Parameters
yearThe year (1 through 9999).
monthThe month (1 through 12).
dayThe day (1 through the number of days in month).
hourThe hours (0 through 23).
minuteThe minutes (0 through 59).
secondThe seconds (0 through 59).
Exceptions
xtd::argument_out_of_range_exceptionyear is less than 1 or greater than 9999.
-or-
month is less than 1 or greater than 12.
-or-
day is less than 1 or greater than the number of days in month.
-or-
hour is less than 0 or greater than 23.
-or-
minute is less than 0 or greater than 59.
-or-
second is less than 0 or greater than 59.
Remarks
The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.
This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

◆ date_time() [8/10]

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

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

Parameters
yearThe year (1 through 9999).
monthThe month (1 through 12).
dayThe day (1 through the number of days in month).
hourThe hours (0 through 23).
minuteThe minutes (0 through 59).
secondThe seconds (0 through 59).
kindOne 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_exceptionyear 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
@ local
The time represented is local time.
Remarks
The xtd::date_time::kind property is initialized to xtd::date_time_kind::unspecified.
This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

◆ date_time() [9/10]

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

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

Parameters
yearThe year (1 through 9999).
monthThe month (1 through 12).
dayThe day (1 through the number of days in month).
hourThe hours (0 through 23).
minuteThe minutes (0 through 59).
secondThe seconds (0 through 59).
millisecondThe milliseconds (0 through 999).
Exceptions
xtd::argument_out_of_range_exceptionyear is less than 1 or greater than 9999.
-or-
month is less than 1 or greater than 12.
-or-
day is less than 1 or greater than the number of days in month.
-or-
hour is less than 0 or greater than 23.
-or-
minute is less than 0 or greater than 59
-or-
second is less than 0 or greater than 59
-or-
millisecond is less than 0 or greater than 999.
Remarks
This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

◆ date_time() [10/10]

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

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

Parameters
yearThe year (1 through 9999).
monthThe month (1 through 12).
dayThe day (1 through the number of days in month).
hourThe hours (0 through 23).
minuteThe minutes (0 through 59).
secondThe seconds (0 through 59).
millisecondThe milliseconds (0 through 999).
kindOne 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_exceptionyear is less than 1 or greater than 9999.
-or-
month is less than 1 or greater than 12.
-or-
day is less than 1 or greater than the number of days in month.
-or-
hour is less than 0 or greater than 23.
-or-
minute is less than 0 or greater than 59
-or-
second is less than 0 or greater than 59
-or-
millisecond is less than 0 or greater than 999.
Remarks
This constructor interpretsyear, month, and day as a year, month, and day in the Gregorian calendar.

Member Function Documentation

◆ date()

date_time xtd::date_time::date ( ) const
noexcept

Gets the date component of this instance.

Returns
A new object with the same date as this instance, and the time value set to 12:00:00 midnight (00:00:00).
Examples
The following example uses the xtd::date_time::date property to extract the date component of a xtd::date_time value with its time component set to zero (or 0:00:00, or midnight). It also illustrates that, depending on the format string used when displaying the xtd::date_time value, the time component can continue to appear in formatted output.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto date1 = date_time {2008, 6, 1, 7, 47, 0};
console::write_line(date1.to_string());
// Get date-only portion of date, without its time.
auto date_only = date1.date();
// Display date using short date string.
console::write_line(date_only.to_string("d"));
// Display date using 24-hour clock.
console::write_line(date_only.to_string("g"));
console::write_line(date_only.to_string("u"));
}
};
startup_(program::main);
// This code produces the following output :
// Sun Jun 1 07:47:00 2008
// 06/01/2008
// Sun Jun 1 00:00:00 2008
// 2008-06-01 00:00:00
Remarks
The value of the xtd::date_time::kind property of the returned xtd::date_time value is the same as that of the current instance.
Because the xtd::date_time type represents both dates and times in a single type, it is important to avoid misinterpreting a date returned by the xtd::date property as a date and time.

◆ day()

uint32 xtd::date_time::day ( ) const
noexcept

Gets the day of the month represented by this instance.

Returns
The day component, expressed as a value between 1 and 31.
Examples
The following example demonstrates the xtd::date_time::day property.
xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
// month gets 1 (January).
uint23_t month = moment.month();
// day gets 13.
uint23_t day = moment.day();
// hour gets 3.
uint23_t hour = momentour();
// minute gets 57.
uint23_t minute = moment.minute();
// second gets 32.
uint23_t second = moment.second();
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();
uint32 minute() const noexcept
Gets the minute component of the date represented by this instance.
uint32 day() const noexcept
Gets the day of the month represented by this instance.
uint32 month() const noexcept
Gets the month component of the date represented by this instance.
uint32 year() const noexcept
Gets the year component of the date represented by this instance.
uint32 millisecond() const noexcept
Gets the milliseconds component of the date represented by this instance.
uint32 second() const noexcept
Gets the seconds component of the date represented by this instance.
uint32 hour() const noexcept
Gets the hour component of the date represented by this instance.
uint32_t uint32
Represents a 32-bit unsigned integer.
Definition uint32.h:23
Remarks
The xtd::date_time::day property always returns the day of the month in the Gregorian calendar.

◆ day_of_week()

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

Gets the day of the week represented by this instance.

Returns
An enumerated constant that indicates the day of the week of this xtd::date_time value.
Examples
The following example demonstrates the xtd::date_time::day_of_week property and the xtd::day_of_week enumeration.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Create a DateTime for the first of May, 2003.
auto dt = date_time {2003, 5, 1};
console::write_line("Is Thursday the day of the week for {0:d}?: {1}", dt, dt.day_of_week() == day_of_week::thursday);
console::write_line("The day of the week for {0:d} is {1}.", dt, dt.day_of_week());
}
};
startup_(program::main);
// This code produces the following output :
//
// Is Thursday the day of the week for 05/01/2003?: true
// The day of the week for 05/01/2003 is thursday.
Remarks
The value of the constants in the xtd::day_of_week enumeration ranges from xtd::day_of_week::sunday to xtd::day_of_week::saturday. If cast to an integer, its value ranges from zero (which indicates xtd::day_of_week::sunday) to six (which indicates xtd::day_of_week::saturday).
The xtd::date_time::day_of_week property returns an enumerated constant; it does not reflect a system's regional and language settings. To retrieve a string representing a localized weekday name for a particular date, call one of the overloads of the xtd::date_time::to_string method that includes a format parameter and pass it either the "h" or "H" format strings.

◆ day_of_year()

uint32 xtd::date_time::day_of_year ( ) const
noexcept

Gets the day of the year represented by this instance.

Returns
The day of the year, expressed as a value between 1 and 366.
Examples
The following example displays the day of the year of December 31 for the years 2010-2020 in the Gregorian calendar. Note that the example shows that December 31 is the 366th day of the year in leap years.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto dec31 = date_time {2010, 12, 31};
for (auto ctr = 0u; ctr <= 10u; ctr++) {
auto date_to_display = dec31.add_years(ctr);
console::write_line("{0:d}: day {1} of {2} {3}", date_to_display, date_to_display.day_of_year(), date_to_display.year(), date_time::is_leap_year(date_to_display.year()) ? "(Leap Year)" : "");
}
}
};
startup_(program::main);
// This code 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)
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.
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/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Get the date and time for the current moment, adjusted
// to the local time zone.
auto save_now = date_time::now();
// Get the date and time for the current moment expressed
// as coordinated universal time (UTC).
auto save_utc_now = date_time::utc_now();
auto my_dt = date_time {};
// display the value and kind property of the current moment
// expressed as UTC and local time.
display_now("utc_now: ...........", save_utc_now);
display_now("now: ...............", save_now);
console::write_line();
// Change the kind property of the current moment to
// date_time_kind::utc and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
display("utc: ...............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::local and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::local);
display("local: .............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::unspecified and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
display("unspecified: .......", my_dt);
}
// display the value and kind() property of a date_time structure, the
// date_time structure converted to local time, and the date_time
// structure converted to universal time.
static void display(const 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("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
// Convert input_dt to local time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
// If input_dt.kind() is date_time_kind::local, the conversion is not performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was universal time.
disp_dt = input_dt.to_local_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_local_time: {0}, kind = {1}", dt_string, disp_dt.kind());
// Convert input_dt to universal time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
// If input_dt.kind() is date_time_kind::local, the conversion is performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was local time.
disp_dt = input_dt.to_universal_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
console::write_line();
}
// display the value and kind property for date_time::now() and date_time::utc_now().
static void display_now(const string& title, const date_time& input_dt) {
auto dt_string = input_dt.to_string("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
}
};
startup_(program::main);
// This code can produce the following output :
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
// to_local_time: 2021-12-31 19:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
date_time to_universal_time() const
Converts the value of the current xtd::date_time object to Coordinated Universal Time (UTC).
date_time to_local_time() const
Converts the value of the current xtd::date_time object to local time.
date_time_kind kind() const noexcept
Gets a value that indicates whether the time represented by this instance is based on local time,...
Remarks
You can explicitly set the xtd::date_time::xtd::date_time::kind property of a new xtd::date_time value to a particular xtd::date_time_kind value by calling the xtd::date_time::specify_kind method.
The xtd::date_time::kind property allows a xtd::date_time value to clearly reflect either Coordinated Universal Time (UTC) or the local time. In contrast, the xtd::date_time_offset structure can unambiguously reflect any time in any time zone as a single point in time.
Examples
date_time_specify_kind.cpp.

◆ millisecond()

uint32 xtd::date_time::millisecond ( ) const
noexcept

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

Returns
The milliseconds component, expressed as a value between 0 and 999.
Examples
The following example demonstrates the xtd::date_time::millisecond property.
xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
// month gets 1 (January).
uint23_t month = moment.month();
// day gets 13.
uint23_t day = moment.day();
// hour gets 3.
uint23_t hour = moment.hour();
// minute gets 57.
uint23_t minute = moment.minute();
// second gets 32.
uint23_t second = moment.second();
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();
Remarks
You can display the string representation of the xtd::date::time::millisecond property by using the "b" or "B" format specifier. For example, the following code displays a string that contains the number of milliseconds in a date and time to the console.
date_time date1(2008, 1, 1, 0, 30, 45, 125);
console::write_line("milliseconds: {0:b}", date1); // displays milliseconds: 125
You can also display the millisecond component together with the other components of a date and time value by using the "s" standard format specifier. For example:
date_time date2(2008, 1, 1, 0, 30, 45, 125);
Console.WriteLine("Date: {0:s}", date2);
// Displays the following output to the console:
// Date: 2008-01-01T00:30:45.1250000

◆ minute()

uint32 xtd::date_time::minute ( ) const
noexcept

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

Returns
The minute component, expressed as a value between 0 and 59.
Examples
The following example demonstrates the xtd::date_time::minute property.
xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
// month gets 1 (January).
uint23_t month = moment.month();
// day gets 13.
uint23_t day = moment.day();
// hour gets 3.
uint23_t hour = moment.hour();
// minute gets 57.
uint23_t minute = moment.minute();
// second gets 32.
uint23_t second = moment.second();
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

◆ month()

uint32 xtd::date_time::month ( ) const
noexcept

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

Returns
The month component, expressed as a value between 1 and 12.
Examples
The following example demonstrates the xtd::date_time::month property.
xtd::date_time moment(1999, 1, 13, 3, 57, 32, 11);
// year gets 1999.
uint32 year = moment.year();
// month gets 1 (January).
uint23_t month = moment.month();
// day gets 13.
uint23_t day = moment.day();
// hour gets 3.
uint23_t hour = moment.hour();
// minute gets 57.
uint23_t minute = moment.minute();
// second gets 32.
uint23_t second = moment.second();
// millisecond gets 11.
uint23_t millisecond = moment.millisecond();

◆ 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/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace std::chrono;
using namespace xtd;
class program {
public:
static auto main() {
auto century_begin = date_time {2001, 1, 1};
auto current_date = date_time::now();
auto elapsed_ticks = current_date.ticks() - century_begin.ticks();
auto elapsed_span = time_span {elapsed_ticks};
console::write_line("Elapsed from the beginning of the century to {:f}:", current_date);
console::write_line(" {:N0} nanoseconds", elapsed_ticks * 100);
console::write_line(" {:N0} ticks", elapsed_ticks);
console::write_line(" {:N2} seconds", elapsed_span.total_seconds());
console::write_line(" {:N2} minutes", elapsed_span.total_minutes());
console::write_line(" {:N0} days, {} hours, {} minutes, {} seconds", elapsed_span.days(), elapsed_span.hours(),
elapsed_span.minutes(), elapsed_span.seconds());
}
};
startup_(program::main);
// This code can 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
Represents a time interval.
Definition time_span.h:29
Examples
date_time_ticks.cpp.

◆ ticks_duration()

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

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

Returns
The number of ticks that represent the date and time of this instance. The value is between xtd::date_time::min_value.ticks and xtd::date_time::max_value.ticks.
Examples
The following example uses the xtd::date_time::ticks property to display the number of ticks that have elapsed since the beginning of the century.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace std::chrono;
using namespace xtd;
class program {
public:
static auto main() {
auto century_begin = date_time {2001, 1, 1};
auto current_date = date_time::now();
auto elapsed_ticks = current_date.ticks() - century_begin.ticks();
auto elapsed_span = time_span {elapsed_ticks};
console::write_line("Elapsed from the beginning of the century to {:f}:", current_date);
console::write_line(" {:N0} nanoseconds", elapsed_ticks * 100);
console::write_line(" {:N0} ticks", elapsed_ticks);
console::write_line(" {:N2} seconds", elapsed_span.total_seconds());
console::write_line(" {:N2} minutes", elapsed_span.total_minutes());
console::write_line(" {:N0} days, {} hours, {} minutes, {} seconds", elapsed_span.days(), elapsed_span.hours(),
elapsed_span.minutes(), elapsed_span.seconds());
}
};
startup_(program::main);
// This code can 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/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Get the current date.
auto this_day = date_time::today();
// Display the date in the default (general) format.
console::write_line(this_day.to_string());
console::write_line();
// Display the date in a variety of formats.
console::write_line(this_day.to_string("d"));
console::write_line(this_day.to_string("D"));
console::write_line(this_day.to_string("g"));
}
};
startup_(program::main);
// This code can 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
valueA 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_exceptionThe 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 :
//
// Wed Jan 12 14:06:34 2022
// Thu Feb 17 14:06:34 2022
Remarks
You can use the xtd::date_time::add method to add more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. This method's behavior is identical to that of the addition operator. The xtd::date_time::addxtd::date_time structure also supports specialized addition methods (such as xtd::date_time::add_days, xtd::date_time::add_hours, and xtd::date_time::add_minutes) for each time interval.
The xtd::date_time::add method takes into account leap years and the number of days in a month when performing date arithmetic.
This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation. The xtd::date_time::kind property of the new xtd::date_time instance is the same as that of the current instance.

◆ add_days()

date_time xtd::date_time::add_days ( double  value) const

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

Parameters
valueA 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_exceptionThe 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 :
//
// Wed Jan 12 14:06:34 2022
// Thu Feb 17 14:06:34 2022
Remarks
This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.
The fractional part of value is the fractional part of a day. For example, 4.5 is equivalent to 4 days, 12 hours, 0 minutes, 0 seconds, 0 milliseconds, and 0 ticks.
The xtd::date_time::add_days method takes into account leap years and the number of days in a month when performing date arithmetic.

◆ add_hours()

date_time xtd::date_time::add_hours ( double  value) const

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

Parameters
valueA 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_exceptionThe resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
Examples
The following example uses the xtd::date_time::add_hours method to add a number of whole and fractional values to a date and time. It also illustrates the loss of precision caused by passing the method a value that includes a fractional component.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::collections::generic;
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:u} + {1} hour(s) = {2:u}", date_value, hour, date_value.add_hours(hour));
}
};
startup_(program::main);
// This code produces the following output :
//
// 2009-03-01 12:00:00 + 0.08333 hour(s) = 2009-03-01 12:04:59
// 2009-03-01 12:00:00 + 0.16667 hour(s) = 2009-03-01 12:10:00
// 2009-03-01 12:00:00 + 0.25 hour(s) = 2009-03-01 12:15:00
// 2009-03-01 12:00:00 + 0.33333 hour(s) = 2009-03-01 12:19:59
// 2009-03-01 12:00:00 + 0.5 hour(s) = 2009-03-01 12:30:00
// 2009-03-01 12:00:00 + 0.66667 hour(s) = 2009-03-01 12:40:00
// 2009-03-01 12:00:00 + 1 hour(s) = 2009-03-01 13:00:00
// 2009-03-01 12:00:00 + 2 hour(s) = 2009-03-01 14:00:00
// 2009-03-01 12:00:00 + 29 hour(s) = 2009-03-02 17:00:00
// 2009-03-01 12:00:00 + 30 hour(s) = 2009-03-02 18:00:00
// 2009-03-01 12:00:00 + 31 hour(s) = 2009-03-02 19:00:00
// 2009-03-01 12:00:00 + 90 hour(s) = 2009-03-05 06:00:00
// 2009-03-01 12:00:00 + 365 hour(s) = 2009-03-16 17:00:00
Represents a strongly typed list of objects that can be accessed by index. Provides methods to search...
Definition list.h:71
Represents the standard input, output, and error streams for console applications.
Definition console.h:36
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.h:15
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
valueA 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_exceptionThe resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
Examples
The following example uses the xtd::date_timeadd_milliseconds method to add one millisecond and 1.5 milliseconds to a xtd::date_time value. It then displays each new value and displays the difference between it and the original value. The difference is displayed both as a time span and as a number of ticks. The example makes it clear that one millisecond equals 10,000 ticks. It also shows that fractional milliseconds are rounded before performing the addition; the xtd::date_time value that results from adding 1.5 milliseconds to the original date is 2 milliseconds greater than the original date.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <xtd/string>
using namespace xtd;
class program {
public:
static auto main() {
auto date_format = "{0:d}/{0:t}.{0:c}"_s;
auto date1 = date_time {2010, 9, 8, 16, 0, 0};
console::write_line("Original date: {0} ({1:N0} ticks)\n", string::format(date_format, date1), date1.ticks());
auto date2 = date1.add_milliseconds(1);
console::write_line("Second date: {0} ({1:N0} ticks)", string::format(date_format, date2), date2.ticks());
console::write_line("Difference between dates: {0} ({1:N0} ticks)\n", date2 - date1, date2.ticks() - date1.ticks());
auto date3 = date1.add_milliseconds(1.5);
console::write_line("Third date: {0} ({1:N0} ticks)", string::format(date_format, date3), date3.ticks());
console::write_line("Difference between dates: {0} ({1:N0} ticks)", date3 - date1, date3.ticks() - date1.ticks());
}
};
startup_(program::main);
// This code produces the following output :
//
// Original date: 09/08/2010/16:00:00.0000000 (634195584000000000 ticks)
//
// Second date: 09/08/2010/16:00:00.0000000 (634195584000010000 ticks)
// Difference between dates: Mon Jan 1 00:00:00 0001 (10000 ticks)
//
// Third date: 09/08/2010/16:00:00.0005000 (634195584000015000 ticks)
// Difference between dates: Mon Jan 1 00:00:00 0001 (15000 ticks)
Remarks
This method does not change the value of this xtd::date_time. Instead, it returns a new xtd::date_time whose value is the result of this operation.
The fractional part of value is the fractional part of a millisecond. For example, 4.5 is equivalent to 4 milliseconds and 5000 ticks, where one millisecond = 10000 ticks.
The value parameter is rounded to the nearest integer.

◆ add_minutes()

date_time xtd::date_time::add_minutes ( double  value) const

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

Parameters
valueA 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_exceptionThe 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
monthsA 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_exceptionThe resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
-or-
months is less than -120,000 or greater than 120,000.
Examples
The following example adds between zero and fifteen months to the last day of December, 2015. In this case, the xtd::date_time::add_months method returns the date of the last day of each month, and successfully handles leap years.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto dat = date_time {2015, 12, 31};
for (auto ctr = 0; ctr <= 15; ctr++)
console::write_line(dat.add_months(ctr).to_string("d"));
}
};
startup_(program::main);
// This code produces the following output :
//
// 12/31/2015
// 01/31/2016
// 02/29/2016
// 03/31/2016
// 04/30/2016
// 05/31/2016
// 06/30/2016
// 07/31/2016
// 08/31/2016
// 09/30/2016
// 10/31/2016
// 11/30/2016
// 12/31/2016
// 01/31/2017
// 02/28/2017
// 03/31/2017
Remarks
This method does not change the value of this xtd::date_time object. Instead, it returns a new xtd::date_time object whose value is the result of this operation.
The xtd::date_time::add_months method calculates the resulting month and year, taking into account leap years and the number of days in a month, then adjusts the day part of the resulting xtd::date_time object. If the resulting day is not a valid day in the resulting month, the last valid day of the resulting month is used. For example, March 31st + 1 month = April 30th, and March 31st - 1 month = February 28 for a non-leap year and February 29 for a leap year.

◆ add_seconds()

date_time xtd::date_time::add_seconds ( double  value) const

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

Parameters
valueA 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_exceptionThe 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
valueA 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_exceptionThe 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
valueA 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_exceptionThe resulting xtd::date_time is less than xtd::date_time::min_value or greater than xtd::date_time::max_value.
Remarks
This method does not change the value of this xtd::date_time object. Instead, it returns a new xtd::date_time object whose value is the result of this operation.
The xtd::date_time::add_years method calculates the resulting year taking into account leap years. The month and time-of-day part of the resulting xtd::date_time object remains the same as this instance.
If the current instance represents the leap day in a leap year, the return value depends on the target date:
  • If value + xtd::date_time::year() is also a leap year, the return value represents the leap day in that year. For example, if four years is added to February 29, 2012, the date returned is February 29, 2016.
  • If value + xtd::date_time::year() is not a leap year, the return value represents the day before the leap day in that year. For example, if one year is added to February 29, 2012, the date returned is February 28, 2013.
Examples
The following example illustrates using the xtd::date_time::add_years method with a xtd::date_time value that represents a leap year day. It displays the date for the fifteen years prior to and the fifteen years that follow February 29, 2000.
Examples
date_time_day_of_year.cpp.

◆ compare_to()

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

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

Parameters
objAn 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/3]

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

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

Parameters
objAn 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_date_time_formats()

std::vector< 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
valueThe 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_exceptionThe 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
valueThe 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_exceptionThe 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:

◆ 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_exceptionThe 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_exceptionThe resulting file time would represent a date and time before 12:00 midnight January 1, 1601 C.E. UTC.
Remarks
A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file.
The xtd::date_time::to_file_time_utc method uses the xtd::date_time::to_file_timextd::date_time::kind property to determine whether the current xtd::date_time object is a local time, a UTC time, or an unspecified kind of time which is treated as a UTC time. If it is a local time, it converts the time to UTC before performing the conversion to a Windows file time.

◆ to_local_time()

date_time xtd::date_time::to_local_time ( ) const

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

Returns
An object whose xtd::date_time::kind property is xtd::date_time_kind::local, and whose value is the local time equivalent to the value of the current xtd::date_time object, or xtd::date_time::max_value if the converted value is too large to be represented by a xtd::date_time object, or xtd::date_time::min_value if the converted value is too small to be represented as a xtd::date_time object.
Examples
The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Get the date and time for the current moment, adjusted
// to the local time zone.
auto save_now = date_time::now();
// Get the date and time for the current moment expressed
// as coordinated universal time (UTC).
auto save_utc_now = date_time::utc_now();
auto my_dt = date_time {};
// display the value and kind property of the current moment
// expressed as UTC and local time.
display_now("utc_now: ...........", save_utc_now);
display_now("now: ...............", save_now);
console::write_line();
// Change the kind property of the current moment to
// date_time_kind::utc and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
display("utc: ...............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::local and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::local);
display("local: .............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::unspecified and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
display("unspecified: .......", my_dt);
}
// display the value and kind() property of a date_time structure, the
// date_time structure converted to local time, and the date_time
// structure converted to universal time.
static void display(const 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("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
// Convert input_dt to local time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
// If input_dt.kind() is date_time_kind::local, the conversion is not performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was universal time.
disp_dt = input_dt.to_local_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_local_time: {0}, kind = {1}", dt_string, disp_dt.kind());
// Convert input_dt to universal time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
// If input_dt.kind() is date_time_kind::local, the conversion is performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was local time.
disp_dt = input_dt.to_universal_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
console::write_line();
}
// display the value and kind property for date_time::now() and date_time::utc_now().
static void display_now(const string& title, const date_time& input_dt) {
auto dt_string = input_dt.to_string("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
}
};
startup_(program::main);
// This code can produce the following output :
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
// to_local_time: 2021-12-31 19:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
Remarks
The local time is equal to the Coordinated Universal Time (UTC) time plus the UTC offset. For more information about the UTC offset, see xtd::time_zone_info::get_utc_offset. The conversion also takes into account the daylight saving time rule that applies to the time represented by the current xtd::date_time object.
The value returned by the xtd::date_time::to_local_time method is determined by the xtd::date_time::kind property of the current xtd::date_time object. The following table describes the possible results.
Kind Results
xtd::date_time_kind::utc This instance of xtd::date_timextd::date_time is converted to local time.
xtd::date_time_kind::local No conversion is performed.
xtd::date_time_kind::unspecified This instance of xtd::date_time is assumed to be a UTC time, and the conversion is performed as if xtd::date_time::kind were xtd::date_time_kind::utc.
Note
The xtd::date_time::to_local_time method converts a xtd::date_time:: value from UTC to local time. To convert the time in any designated time zone to local time, use the xtd::time_zone_info::convert_time method.
Remarks
The value returned by the conversion is a xtd::date_time whose xtd::date_time::Kind property always returns xtd::date_time_kind::local. Consequently, a valid result is returned even if xtd::date_time::to_local_time is applied repeatedly to the same xtd::date_time.
Examples
date_time_specify_kind.cpp.

◆ to_long_date_string()

const xtd::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/3]

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.

Examples
date_time_specify_kind.cpp.

◆ to_string() [2/3]

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
formatA 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_excpetionThe length of format is 1, and it is not a valid format characters
-or-
The length si greater than 1.
Examples
The foloowwing example shows how to use xtd::date_time::to_string(const xtd::string&) with differentt formats.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto date1 = date_time {2008, 4, 1, 18, 7, 5, 16};
console::write_line(date1.to_string("a")); // PM
console::write_line(date1.to_string("b")); // 016
console::write_line(date1.to_string("B")); // 16
console::write_line(date1.to_string("c")); // 0160000
console::write_line(date1.to_string("c")); // 160000
console::write_line(date1.to_string("d")); // 04/01/2008
console::write_line(date1.to_string("D")); // 4/01/2008
console::write_line(date1.to_string("e")); // 05
console::write_line(date1.to_string("E")); // 5
console::write_line(date1.to_string("f")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("F")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("g")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("G")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("h")); // Tue
console::write_line(date1.to_string("H")); // Tuesday
console::write_line(date1.to_string("i")); // 01
console::write_line(date1.to_string("I")); // 1
console::write_line(date1.to_string("j")); // Apr
console::write_line(date1.to_string("J")); // April
console::write_line(date1.to_string("k")); // 04
console::write_line(date1.to_string("K")); // 4
console::write_line(date1.to_string("l")); // 08
console::write_line(date1.to_string("L")); // 2008
console::write_line(date1.to_string("m")); // 2008
console::write_line(date1.to_string("M")); // April 1
console::write_line(date1.to_string("n")); // Tuesday, 1 April 2008
console::write_line(date1.to_string("N")); // Tuesday, 1 April 2008 18:07:05
console::write_line(date1.to_string("o")); // 1 April 2008
console::write_line(date1.to_string("O")); // 1 April 2008
console::write_line(date1.to_string("p")); // 07
console::write_line(date1.to_string("P")); // 7
console::write_line(date1.to_string("s")); // 2008-04-01T18:07:05.0160000
console::write_line(date1.to_string("t")); // 18:07:05
console::write_line(date1.to_string("T")); // 18:07:05
console::write_line(date1.to_string("u")); // 2008-04-01 18:07:05
console::write_line(date1.to_string("U")); // Tuesday, 1 April 2008 18:07:05
console::write_line(date1.to_string("v")); // 18:07
console::write_line(date1.to_string("V")); // 18:07
console::write_line(date1.to_string("w")); // 18
console::write_line(date1.to_string("W")); // 18
console::write_line(date1.to_string("x")); // 06
console::write_line(date1.to_string("X")); // 6
console::write_line(date1.to_string("y")); // April 8
console::write_line(date1.to_string("Y")); // April 2008
console::write_line(date1.to_string("z")); // UTC
console::write_line(date1.to_string("Z")); // UTC
// Other format generate a xtd::format_exception exception
}
};
startup_(program::main);
// This code produces the following output :
//
// PM
// 016
// 16
// 0160000
// 160000
// 04/01/2008
// 4/01/2008
// 05
// 5
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue
// Tuesday
// 01
// 1
// Apr
// April
// 04
// 4
// 08
// 2008
// 2008
// April 1
// Tuesday, 1 April 2008
// Tuesday, 1 April 2008 18:07:05
// 1 April 2008
// 1 April 2008
// 07
// 7
// 2008-04-01T18:07:05.0160000
// 18:07:05
// 18:07:05
// 2008-04-01 18:07:05
// Tuesday, 1 April 2008 18:07:05
// 18:07
// 18:07
// 18
// 18
// 06
// 6
// April 8
// April 2008
// UTC
// UTC
Remarks
The formatting codes for xtd::date_time::to_string (const xtd::string&) are listed below:
Format Print
'a' writes "PM" or "AM"
'b' writes 3 digit millisecond, e.G. 012
'B' wrties millisecond, eg 12
'c' writes 7 digit tick, e.G. 0000123
'C' writes tick, e.G. 123
'd' writes date MM/dd/y, e.g. 01/05/42
'D' writes date M/dd/y, e.g. 1/055/42
'e' writes 2 digit second, e.G. 03
'B' writes second, e.G. 3
'f' writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'F' writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'g' writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'G' writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'h' writes abbreviated weekday name, e.g. Fri (locale dependent).
'H' writes full weekday name, e.g. Friday (locale dependent).
'i' writes 2 digit day, e.g. 05
'I' writes day, e.G. 5
'j' writes abbreviated month name, e.g. Oct (locale dependent)
'J' writes full month name, e.g. October (locale dependent).
'k' writes 2 digit month, e.g. 01
'K' writes month, e.g. 1
'l' writes 2 digit year, e.g. 71
'L' writes 4 digit year, e.g. 1971
'm' writes year, e.g. 42
'M' writes full month name and day, e.g. October, 5 (locale dependent).
'n' writes full weekday name, day, fulll month and year, e.g. Tuesday, 1 April 2008
'N' writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'o' writes day, full month and year, e.g. 5 January 42
'O' writes day, full month and year, e.g. 5 January 42
'p' writes 2 digit minute, e.G. 06
'P' writes minute, e.G. 6
's' writes sortable date/time pattern yyyy-MM-ddThh:mm:ss.ttttttt. e.g. 1971-05-01T21:32:24:42.004567
't' writes time hh/mm/ss, e.g. 02:04:06
'T' writes time h/mm/ss, e.g. 2:04:06
'u' writes sortable short date/time pattern y-MM-dd hh:mm:ss. e.g. 1971-05-01 9:32:24:42
'U' writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'v' writes time hh/mm, e.g. 02:04
'V' writes time h/mm, e.g. 2:04
'w' writes 2 digit hour (24H), e.g. 07
'W' writes hour (24H), e.g. 7
'x' writes 2 digit hour (12H), e.g. 07
'X' writes hour (12H), e.g. 7
'y' writes full month name and year, e.g. October, 71 (locale dependent).
'Y' writes full month name and year, e.g. October, 1971 (locale dependent).
'z' writes time zone "local" or "UTC".
'Z' writes time zone "local" or "UTC".

◆ to_string() [3/3]

xtd::string xtd::date_time::to_string ( const string format,
const std::locale &  loc 
) 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
formatA standard or custom date and time format string.
locAn std::locale object that contains locale information (see std::locale).
Returns
A string representation of value of the current xtd::date_time object as specified by format.
Exceptions
xtd::format_excpetionThe length of format is 1, and it is not a valid format characters
-or-
The length si greater than 1.
Examples
The foloowwing example shows how to use xtd::date_time::to_string(const xtd::string&) with differentt formats.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto date1 = date_time {2008, 4, 1, 18, 7, 5, 16};
console::write_line(date1.to_string("a")); // PM
console::write_line(date1.to_string("b")); // 016
console::write_line(date1.to_string("B")); // 16
console::write_line(date1.to_string("c")); // 0160000
console::write_line(date1.to_string("c")); // 160000
console::write_line(date1.to_string("d")); // 04/01/2008
console::write_line(date1.to_string("D")); // 4/01/2008
console::write_line(date1.to_string("e")); // 05
console::write_line(date1.to_string("E")); // 5
console::write_line(date1.to_string("f")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("F")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("g")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("G")); // Tue Apr 1 18:07:05 2008
console::write_line(date1.to_string("h")); // Tue
console::write_line(date1.to_string("H")); // Tuesday
console::write_line(date1.to_string("i")); // 01
console::write_line(date1.to_string("I")); // 1
console::write_line(date1.to_string("j")); // Apr
console::write_line(date1.to_string("J")); // April
console::write_line(date1.to_string("k")); // 04
console::write_line(date1.to_string("K")); // 4
console::write_line(date1.to_string("l")); // 08
console::write_line(date1.to_string("L")); // 2008
console::write_line(date1.to_string("m")); // 2008
console::write_line(date1.to_string("M")); // April 1
console::write_line(date1.to_string("n")); // Tuesday, 1 April 2008
console::write_line(date1.to_string("N")); // Tuesday, 1 April 2008 18:07:05
console::write_line(date1.to_string("o")); // 1 April 2008
console::write_line(date1.to_string("O")); // 1 April 2008
console::write_line(date1.to_string("p")); // 07
console::write_line(date1.to_string("P")); // 7
console::write_line(date1.to_string("s")); // 2008-04-01T18:07:05.0160000
console::write_line(date1.to_string("t")); // 18:07:05
console::write_line(date1.to_string("T")); // 18:07:05
console::write_line(date1.to_string("u")); // 2008-04-01 18:07:05
console::write_line(date1.to_string("U")); // Tuesday, 1 April 2008 18:07:05
console::write_line(date1.to_string("v")); // 18:07
console::write_line(date1.to_string("V")); // 18:07
console::write_line(date1.to_string("w")); // 18
console::write_line(date1.to_string("W")); // 18
console::write_line(date1.to_string("x")); // 06
console::write_line(date1.to_string("X")); // 6
console::write_line(date1.to_string("y")); // April 8
console::write_line(date1.to_string("Y")); // April 2008
console::write_line(date1.to_string("z")); // UTC
console::write_line(date1.to_string("Z")); // UTC
// Other format generate a xtd::format_exception exception
}
};
startup_(program::main);
// This code produces the following output :
//
// PM
// 016
// 16
// 0160000
// 160000
// 04/01/2008
// 4/01/2008
// 05
// 5
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue Apr 1 18:07:05 2008
// Tue
// Tuesday
// 01
// 1
// Apr
// April
// 04
// 4
// 08
// 2008
// 2008
// April 1
// Tuesday, 1 April 2008
// Tuesday, 1 April 2008 18:07:05
// 1 April 2008
// 1 April 2008
// 07
// 7
// 2008-04-01T18:07:05.0160000
// 18:07:05
// 18:07:05
// 2008-04-01 18:07:05
// Tuesday, 1 April 2008 18:07:05
// 18:07
// 18:07
// 18
// 18
// 06
// 6
// April 8
// April 2008
// UTC
// UTC
Remarks
The formatting codes for xtd::date_time::to_string (const xtd::string&) are listed below:
Format Print
'a' writes "PM" or "AM"
'b' writes 3 digit millisecond, e.G. 012
'B' wrties millisecond, eg 12
'c' writes 7 digit tick, e.G. 0000123
'C' writes tick, e.G. 123
'd' writes date MM/dd/y, e.g. 01/05/42
'D' writes date M/dd/y, e.g. 1/055/42
'e' writes 2 digit second, e.G. 03
'B' writes second, e.G. 3
'f' writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'F' writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'g' writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
'G' writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
'h' writes abbreviated weekday name, e.g. Fri (locale dependent).
'H' writes full weekday name, e.g. Friday (locale dependent).
'i' writes 2 digit day, e.g. 05
'I' writes day, e.G. 5
'j' writes abbreviated month name, e.g. Oct (locale dependent)
'J' writes full month name, e.g. October (locale dependent).
'k' writes 2 digit month, e.g. 01
'K' writes month, e.g. 1
'l' writes 2 digit year, e.g. 71
'L' writes 4 digit year, e.g. 1971
'm' writes year, e.g. 42
'M' writes full month name and day, e.g. October, 5 (locale dependent).
'n' writes full weekday name, day, fulll month and year, e.g. Tuesday, 1 April 2008
'N' writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'o' writes day, full month and year, e.g. 5 January 42
'O' writes day, full month and year, e.g. 5 January 42
'p' writes 2 digit minute, e.G. 06
'P' writes minute, e.G. 6
's' writes sortable date/time pattern yyyy-MM-ddThh:mm:ss.ttttttt. e.g. 1971-05-01T21:32:24:42.004567
't' writes time hh/mm/ss, e.g. 02:04:06
'T' writes time h/mm/ss, e.g. 2:04:06
'u' writes sortable short date/time pattern y-MM-dd hh:mm:ss. e.g. 1971-05-01 9:32:24:42
'U' writes full weekday name, day, fulll month, year, hour, minute ans second, e.g. Tuesday, 1 April 2008 18:07:05
'v' writes time hh/mm, e.g. 02:04
'V' writes time h/mm, e.g. 2:04
'w' writes 2 digit hour (24H), e.g. 07
'W' writes hour (24H), e.g. 7
'x' writes 2 digit hour (12H), e.g. 07
'X' writes hour (12H), e.g. 7
'y' writes full month name and year, e.g. October, 71 (locale dependent).
'Y' writes full month name and year, e.g. October, 1971 (locale dependent).
'z' writes time zone "local" or "UTC".
'Z' writes time zone "local" or "UTC".

Implements xtd::iformatable.

◆ to_time_t()

std::time_t xtd::date_time::to_time_t ( ) const

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

Returns
The value of the current xtd::date_time object expressed as std::time_t.
Remarks
std::time_t is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.
See <std::chrono for more information.

◆ to_tm()

std::tm xtd::date_time::to_tm ( ) const

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

Returns
The value of the current xtd::date_time object expressed as std::tm.
Remarks
std::tm is a structure holding a calendar date and time broken down into its components. is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.
See <std::chrono for more information.

◆ to_universal_time()

date_time xtd::date_time::to_universal_time ( ) const

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

Returns
An object whose xtd::date_time::kind property is xtd::date_time_kind::utc, and whose value is the UTC equivalent to the value of the current xtd::date_time object, or xtd::date_time::max_value if the converted value is too large to be represented by a xtd::date_time object, or xtd::date_time::min_value if the converted value is too small to be represented by a xtd::date_time object.
Examples
The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Get the date and time for the current moment, adjusted
// to the local time zone.
auto save_now = date_time::now();
// Get the date and time for the current moment expressed
// as coordinated universal time (UTC).
auto save_utc_now = date_time::utc_now();
auto my_dt = date_time {};
// display the value and kind property of the current moment
// expressed as UTC and local time.
display_now("utc_now: ...........", save_utc_now);
display_now("now: ...............", save_now);
console::write_line();
// Change the kind property of the current moment to
// date_time_kind::utc and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
display("utc: ...............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::local and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::local);
display("local: .............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::unspecified and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
display("unspecified: .......", my_dt);
}
// display the value and kind() property of a date_time structure, the
// date_time structure converted to local time, and the date_time
// structure converted to universal time.
static void display(const 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("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
// Convert input_dt to local time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
// If input_dt.kind() is date_time_kind::local, the conversion is not performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was universal time.
disp_dt = input_dt.to_local_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_local_time: {0}, kind = {1}", dt_string, disp_dt.kind());
// Convert input_dt to universal time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
// If input_dt.kind() is date_time_kind::local, the conversion is performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was local time.
disp_dt = input_dt.to_universal_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
console::write_line();
}
// display the value and kind property for date_time::now() and date_time::utc_now().
static void display_now(const string& title, const date_time& input_dt) {
auto dt_string = input_dt.to_string("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
}
};
startup_(program::main);
// This code can produce the following output :
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
// to_local_time: 2021-12-31 19:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
Remarks
The Coordinated Universal Time (UTC) is equal to the local time minus the UTC offset. For more information about the UTC offset, see xtd::time_zone_info::get_utc_offset. The conversion also takes into account the daylight saving time rule that applies to the time represented by the current xtd::date_time object.
The value returned by the xtd::date_time::to_universal_time method is determined by the xtd::date_time::kind property of the current xtd::date_time object. The following table describes the possible results.
Kind Results
xtd::date_time_kind::utc No conversion is performed.
xtd::date_time_kind::local The current xtd::date_time object is converted to UTC.
xtd::date_time_kind::unspecified The current xtd::date_time object is assumed to be a local time, and the conversion is performed as if xtd::date_time::kind were Local.
Examples
date_time_specify_kind.cpp.

◆ now()

static date_time xtd::date_time::now ( )
staticnoexcept

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

Returns
An object whose value is the current local date and time.
Examples
The following example uses the xtd::date_time::now and xtd::date_time::utc_now properties to retrieve the current local date and time and the current universal coordinated (UTC) date and time. It then uses the formatting conventions of a number of locale to display the strings, along with the values of the their xtd::datte_time::kind properties.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::collections::generic;
class program {
public:
static auto main() {
auto local_date = date_time::now();
auto utc_date = date_time::utc_now();
auto locale_names = list {"en_US", "en_GB", "fr_FR", "de_DE", "ru_RU"};
for (auto locale_name : locale_names) {
try {
std::locale::global(std::locale {locale_name + ".utf-8"_s});
console::write_line("{}:", locale_name);
console::write_line(" Local date and time: {}, {}", local_date.to_string(), local_date.kind());
console::write_line(" UTC date and time: {}, {}\n", utc_date.to_string(), utc_date.kind());
} catch (const std::exception& e) {
console::write_line(string::format("Make sure {} locale is installed on your system :\n\n{}\n", locale_name, e.what()), "Exception");
}
}
}
};
startup_(program::main);
// This code can produce the following output :
//
// en_US
// Local date and time: Sun Jan 2 09:50:36 2022, local
// UTC date and time: Sun Jan 2 08:50:36 2022, utc
//
// en_GB
// Local date and time: Sun 2 Jan 09:50:36 2022, local
// UTC date and time: Sun 2 Jan 08:50:36 2022, utc
//
// fr_FR
// Local date and time: Dim 2 jan 09:50:36 2022, local
// UTC date and time: Dim 2 jan 08:50:36 2022, utc
//
// de_DE
// Local date and time: So 2 Jan 09:50:36 2022, local
// UTC date and time: So 2 Jan 08:50:36 2022, utc
//
// ru_RU
// Local date and time: воскресенье, 2 января 2022 г. 09:50:36, local
// UTC date and time: воскресенье, 2 января 2022 г. 08:50:36, utc
@ e
The E key.
Remarks
The xtd::date_time::now property returns a xtd::date_time value that represents the current date and time on the local computer. Note that there is a difference between a xtd::date_time value, which represents the number of ticks that have elapsed since midnight of January 1, 0001, and the string representation of that xtd::date_time value, which expresses a date and time value in a culture-specific-specific format. For information on formatting date and time values, see the to_string method. The following example displays the short date and time string in a number of culture-specific formats.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::collections::generic;
class program {
public:
static auto main() {
auto local_date = date_time::now();
auto locale_names = list {"en_US", "en_GB", "fr_FR", "de_DE", "ru_RU"};
for (auto locale_name : locale_names) {
try {
std::locale::global(std::locale {locale_name + ".utf-8"_s});
console::write_line("{}: {}", locale_name, date_time::sprintf("%x %T", local_date));
} catch (const std::exception& e) {
console::write_line(string::format("Make sure {} locale is installed on your system :\n\n{}\n", locale_name, e.what()), "Exception");
}
}
}
};
startup_(program::main);
// This code can produce the following output :
//
// en_US: 01/02/2022 10:59:07
// en_GB: 02/01/2022 10:59:07
// fr_FR: 02.01.2022 10:59:07
// de_DE: 02.01.2022 10:59:07
// ru_RU: 02.01.2022 10:59:07
Examples
date_time_add.cpp, date_time_add_days.cpp, and sprintf_date_time.cpp.

◆ 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/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::collections::generic;
class program {
public:
static auto main() {
auto dates = list {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
yearThe year.
monthThe 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_exceptionmonth 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() {
xtd::console::write_line(days_in_july);
// days_in_feb gets 28 because the year 1998 was not a leap year.
// days_in_feb_leap gets 29 because the year 1996 was a leap year.
xtd::console::write_line(days_in_feb_leap);
}
};
startup_(program::main);
// This code produces the following output :
//
// 31
// 28
// 29
static int32 days_in_month(uint32 year, month_of_year month)
Returns the number of days in the specified month and year.
@ july
Indicates july.
@ february
Indicates february.
Examples
The following example displays the number of days in each month of a year specified in an integer array.
#include <xtd/as>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <array>
using namespace xtd;
class program {
public:
static auto main() {
auto years = std::array<unsigned int, 2> {2012, 2014};
console::write_line("Days in the Month for the Gregorian calendar\n");
console::write_line("{0,-10}{1,-15}{2,4}\n", "Year", "Month", "Days");
for (auto year : years) {
for (auto ctr = 1u; ctr <= 12u; ctr++)
console::write_line("{0,-10}{1,-15}{2,4}", year, as<month_of_year>(ctr), date_time::days_in_month(year, ctr));
console::write_line();
}
}
};
startup_(program::main);
// This code 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
yearThe year.
monthThe 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_exceptionmonth 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() {
xtd::console::write_line(days_in_july);
// days_in_feb gets 28 because the year 1998 was not a leap year.
// days_in_feb_leap gets 29 because the year 1996 was a leap year.
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/as>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
#include <array>
using namespace xtd;
class program {
public:
static auto main() {
auto years = std::array<unsigned int, 2> {2012, 2014};
console::write_line("Days in the Month for the Gregorian calendar\n");
console::write_line("{0,-10}{1,-15}{2,4}\n", "Year", "Month", "Days");
for (auto year : years) {
for (auto ctr = 1u; ctr <= 12u; ctr++)
console::write_line("{0,-10}{1,-15}{2,4}", year, as<month_of_year>(ctr), date_time::days_in_month(year, ctr));
console::write_line();
}
}
};
startup_(program::main);
// This code 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_dataA 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_exceptiondate_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_timeA 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_exceptionfile_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) {
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;
// file_creation_time is not valid, so re-throw the exception.
throw;
}
}
The exception that is thrown when one of the arguments provided to a method is out of range.
Definition argument_out_of_range_exception.h:23
static date_time from_file_time(int64 file_time)
Converts the specified Windows file time to an equivalent local time.
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 instan...
int64_t int64
Represents a 64-bit signed integer.
Definition int64.h:23
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_timeA 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_exceptionfile_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
valueA 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_exceptionvalue 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
valueA time interval from the start of the Clock's epoch.
kindOne 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_exceptionvalue 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
valueA 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_exceptionvalue 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
valueA time interval from the start of the Clock's epoch.
kindOne 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_exceptionvalue 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
valueA 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_exceptionvalue.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
valueA std::tm struct.
kindOne 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_exceptionvalue.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
yearA 4-digit year.
Returns
true if year is a leap year; otherwise, false.
Exceptions
xtd::argument_out_of_range_exceptionyear is less than 1 or greater than 9999.

◆ parse()

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
sA 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_exceptions 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
valueA date and time.
kindOne of the enumeration values that indicates whether the new object represents local time, UTC, or neither.
Returns
A new object that has the same number of ticks as the object represented by the value parameter and the xtd::date_time_kind value specified by the kind parameter.
Examples
The following example uses the xtd::date_time::specify_kind method to demonstrate how the xtd::date_time::kind property influences the xtd::date_time::to_local_time and xtd::date_time::to_universal_time conversion methods.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Get the date and time for the current moment, adjusted
// to the local time zone.
auto save_now = date_time::now();
// Get the date and time for the current moment expressed
// as coordinated universal time (UTC).
auto save_utc_now = date_time::utc_now();
auto my_dt = date_time {};
// display the value and kind property of the current moment
// expressed as UTC and local time.
display_now("utc_now: ...........", save_utc_now);
display_now("now: ...............", save_now);
console::write_line();
// Change the kind property of the current moment to
// date_time_kind::utc and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::utc);
display("utc: ...............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::local and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::local);
display("local: .............", my_dt);
// Change the kind property of the current moment to
// date_time_kind::unspecified and display the result.
my_dt = date_time::specify_kind(save_now, date_time_kind::unspecified);
display("unspecified: .......", my_dt);
}
// display the value and kind() property of a date_time structure, the
// date_time structure converted to local time, and the date_time
// structure converted to universal time.
static void display(const 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("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, disp_dt.kind());
// Convert input_dt to local time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is performed.
// If input_dt.kind() is date_time_kind::local, the conversion is not performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was universal time.
disp_dt = input_dt.to_local_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_local_time: {0}, kind = {1}", dt_string, disp_dt.kind());
// Convert input_dt to universal time and display the result.
// If input_dt.kind() is date_time_kind.Utc, the conversion is not performed.
// If input_dt.kind() is date_time_kind::local, the conversion is performed.
// If input_dt.kind() is date_time_kind::unspecified, the conversion is
// performed as if input_dt was local time.
disp_dt = input_dt.to_universal_time();
dt_string = disp_dt.to_string("u");
console::write_line(" to_universal_time: {0}, kind = {1}", dt_string, disp_dt.kind());
console::write_line();
}
// display the value and kind property for date_time::now() and date_time::utc_now().
static void display_now(const string& title, const date_time& input_dt) {
auto dt_string = input_dt.to_string("u");
console::write_line("{0} {1}, kind = {2}", title, dt_string, input_dt.kind());
}
};
startup_(program::main);
// This code can produce the following output :
//
// utc_now: ........... 2021-12-31 17:08:41, Kind = utc
// now: ............... 2021-12-31 18:08:41, Kind = local
//
// utc: ............... 2021-12-31 17:08:41, Kind = utc
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// local: ............. 2021-12-31 18:08:41, Kind = local
// to_local_time: 2021-12-31 18:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc
//
// unspecified: ....... 2021-12-31 18:08:41, Kind = unspecified
// to_local_time: 2021-12-31 19:08:41, Kind = local
// to_universal_time: 2021-12-31 17:08:41, Kind = utc

◆ sprintf()

static xtd::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
formatFormat-control String.
valueThe xtd::date_time object to format.
Returns
A xtd::string that represents the current xtd::date_time.
Examples
The foloowwing example shows how to use xtd::date_time::sprintf with differentt formats.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
auto date1 = date_time {2008, 4, 1, 18, 7, 5, 16};
console::write_line(date_time::sprintf("%a", date1)); // Tue
console::write_line(date_time::sprintf("%A", date1)); // Tuesday
console::write_line(date_time::sprintf("%b", date1)); // Apr
console::write_line(date_time::sprintf("%B", date1)); // April
console::write_line(date_time::sprintf("%c", date1)); // Tue Apr 1 18:07:05 2008
console::write_line(date_time::sprintf("%C", date1)); // 20
console::write_line(date_time::sprintf("%d", date1)); // 01
console::write_line(date_time::sprintf("%D", date1)); // 04/01/08
console::write_line(date_time::sprintf("%e", date1)); // 1
console::write_line(date_time::sprintf("%Ec", date1)); // Tue Apr 1 18:07:05 2008
console::write_line(date_time::sprintf("%EC", date1)); // 20
console::write_line(date_time::sprintf("%Ex", date1)); // 04/01/08
console::write_line(date_time::sprintf("%EX", date1)); // 18:07:05
console::write_line(date_time::sprintf("%Ey", date1)); // 08
console::write_line(date_time::sprintf("%EY", date1)); // 2008
console::write_line(date_time::sprintf("%F", date1)); // 2008-04-01
console::write_line(date_time::sprintf("%g", date1)); // 08
console::write_line(date_time::sprintf("%G", date1)); // 2008
console::write_line(date_time::sprintf("%h", date1)); // Apr
console::write_line(date_time::sprintf("%H", date1)); // 18
console::write_line(date_time::sprintf("%I", date1)); // 06
console::write_line(date_time::sprintf("%j", date1)); // 093
console::write_line(date_time::sprintf("%m", date1)); // 04
console::write_line(date_time::sprintf("%M", date1)); // 07
console::write_line(date_time::sprintf("%p", date1)); // PM
console::write_line(date_time::sprintf("%r", date1)); // 06:07:05 PM
console::write_line(date_time::sprintf("%R", date1)); // 18:07
console::write_line(date_time::sprintf("%S", date1)); // 05
console::write_line(date_time::sprintf("%T", date1)); // 18:07:05
console::write_line(date_time::sprintf("%u", date1)); // 2
console::write_line(date_time::sprintf("%U", date1)); // 13
console::write_line(date_time::sprintf("%V", date1)); // 14
console::write_line(date_time::sprintf("%w", date1)); // 2
console::write_line(date_time::sprintf("%W", date1)); // 14
console::write_line(date_time::sprintf("%x", date1)); // 04/01/08
console::write_line(date_time::sprintf("%X", date1)); // 18:07:05
console::write_line(date_time::sprintf("%y", date1)); // 08
console::write_line(date_time::sprintf("%Y", date1)); // 2008
console::write_line(date_time::sprintf("%z", date1)); // +0100
console::write_line(date_time::sprintf("%Z", date1)); // CET
console::write_line(date_time::sprintf("%Od", date1)); // 01
console::write_line(date_time::sprintf("%Oe", date1)); // 1
console::write_line(date_time::sprintf("%OH", date1)); // 18
console::write_line(date_time::sprintf("%OI", date1)); // 06
console::write_line(date_time::sprintf("%Om", date1)); // 04
console::write_line(date_time::sprintf("%OM", date1)); // 07
console::write_line(date_time::sprintf("%OS", date1)); // 05
console::write_line(date_time::sprintf("%Ou", date1)); // 2
console::write_line(date_time::sprintf("%OU", date1)); // 13
console::write_line(date_time::sprintf("%OV", date1)); // 14
console::write_line(date_time::sprintf("%Ow", date1)); // 2
console::write_line(date_time::sprintf("%OW", date1)); // 14
console::write_line(date_time::sprintf("%Oy", date1)); // 08
}
};
startup_(program::main);
// This code produces the following output :
//
// Tue
// Tuesday
// Apr
// April
// Tue Apr 1 18:07:05 2008
// 20
// 01
// 04/01/08
// 1
// Tue Apr 1 18:07:05 2008
// 20
// 04/01/08
// 18:07:05
// 08
// 2008
// 2008-04-01
// 08
// 2008
// Apr
// 18
// 06
// 093
// 04
// 07
// PM
// 06:07:05 PM
// 18:07
// 05
// 18:07:05
// 2
// 13
// 14
// 2
// 14
// 04/01/08
// 18:07:05
// 08
// 2008
// +0100
// CET
// 01
// 1
// 18
// 06
// 04
// 07
// 05
// 2
// 13
// 14
// 2
// 14
// 08
Remarks
The formatting codes for sprintf are listed below:
Format Print
%a writes abbreviated weekday name, e.g. Fri (locale dependent).
%A writes full weekday name, e.g. Friday (locale dependent).
%b writes abbreviated month name, e.g. Oct (locale dependent)
%B writes full month name, e.g. October (locale dependent).
%c  writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent).
%C writes first 2 digits of year as a decimal number (range [00,99]).
%d writes day of the month as a decimal number (range [01,31]).
%D equivalent to "%m/%d/%y".
%e  writes day of the month as a decimal number (range [1,31]).
%Ec writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%EC Writes name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP
%Ex  writes alternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%EX writes alternative time representation (locale dependent).
%Ey writes year as offset from locale's alternative calendar period EC.
%EY writes year in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale.
%F equivalent to "%Y-%m-%d" (the ISO 8601 date format).
%g  writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]).
%G  writes ISO 8601 week-based year, i.e. the year that contains the specified week.
%h synonym of b.
%H writes hour as a decimal number, 24 hour clock (range [00-23]).
%I writes hour as a decimal number, 12 hour clock (range [01,12]).
%j writes day of the year as a decimal number (range [001,366]).
%m writes month as a decimal number (range [01,12]).
%M writes minute as a decimal number (range [00,59]).
%Od writes zero-based day of the month using the alternative numeric system, e.g 二十七 instead of 27 in ja_JP locale.
%Oe writes one-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale.
%OH writes hour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale.
%OI writes hour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale.
%Om writes month using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale.
%OM writes minute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale.
%OS  writes second using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale.
%Ou writes weekday, where Monday is 1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale.
%OU writes week of the year, as by U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%OV  writes week of the year, as by V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%Ow writes weekday, where Sunday is 0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale.
%OW writes week of the year, as by W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale.
%Oy writes last 2 digits of year using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale.
%p writes localized a.m. or p.m. (locale dependent).
%r  writes localized 12-hour clock time (locale dependent).
%R  equivalent to "%H:%M".
%S writes second as a decimal number (range [00,60]).
%T  equivalent to "%H:%M:%S" (the ISO 8601 time format)
%u writes weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]).
%U writes week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]).
%V  writes ISO 8601 week of the year (range [01,53]).
%w writes weekday as a decimal number, where Sunday is 0 (range [0-6]).
%W writes week of the year as a decimal number (Monday is the first day of the week) (range [00,53]).
%x writes localized date representation (locale dependent).
%X writes localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent).
%y writes last 2 digits of year as a decimal number (range [00,99]).
%Y writes year as a decimal number, e.g. 2017.
%z writes offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available.
%Z writes locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available.
%% writes literal %. The full conversion specification must be %%.
%n writes newline character.
%t writes horizontal tab character.
See std::put_time for more information.

◆ try_parse()

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
sA string containing a date and time to convert.
resultWhen 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.

◆ equals() [2/3]

virtual bool xtd::object::equals ( const object obj) const
virtualnoexcept

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

Parameters
objThe object to compare with the current object.
Returns
true if the specified object is equal to the current object. otherwise, false.
Examples
The following code example compares the current instance with another object.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
auto object1 = new_ptr<object>();
auto object2 = new_ptr<object>();
auto object3 = object2;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
object3 = object1;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
}
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

◆ equals() [3/3]

template<typename object_a_t , typename object_b_t >
static bool xtd::object::equals ( const object_a_t &  object_a,
const object_b_t &  object_b 
)
inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters
object_aThe first object to compare.
object_bThe second object to compare.
Returns
true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.
Examples
The following code example compares different objects.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
string s1 = "Tom";
string s2 = "Carol";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Tom";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Carol";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

Member Data Documentation

◆ max_value

const date_time xtd::date_time::max_value
static

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

Remarks
The value of this constant is equivalent to 23:59:59.9999999 UTC, December 31, 9999 in the Gregorian calendar, exactly one 100-nanosecond tick before 00:00:00 UTC, January 1, 10000.
Examples
The following example instantiates a xtd::date_time object by passing its constructor an xtd::ticks value that represents a number of ticks. Before invoking the constructor, the example ensures that this value is greater than or equal to date_time::min_value.ticks() and less than or equal to date_time::max_value.ticks(). If not, it throws an xtd::argument_out_of_range_exception.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/int64_object>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Attempt to assign an out-of-range value to a date_time constructor.
auto number_of_ticks = int64_object::max_value;
auto valid_date = date_time {};
// Validate the value.
if (number_of_ticks >= date_time::min_value.ticks() && number_of_ticks <= date_time::max_value.ticks()) {
valid_date = date_time(number_of_ticks);
console::write_line("{0} is valid.", valid_date.ticks());
} else if (number_of_ticks < date_time::min_value.ticks())
console::write_line("{0} is less than {1} ticks.", number_of_ticks, date_time::min_value.ticks());
else
console::write_line("{0} is greater than {1} ticks.", number_of_ticks, date_time::max_value.ticks());
}
};
startup_(program::main);
// This code produces the following output :
//
// 9223372036854775807 is greater than 3155378975999999999 ticks.

◆ min_value

const date_time xtd::date_time::min_value
static

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

Examples
The following example instantiates a xtd::date_time object by passing its constructor an xtd::ticks value that represents a number of ticks. Before invoking the constructor, the example ensures that this value is greater than or equal to date_time::min_value.ticks() and less than or equal to date_time::max_value.ticks(). If not, it throws an xtd::argument_out_of_range_exception.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/int64_object>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Attempt to assign an out-of-range value to a date_time constructor.
auto number_of_ticks = int64_object::max_value;
auto valid_date = date_time {};
// Validate the value.
if (number_of_ticks >= date_time::min_value.ticks() && number_of_ticks <= date_time::max_value.ticks()) {
valid_date = date_time(number_of_ticks);
console::write_line("{0} is valid.", valid_date.ticks());
} else if (number_of_ticks < date_time::min_value.ticks())
console::write_line("{0} is less than {1} ticks.", number_of_ticks, date_time::min_value.ticks());
else
console::write_line("{0} is greater than {1} ticks.", number_of_ticks, date_time::max_value.ticks());
}
};
startup_(program::main);
// This code produces the following output :
//
// 9223372036854775807 is greater than 3155378975999999999 ticks.
Remarks
The value of this constant is equivalent to 00:00:00.0000000 UTC, January 1, 0001, in the Gregorian calendar.
xtd::date_time::min_value defines the date and time that is assigned to an uninitialized xtd::date_time variable. The following example illustrates this.
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
class program {
public:
static auto main() {
// Define an uninitialized date.
auto date1 = date_time {};
console::write("{:u}", date1);
if (date1.equals(date_time::min_value))
console::write_line(" (Equals date_time.min_value)");
}
};
startup_(program::main);
// This code produces the following output :
//
// 01/01/0001 00:00:00 (Equals date_time.min_value)

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