[#BloombergLP-bsls-TimeInterval]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bsls.adoc[bsls]::TimeInterval
:relfileprefix: ../../
:mrdocs:

Each instance of this value‐semantic type represents a time interval with nanosecond resolution. In the "canonical representation" of a time interval, the `seconds` field may have any 64‐bit signed integer value, with the `nanoseconds` field limited to the range `[ ‐999,999,999..999,999,999 ]`, and with the additional constraint that the two fields are either both non‐negative or both non‐positive.

== Synopsis

Declared in `<bsls_timeinterval.h>`

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

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/TimeInterval/2constructor-01.adoc[`TimeInterval`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bsls/TimeInterval/operator_assign.adoc[`operator=`] 
| Assign to this time interval the value of the specified `rhs` real number of seconds, and return a reference providing modifiable access to this object. The fractional part of `rhs`, if any, is rounded to the nearest whole number of nanoseconds. The behavior is undefined unless `rhs` can be converted to a valid `TimeInterval` object.
| xref:BloombergLP/bsls/TimeInterval/addDays.adoc[`addDays`] 
| Add to this time interval the number of seconds represented by the specified integral number of `days`, and return a reference providing modifiable access to this object. The behavior is undefined unless the number of seconds in `days`, and the total number of seconds in the resulting time interval, can both be represented with 64‐bit signed integers. Note that `days` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addDuration.adoc[`addDuration`] 
| Add to this time interval the specified `duration`. Return a reference providing modifiable access to this object. The behavior is undefined unless the `duration` can be converted to a valid `TimeInterval` object, whose `seconds` field may have any 64‐bit signed integer value and `nanoseconds` field limited to the range `[ ‐999,999,999..999,999,999 ]`. Also the behavior is undefined unless the total number of seconds in the resulting time interval can be represented with 64‐bit signed integer. Note that this operation is allowed only if representation type of the `duration` is not a floating point type and the `duration` itself can be _exactly_ represented by an integer nanoseconds.
| xref:BloombergLP/bsls/TimeInterval/addHours.adoc[`addHours`] 
| Add to this time interval the number of seconds represented by the specified integral number of `hours`, and return a reference providing modifiable access to this object. The behavior is undefined unless the number of seconds in `hours`, and the total number of seconds in the resulting time interval, can both be represented with 64‐bit signed integers. Note that `hours` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addInterval.adoc[`addInterval`] 
| Add to this time interval the specified integral number of `seconds`, and the optionally specified integral number of `nanoseconds`. If unspecified, `nanoseconds` is 0. Return a reference providing modifiable access to this object. The behavior is undefined unless `seconds() + seconds`, and the total number of seconds in the resulting time interval, can both be represented with 64‐bit signed integers.
| xref:BloombergLP/bsls/TimeInterval/addMicroseconds.adoc[`addMicroseconds`] 
| Add to this time interval the specified integral number of `microseconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64‐bit signed integer. Note that `microseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addMilliseconds.adoc[`addMilliseconds`] 
| Add to this time interval the specified integral number of `milliseconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64‐bit signed integer. Note that `milliseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addMinutes.adoc[`addMinutes`] 
| Add to this time interval the number of seconds represented by the specified integral number of `minutes`, and return a reference providing modifiable access to this object. The behavior is undefined unless the number of seconds in `minutes`, and the total number of seconds in the resulting time interval, can both be represented with 64‐bit signed integers. Note that `minutes` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addNanoseconds.adoc[`addNanoseconds`] 
| Add to this time interval the specified integral number of `nanoseconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64‐bit signed integer. Note that `nanoseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/addSeconds.adoc[`addSeconds`] 
| Add to this time interval the specified integral number of `seconds`, and return a reference providing modifiable access to this object. The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64‐bit signed integer. Note that `seconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/asDuration.adoc[`asDuration`] 
| Return the value of this time interval as a `std::chrono::duration` object. This function participates in overloading if `DURATION_TYPE` is actually an `std::chrono::duration` instance, and if it has _not_ a floating point representation. The behavior is undefined unless the total number of nanoseconds can be represented using a `DURATION_TYPE`. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/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/bsls/TimeInterval/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/bsls/TimeInterval/isInDurationRange.adoc[`isInDurationRange`] 
| Return `true` if the value of this time interval is within the valid range of the parameterized `DURATION_TYPE`, and `false` otherwise. Note that this function does not participate in overload resolution unless `DURATION_TYPE` is an instantiation of `std::chrono::duration`.
| xref:BloombergLP/bsls/TimeInterval/nanoseconds.adoc[`nanoseconds`] 
| Return the nanoseconds field in the canonical representation of the value of this time interval.
| xref:BloombergLP/bsls/TimeInterval/operator_plus_eq-02.adoc[`operator+=`] 
| Addition assignment operators
| xref:BloombergLP/bsls/TimeInterval/operator_minus_eq-0f.adoc[`operator‐=`] 
| Subtraction assignment operators
| xref:BloombergLP/bsls/TimeInterval/print.adoc[`print`] 
| Write the value of this object to the specified output `stream` in a human‐readable format, and return a reference providing modifiable access 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/bsls/TimeInterval/seconds.adoc[`seconds`] 
| Return the seconds field in the canonical representation of the value of this time interval.
| xref:BloombergLP/bsls/TimeInterval/setInterval.adoc[`setInterval`] 
| Set this time interval to have the value given by the sum of the specified integral number of `seconds`, and the optionally specified integral number of `nanoseconds`. If unspecified, `nanoseconds` is 0. The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64‐bit signed integer (see `isValid`). Note that there is no restriction on the sign or magnitude of either argument except that they must not violate the method's preconditions.
| xref:BloombergLP/bsls/TimeInterval/setIntervalRaw.adoc[`setIntervalRaw`] 
| Set this time interval to have the value given by the sum of the specified integral number of `seconds`, and the optionally specified integral number of `nanoseconds`, where `seconds` and `nanoseconds` form a canonical representation of a time interval (see {Representation}). If unspecified, `nanoseconds` is 0. The behavior is undefined unless `‐999,999,999 <= nanoseconds <= +999,999,999` and `seconds` and `nanoseconds` are either both non‐negative or both non‐positive. Note that this function provides a subset of the defined behavior of `setInterval` chosen to minimize runtime performance cost.
| xref:BloombergLP/bsls/TimeInterval/setTotalDays.adoc[`setTotalDays`] 
| Set the overall value of this object to indicate the specified integral number of `days`. The behavior is undefined unless the number of seconds in `days` can be represented with a 64‐bit signed integer. Note that `days` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalHours.adoc[`setTotalHours`] 
| Set the overall value of this object to indicate the specified integral number of `hours`. The behavior is undefined unless the number of seconds in `hours` can be represented with a 64‐bit signed integer. Note that `hours` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalMicroseconds.adoc[`setTotalMicroseconds`] 
| Set the overall value of this object to indicate the specified integral number of `microseconds`. Note that `microseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalMilliseconds.adoc[`setTotalMilliseconds`] 
| Set the overall value of this object to indicate the specified integral number of `milliseconds`. Note that `milliseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalMinutes.adoc[`setTotalMinutes`] 
| Set the overall value of this object to indicate the specified integral number of `minutes`. The behavior is undefined unless the number of seconds in `minutes` can be represented with a 64‐bit signed integer. Note that `minutes` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalNanoseconds.adoc[`setTotalNanoseconds`] 
| Set the overall value of this object to indicate the specified integral number of `nanoseconds`. Note that `nanoseconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/setTotalSeconds.adoc[`setTotalSeconds`] 
| Set the overall value of this object to indicate the specified integral number of `seconds`. Note that `seconds` may be negative.
| xref:BloombergLP/bsls/TimeInterval/streamOut.adoc[`streamOut`] 
| Format this time to the specified output `stream`, and return a reference to the modifiable `stream`.
| xref:BloombergLP/bsls/TimeInterval/totalDays.adoc[`totalDays`] 
| Return the value of this time interval as an integral number of days, rounded towards zero. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/totalHours.adoc[`totalHours`] 
| Return the value of this time interval as an integral number of hours, rounded towards zero. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/totalMicroseconds.adoc[`totalMicroseconds`] 
| Return the value of this time interval as an integral number of microseconds, rounded towards zero. 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/bsls/TimeInterval/totalMilliseconds.adoc[`totalMilliseconds`] 
| Return the value of this time interval as an integral number of milliseconds, rounded towards zero. The behavior is undefined unless the number of milliseconds can be represented with a 64‐bit signed integer. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/totalMinutes.adoc[`totalMinutes`] 
| Return the value of this time interval as an integral number of minutes, rounded towards zero. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/totalNanoseconds.adoc[`totalNanoseconds`] 
| Return the value of this time interval as an integral number of nanoseconds. The behavior is undefined unless the number of nanoseconds can be represented using a 64‐bit signed integer. Note that the return value may be negative.
| xref:BloombergLP/bsls/TimeInterval/totalSeconds.adoc[`totalSeconds`] 
| Return the value of this time interval as an integral number of seconds, rounded towards zero. Note that the return value may be negative. Also note that this method returns the same value as `seconds`.
| xref:BloombergLP/bsls/TimeInterval/totalSecondsAsDouble.adoc[`totalSecondsAsDouble`] 
| Return the value of this time interval as a real number of seconds. Note that the return value may be negative and may have a fractional part (representing the nanosecond field of this object). Also note that the conversion from the internal representation to a `double` may _lose_ precision.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/TimeInterval/isValid-07.adoc[`isValid`] 
| `isValid` overloads
| xref:BloombergLP/bsls/TimeInterval/maxSupportedBdexVersion-00.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| xref:BloombergLP/bsls/TimeInterval/maxSupportedVersion.adoc[`maxSupportedVersion`] 
| Return the most current BDEX streaming version number supported by this class.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/operator_not_eq-05.adoc[`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 their respective second or nanosecond fields differ in value. The behavior is undefined unless operands of type `double` can be converted to valid `TimeInterval` objects.
| xref:BloombergLP/bsls/operator_not_eq-0ba.adoc[`operator!=`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_h.adoc[`operator""_h`]
| This user defined literal operator converts the specified `hours` value to the respective `TimeInterval` value. The behavior is undefined unless the specified number of hours can be converted to valid `TimeInterval` object. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_min.adoc[`operator""_min`]
| This user defined literal operator converts the specified `minutes` value to the respective `TimeInterval` value. The behavior is undefined unless the specified number of minutes can be converted to valid `TimeInterval` object. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_ms.adoc[`operator""_ms`]
| This user defined literal operator converts the specified `milliseconds` value to the respective `TimeInterval` value. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_ns.adoc[`operator""_ns`]
| This user defined literal operator converts the specified `nanoseconds` value to the respective `TimeInterval` value. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_s.adoc[`operator""_s`]
| This user defined literal operator converts the specified `seconds` value to the respective `TimeInterval` value. The behavior is undefined unless the specified number of seconds can be converted to valid `TimeInterval` object. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_us.adoc[`operator""_us`]
| This user defined literal operator converts the specified `microseconds` value to the respective `TimeInterval` value. (See the "User‐Defined Literals" section in the component‐level documentation.)
| xref:BloombergLP/bsls/operator_plus-01.adoc[`operator+`]
| Return a `TimeInterval` value that is the sum of the specified `lhs` and `rhs` time intervals. The behavior is undefined unless (1) operands of type `double` can be converted to valid `TimeInterval` objects, and (2) the resulting time interval can be represented with a 64‐bit signed integer.
| xref:BloombergLP/bsls/operator_plus-0ca.adoc[`operator+`]
| Same as the preceding overload, converting `lhs` from `double`.
| xref:BloombergLP/bsls/operator_plus-0cf.adoc[`operator+`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_minus-003.adoc[`operator‐`]
| Return a `TimeInterval` value that is the negative of the specified `rhs` time interval. The behavior is undefined unless `LLONG_MIN != rhs.seconds()`.
| xref:BloombergLP/bsls/operator_minus-04.adoc[`operator‐`]
| Return a `TimeInterval` value that is the difference between the specified `lhs` and `rhs` time intervals. The behavior is undefined unless (1) operands of type `double` can be converted to valid `TimeInterval` objects, (2) the value on the right‐hand side (potentially after conversion to a `TimeInterval`) has a number of seconds that is not `LLONG_MIN`, and (3) the resulting time interval can be represented with a 64‐bit signed integer.
| xref:BloombergLP/bsls/operator_minus-0a.adoc[`operator‐`]
| Same as the preceding overload, converting `lhs` from `double`.
| xref:BloombergLP/bsls/operator_minus-0e.adoc[`operator‐`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_lt-01.adoc[`operator<`]
| Return `true` if the nominal relation between the specified `lhs` and `rhs` time interval values holds, and `false` otherwise. The behavior is undefined unless operands of type `double` can be converted to valid `TimeInterval` objects.
| xref:BloombergLP/bsls/operator_lt-022.adoc[`operator<`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_le-07.adoc[`operator<=`]
| Same as the preceding overload.
| xref:BloombergLP/bsls/operator_le-08.adoc[`operator<=`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_eq-0a.adoc[`operator==`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_eq-0e.adoc[`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 their respective second and nanosecond fields have the same value. The behavior is undefined unless operands of type `double` can be converted to valid `TimeInterval` objects.
| xref:BloombergLP/bsls/operator_gt-02.adoc[`operator>`]
| Same as the preceding overload.
| xref:BloombergLP/bsls/operator_gt-06.adoc[`operator>`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_ge-05.adoc[`operator>=`]
| Same as the preceding overload, converting `rhs` from `double`.
| xref:BloombergLP/bsls/operator_ge-07.adoc[`operator>=`]
| Same as the preceding overload.
| xref:BloombergLP/bdlt/operator_plus-069.adoc[`::BloombergLP::bdlt::operator+`]
| Return a `Datetime` object having a value that is the sum of the specified `lhs` (`bsls::TimeInterval`) 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.
|===


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