add_hours()

date_time xtd::date_time::add_hours

(

double

value

)

const

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

Parameters

value

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

Returns

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

Exceptions

xtd::argument_out_of_range_exception

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

Examples

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

#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
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

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.