subtract() [1/2]

xtd::time_span xtd::date_time::subtract

(

const date_time &

value

)

const

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

Parameters

value

The date and time value to subtract.

Returns

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

Exceptions

xtd::argument_out_of_range_exception

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

Examples

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

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

Remarks

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

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

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

Note

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