subtract() [2/2]

date_time xtd::date_time::subtract

(

const xtd::time_span &

value

)

const

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

Parameters

value

The time interval to subtract.

Returns

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

Exceptions

xtd::argument_out_of_range_exception

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

Examples

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

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

Remarks

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

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

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

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

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