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

Each instance of this value&hyphen;semantic type represents a time interval with nanosecond resolution&period; In the &quot;canonical representation&quot; of a time interval, the `seconds` field may have any 64&hyphen;bit signed integer value, with the `nanoseconds` field limited to the range `&lsqb; &hyphen;999,999,999&period;&period;999,999,999 &rsqb;`, and with the additional constraint that the two fields are either both non&hyphen;negative or both non&hyphen;positive&period;

== Synopsis

Declared in `&lt;bsls&lowbar;timeinterval&period;h&gt;`

[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&equals;`] 
| 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&period; The fractional part of `rhs`, if any, is rounded to the nearest whole number of nanoseconds&period; The behavior is undefined unless `rhs` can be converted to a valid `TimeInterval` object&period;
| 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&period; 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&hyphen;bit signed integers&period; Note that `days` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/addDuration.adoc[`addDuration`] 
| Add to this time interval the specified `duration`&period; Return a reference providing modifiable access to this object&period; The behavior is undefined unless the `duration` can be converted to a valid `TimeInterval` object, whose `seconds` field may have any 64&hyphen;bit signed integer value and `nanoseconds` field limited to the range `&lsqb; &hyphen;999,999,999&period;&period;999,999,999 &rsqb;`&period; Also the behavior is undefined unless the total number of seconds in the resulting time interval can be represented with 64&hyphen;bit signed integer&period; 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&period;
| 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&period; 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&hyphen;bit signed integers&period; Note that `hours` may be negative&period;
| 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`&period; If unspecified, `nanoseconds` is 0&period; Return a reference providing modifiable access to this object&period; The behavior is undefined unless `seconds() &plus; seconds`, and the total number of seconds in the resulting time interval, can both be represented with 64&hyphen;bit signed integers&period;
| 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&period; The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64&hyphen;bit signed integer&period; Note that `microseconds` may be negative&period;
| 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&period; The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64&hyphen;bit signed integer&period; Note that `milliseconds` may be negative&period;
| 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&period; 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&hyphen;bit signed integers&period; Note that `minutes` may be negative&period;
| 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&period; The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64&hyphen;bit signed integer&period; Note that `nanoseconds` may be negative&period;
| 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&period; The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64&hyphen;bit signed integer&period; Note that `seconds` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/asDuration.adoc[`asDuration`] 
| Return the value of this time interval as a `std&colon;&colon;chrono&colon;&colon;duration` object&period; This function participates in overloading if `DURATION&lowbar;TYPE` is actually an `std&colon;&colon;chrono&colon;&colon;duration` instance, and if it has _not_ a floating point representation&period; The behavior is undefined unless the total number of nanoseconds can be represented using a `DURATION&lowbar;TYPE`&period; Note that the return value may be negative&period;
| 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`&period; If `stream` is initially invalid, this operation has no effect&period; If `version` is not supported, this object is unaltered and `stream` is invalidated, but otherwise unmodified&period; If `version` is supported but `stream` becomes invalid during this operation, this object has an undefined, but valid, state&period; Note that no version is read from `stream`&period; See the `bslx` package&hyphen;level documentation for more information on BDEX streaming of value&hyphen;semantic types and containers&period;
| 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`&period; If `stream` is initially invalid, this operation has no effect&period; If `version` is not supported, `stream` is invalidated, but otherwise unmodified&period; Note that `version` is not written to `stream`&period; See the `bslx` package&hyphen;level documentation for more information on BDEX streaming of value&hyphen;semantic types and containers&period;
| 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&lowbar;TYPE`, and `false` otherwise&period; Note that this function does not participate in overload resolution unless `DURATION&lowbar;TYPE` is an instantiation of `std&colon;&colon;chrono&colon;&colon;duration`&period;
| xref:BloombergLP/bsls/TimeInterval/nanoseconds.adoc[`nanoseconds`] 
| Return the nanoseconds field in the canonical representation of the value of this time interval&period;
| xref:BloombergLP/bsls/TimeInterval/operator_plus_eq-02.adoc[`operator&plus;&equals;`] 
| Addition assignment operators
| xref:BloombergLP/bsls/TimeInterval/operator_minus_eq-0f.adoc[`operator&hyphen;&equals;`] 
| Subtraction assignment operators
| xref:BloombergLP/bsls/TimeInterval/print.adoc[`print`] 
| Write the value of this object to the specified output `stream` in a human&hyphen;readable format, and return a reference providing modifiable access to `stream`&period; Optionally specify an initial indentation `level`, whose absolute value is incremented recursively for nested objects&period; 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&period; If `level` is negative, suppress indentation of the first line&period; If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`)&period; If `stream` is not valid on entry, this operation has no effect&period; Note that the format is not fully specified, and can change without notice&period;
| xref:BloombergLP/bsls/TimeInterval/seconds.adoc[`seconds`] 
| Return the seconds field in the canonical representation of the value of this time interval&period;
| 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`&period; If unspecified, `nanoseconds` is 0&period; The behavior is undefined unless the total number of seconds in the resulting time interval can be represented with a 64&hyphen;bit signed integer (see `isValid`)&period; Note that there is no restriction on the sign or magnitude of either argument except that they must not violate the method&apos;s preconditions&period;
| 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 &lcub;Representation&rcub;)&period; If unspecified, `nanoseconds` is 0&period; The behavior is undefined unless `&hyphen;999,999,999 &lt;&equals; nanoseconds &lt;&equals; &plus;999,999,999` and `seconds` and `nanoseconds` are either both non&hyphen;negative or both non&hyphen;positive&period; Note that this function provides a subset of the defined behavior of `setInterval` chosen to minimize runtime performance cost&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalDays.adoc[`setTotalDays`] 
| Set the overall value of this object to indicate the specified integral number of `days`&period; The behavior is undefined unless the number of seconds in `days` can be represented with a 64&hyphen;bit signed integer&period; Note that `days` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalHours.adoc[`setTotalHours`] 
| Set the overall value of this object to indicate the specified integral number of `hours`&period; The behavior is undefined unless the number of seconds in `hours` can be represented with a 64&hyphen;bit signed integer&period; Note that `hours` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalMicroseconds.adoc[`setTotalMicroseconds`] 
| Set the overall value of this object to indicate the specified integral number of `microseconds`&period; Note that `microseconds` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalMilliseconds.adoc[`setTotalMilliseconds`] 
| Set the overall value of this object to indicate the specified integral number of `milliseconds`&period; Note that `milliseconds` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalMinutes.adoc[`setTotalMinutes`] 
| Set the overall value of this object to indicate the specified integral number of `minutes`&period; The behavior is undefined unless the number of seconds in `minutes` can be represented with a 64&hyphen;bit signed integer&period; Note that `minutes` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalNanoseconds.adoc[`setTotalNanoseconds`] 
| Set the overall value of this object to indicate the specified integral number of `nanoseconds`&period; Note that `nanoseconds` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/setTotalSeconds.adoc[`setTotalSeconds`] 
| Set the overall value of this object to indicate the specified integral number of `seconds`&period; Note that `seconds` may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/streamOut.adoc[`streamOut`] 
| Format this time to the specified output `stream`, and return a reference to the modifiable `stream`&period;
| xref:BloombergLP/bsls/TimeInterval/totalDays.adoc[`totalDays`] 
| Return the value of this time interval as an integral number of days, rounded towards zero&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalHours.adoc[`totalHours`] 
| Return the value of this time interval as an integral number of hours, rounded towards zero&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalMicroseconds.adoc[`totalMicroseconds`] 
| Return the value of this time interval as an integral number of microseconds, rounded towards zero&period; The behavior is undefined unless the number of microseconds can be represented with a 64&hyphen;bit signed integer&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalMilliseconds.adoc[`totalMilliseconds`] 
| Return the value of this time interval as an integral number of milliseconds, rounded towards zero&period; The behavior is undefined unless the number of milliseconds can be represented with a 64&hyphen;bit signed integer&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalMinutes.adoc[`totalMinutes`] 
| Return the value of this time interval as an integral number of minutes, rounded towards zero&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalNanoseconds.adoc[`totalNanoseconds`] 
| Return the value of this time interval as an integral number of nanoseconds&period; The behavior is undefined unless the number of nanoseconds can be represented using a 64&hyphen;bit signed integer&period; Note that the return value may be negative&period;
| xref:BloombergLP/bsls/TimeInterval/totalSeconds.adoc[`totalSeconds`] 
| Return the value of this time interval as an integral number of seconds, rounded towards zero&period; Note that the return value may be negative&period; Also note that this method returns the same value as `seconds`&period;
| xref:BloombergLP/bsls/TimeInterval/totalSecondsAsDouble.adoc[`totalSecondsAsDouble`] 
| Return the value of this time interval as a real number of seconds&period; Note that the return value may be negative and may have a fractional part (representing the nanosecond field of this object)&period; Also note that the conversion from the internal representation to a `double` may _lose_ precision&period;
|===


== 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&period;
|===


== Non-Member Functions

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


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