[#BloombergLP-bdlt-DatetimeInterval]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlt.adoc[bdlt]::DatetimeInterval
:relfileprefix: ../../
:mrdocs:

Each object of this class represents a (signed) time interval with microsecond resolution. See {The Representation of a Time Interval} for details.

== Synopsis

Declared in `<bdlt_datetimeinterval.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class DatetimeInterval;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/DatetimeInterval/2constructor-0f.adoc[`DatetimeInterval`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlt/DatetimeInterval/operator_assign.adoc[`operator=`] 
| Assign to this object the value of the specified `rhs` time interval, and return a reference providing modifiable access to this object.
| xref:BloombergLP/bdlt/DatetimeInterval/addDays.adoc[`addDays`] 
| Add to this time interval the specified number of `days`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addDaysIfValid.adoc[`addDaysIfValid`] 
| Add to this time interval the specified number of `days`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/addHours.adoc[`addHours`] 
| Add to this time interval the specified number of `hours`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addHoursIfValid.adoc[`addHoursIfValid`] 
| Add to this time interval the specified number of `hours`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/addInterval.adoc[`addInterval`] 
| Add to this time interval the specified number of `days`, and the optionally specified number of `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`, and return a reference providing modifiable access to this object. Unspecified arguments default to 0. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer). Note that the arguments may be supplied using a mixture of positive, negative, and 0 values.
| xref:BloombergLP/bdlt/DatetimeInterval/addIntervalIfValid.adoc[`addIntervalIfValid`] 
| Add to this time interval the specified number of `days`, and the optionally specified number of `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise. Note that the arguments may be supplied using a mixture of positive, negative, and 0 values.
| xref:BloombergLP/bdlt/DatetimeInterval/addMicroseconds.adoc[`addMicroseconds`] 
| Add to this time interval the specified number of `microseconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addMicrosecondsIfValid.adoc[`addMicrosecondsIfValid`] 
| Add to this time interval the specified number of `microseconds`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/addMilliseconds.adoc[`addMilliseconds`] 
| Add to this time interval the specified number of `milliseconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addMillisecondsIfValid.adoc[`addMillisecondsIfValid`] 
| Add to this time interval the specified number of `milliseconds`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/addMinutes.adoc[`addMinutes`] 
| Add to this time interval the specified number of `minutes`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addMinutesIfValid.adoc[`addMinutesIfValid`] 
| Add to this time interval the specified number of `minutes`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/addSeconds.adoc[`addSeconds`] 
| Add to this time interval the specified number of `seconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/addSecondsIfValid.adoc[`addSecondsIfValid`] 
| Add to this time interval the specified number of `seconds`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/bdexStreamIn.adoc[`bdexStreamIn`] 
| Assign to this object the value read from the specified input `stream` using the specified `version` format, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, this object is unaltered and `stream` is invalidated, but otherwise unmodified. If `version` is supported but `stream` becomes invalid during this operation, this object has an undefined, but valid, state. Note that no version is read from `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlt/DatetimeInterval/bdexStreamOut.adoc[`bdexStreamOut`] 
| Write the value of this object, using the specified `version` format, to the specified output `stream`, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, `stream` is invalidated, but otherwise unmodified. Note that `version` is not written to `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlt/DatetimeInterval/days.adoc[`days`] 
| Return the days field in the canonical representation of the value of this time interval. Note that the return value may be negative. Also note that the return value is the same as that returned by `totalDays`.
| xref:BloombergLP/bdlt/DatetimeInterval/fractionalDayInMicroseconds.adoc[`fractionalDayInMicroseconds`] 
| Return the value of this time interval as an integral number of microseconds modulo the number of microseconds in a day. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/hours.adoc[`hours`] 
| Return the hours field in the canonical representation of the value of this time interval. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/microseconds.adoc[`microseconds`] 
| Return the microseconds field in the canonical representation of the value of this time interval. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/milliseconds.adoc[`milliseconds`] 
| Return the milliseconds field in the canonical representation of the value of this time interval. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/minutes.adoc[`minutes`] 
| Return the minutes field in the canonical representation of the value of this time interval. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/operator_plus_eq.adoc[`operator+=`] 
| Add to this time interval the value of the specified `rhs` time interval, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/operator_minus_eq.adoc[`operator‐=`] 
| Subtract from this time interval the value of the specified `rhs` time interval, and return a reference providing modifiable access to this object. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/print.adoc[`print`] 
| Write the value of this object to the specified output `stream` in a human‐readable format, and return a reference to `stream`. Optionally specify an initial indentation `level`, whose absolute value is incremented recursively for nested objects. If `level` is specified, optionally specify `spacesPerLevel`, whose absolute value indicates the number of spaces per indentation level for this and all of its nested objects. If `level` is negative, suppress indentation of the first line. If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`). If `stream` is not valid on entry, this operation has no effect. Note that the format is not fully specified, and can change without notice.
| xref:BloombergLP/bdlt/DatetimeInterval/printToBuffer.adoc[`printToBuffer`] 
| Efficiently write to the specified `result` buffer no more than the specified `numBytes` of a representation of the value of this object. Optionally specify `fractionalSecondPrecision` digits to indicate how many fractional second digits to output. If `fractionalSecondPrecision` is not specified then 6 fractional second digits will be output (3 digits for milliseconds and 3 digits for microseconds). Return the number of characters (not including the null character) that would have been written if the limit due to `numBytes` were not imposed. `result` is null‐terminated unless `numBytes` is 0. The behavior is undefined unless `0 <= numBytes`, `0 <= fractionalSecondPrecision <= 6`, and `result` refers to at least `numBytes` contiguous bytes. Note that the return value is greater than or equal to `numBytes` if the output representation was truncated to avoid `result` overrun.
| xref:BloombergLP/bdlt/DatetimeInterval/seconds.adoc[`seconds`] 
| Return the seconds field in the canonical representation of the value of this time interval. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/setInterval.adoc[`setInterval`] 
| Set the time interval represented by this object to the value given by the specified `days`, and the optionally specified `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`. Unspecified arguments default to 0. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer). Note that the arguments may be supplied using a mixture of positive, negative, and 0 values.
| xref:BloombergLP/bdlt/DatetimeInterval/setIntervalIfValid.adoc[`setIntervalIfValid`] 
| Set the time interval represented by this object to the value given by the specified `days`, and the optionally specified `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`. Unspecified arguments default to 0. Return 0 if the resulting time interval value is valid (i.e., the `days` field must not overflow an `int`) and a non‐zero value (with no effect) otherwise. Note that the arguments may be supplied using a mixture of positive, negative, and 0 values.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalDays.adoc[`setTotalDays`] 
| Set the overall value of this object to indicate the specified number of `days`.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalHours.adoc[`setTotalHours`] 
| Set the overall value of this object to indicate the specified number of `hours`. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalHoursIfValid.adoc[`setTotalHoursIfValid`] 
| Set the overall value of this object to indicate the specified number of `hours`. Return 0 if the resulting time interval value is valid (i.e., the `days` field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalMicroseconds.adoc[`setTotalMicroseconds`] 
| Set the overall value of this object to indicate the specified number of `microseconds`. Note that there is no `setTotalMicrosecondsIfValid` because no value of `microseconds` can cause the number of days to overflow.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalMilliseconds.adoc[`setTotalMilliseconds`] 
| Set the overall value of this object to indicate the specified number of `milliseconds`. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalMillisecondsIfValid.adoc[`setTotalMillisecondsIfValid`] 
| Set the overall value of this object to indicate the specified number of `milliseconds`. Return 0 if the resulting time interval value is valid (i.e., the days field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalMinutes.adoc[`setTotalMinutes`] 
| Set the overall value of this object to indicate the specified number of `minutes`. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalMinutesIfValid.adoc[`setTotalMinutesIfValid`] 
| Set the overall value of this object to indicate the specified number of `minutes`. Return 0 if the resulting time interval value is valid (i.e., the `days` field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalSeconds.adoc[`setTotalSeconds`] 
| Set the overall value of this object to indicate the specified number of `seconds`. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalSecondsFromDouble.adoc[`setTotalSecondsFromDouble`] 
| Set the overall value of this object to indicate the specified number of `seconds`. The fractional part of `seconds`, if any, is rounded to the nearest whole number of microseconds. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalSecondsFromDoubleIfValid.adoc[`setTotalSecondsFromDoubleIfValid`] 
| Set the overall value of this object to indicate the specified number of `seconds`. The fractional part of `seconds`, if any, is rounded to the nearest whole number of microseconds. Return 0 if the resulting time interval value is valid (i.e., the `days` field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/setTotalSecondsIfValid.adoc[`setTotalSecondsIfValid`] 
| Set the overall value of this object to indicate the specified number of `seconds`. Return 0 if the resulting time interval value is valid (i.e., the `days` field must not overflow an `int`) and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/DatetimeInterval/streamOut.adoc[`streamOut`] 
| Format this datetime interval to the specified output `stream`, and return a reference to `stream`.
| xref:BloombergLP/bdlt/DatetimeInterval/totalDays.adoc[`totalDays`] 
| Return the value of this time interval in integral days, rounded toward 0. Note that the return value may be negative. Also note that the return value is the same as that returned by `days`.
| xref:BloombergLP/bdlt/DatetimeInterval/totalHours.adoc[`totalHours`] 
| Return the value of this time interval in integral hours, rounded toward 0. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/totalMicroseconds.adoc[`totalMicroseconds`] 
| Return the value of this time interval as an integral number of microseconds. The behavior is undefined unless the number of microseconds can be represented with a 64‐bit signed integer. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/totalMilliseconds.adoc[`totalMilliseconds`] 
| Return the value of this time interval in integral milliseconds, rounded towards zero. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/totalMinutes.adoc[`totalMinutes`] 
| Return the value of this time interval in integral minutes, rounded toward 0. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/totalSeconds.adoc[`totalSeconds`] 
| Return the value of this time interval in integral seconds, rounded toward 0. Note that the return value may be negative.
| xref:BloombergLP/bdlt/DatetimeInterval/totalSecondsAsDouble.adoc[`totalSecondsAsDouble`] 
| Return the value of this time interval in seconds as a `double`, potentially with a fractional part. Note that the return value may be negative. Also note that the conversion from the internal representation to `double` may _lose_ precision.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/DatetimeInterval/isValid.adoc[`isValid`] 
| Return `true` if a time interval object having the value given by the specified `days`, and the optionally specified `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds` can be represented as a `DatetimeInterval` and `false` otherwise. Unspecified arguments default to 0. The resulting time interval value is valid if the days field does not overflow a 32‐bit integer. Note that the arguments may be supplied using a mixture of positive, negative, and 0 values.
| xref:BloombergLP/bdlt/DatetimeInterval/maxSupportedBdexVersion-05.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| xref:BloombergLP/bdlt/DatetimeInterval/maxSupportedVersion.adoc[`maxSupportedVersion`] 
| Return the most current BDEX streaming version number supported by this class.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/DatetimeInterval/k_MILLISECONDS_MAX.adoc[`k_MILLISECONDS_MAX`] 
| The maximum interval that is representable by a `DatetimeInterval`, in milliseconds.
| xref:BloombergLP/bdlt/DatetimeInterval/k_MILLISECONDS_MIN.adoc[`k_MILLISECONDS_MIN`] 
| The minimum interval that is representable by a `DatetimeInterval`, in milliseconds.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlt/hashAppend-00f.adoc[BloombergLP::bdlt::hashAppend]`
| Pass the specified `object` to the specified `hashAlg`. This function integrates with the `bslh` modular hashing system and effectively provides a `bsl::hash` specialization for `DatetimeInterval`.
| `xref:BloombergLP/bdlt/operator_ge-071.adoc[BloombergLP::bdlt::operator>=]`
| Return `true` if the specified `lhs` interval is greater than or equal to the specified `rhs` interval, and `false` otherwise.
| `xref:BloombergLP/bdlt/operator_gt-0f.adoc[BloombergLP::bdlt::operator>]`
| Return `true` if the specified `lhs` interval is greater than the specified `rhs` interval, and `false` otherwise.
| `xref:BloombergLP/bdlt/operator_le-0d.adoc[BloombergLP::bdlt::operator<=]`
| Return `true` if the specified `lhs` interval is less than or equal to the specified `rhs` interval, and `false` otherwise.
| `xref:BloombergLP/bdlt/operator_lt-04.adoc[BloombergLP::bdlt::operator<]`
| Return `true` if the nominal relation between the specified `lhs` and `rhs` time interval values holds, and `false` otherwise. `lhs` is less than `rhs` if the following expression evaluates to `true`: ` lhs.days() < rhs.days() || (lhs.days() == rhs.days() && lhs.fractionalDayInMicroseconds() < rhs.fractionalDayInMicroseconds()) ` The other relationships are defined similarly.
| `xref:BloombergLP/bdlt/operator_not_eq-0a3.adoc[BloombergLP::bdlt::operator!=]`
| Return `true` if the specified `lhs` and `rhs` time intervals do not have the same value, and `false` otherwise. Two time intervals do not have the same value if any of the corresponding values of their days, hours, minutes, seconds, milliseconds, or microseconds fields is not the same.
| `xref:BloombergLP/bdlt/operator_eq-043.adoc[BloombergLP::bdlt::operator==]`
| Return `true` if the specified `lhs` and `rhs` time intervals have the same value, and `false` otherwise. Two time intervals have the same value if all of the corresponding values of their days, hours, minutes, seconds, milliseconds, and microseconds fields are the same.
| `xref:BloombergLP/bdlt/operator_minus-01.adoc[BloombergLP::bdlt::operator‐]`
| Return a `DatetimeInterval` object whose value is the negative of the specified time interval `value`. The behavior is undefined unless `INT_MIN < value.days()`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/operator_plus-087.adoc[`operator+`]
| Return a `Datetime` object having a value that is the sum of the specified `lhs` (`DatetimeInterval`) and the specified `rhs` (`Datetime`). If `24 == rhs.hour()`, the result is the same as if the `hour` attribute of `rhs` is 0. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object.
| xref:BloombergLP/bdlt/operator_plus-0b.adoc[`operator+`]
| Return a `Time` value that is the sum of the specified `lhs` datetime interval and the specified `rhs` time.
| xref:BloombergLP/bdlt/operator_plus-0d.adoc[`operator+`]
| Return a `DatetimeInterval` object whose value is the sum of the specified `lhs` and `rhs` time intervals. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
| xref:BloombergLP/bdlt/operator_minus-003.adoc[`operator‐`]
| Return a `DatetimeInterval` object initialized with the difference between the specified `lhs` and `rhs` time values.
| xref:BloombergLP/bdlt/operator_minus-0c.adoc[`operator‐`]
| Return a `DatetimeInterval` object having a value that is the difference between the specified `lhs` (`Datetime`) and the specified `rhs` (`Datetime`). If the `hour` attribute of either operand is 24, the result is the same as if that `hour` attribute is 0. The behavior is undefined unless the resulting value is in the valid range for a `DatetimeInterval` object.
| xref:BloombergLP/bdlt/operator_minus-0f.adoc[`operator‐`]
| Return a `DatetimeInterval` object whose value is the difference between the specified `lhs` and `rhs` time intervals. The behavior is undefined unless the resulting time interval value is valid (i.e., the days field must not overflow a 32‐bit integer).
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#