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

This `class` implements a value‐semantic type that represents the time of day to a resolution of one microsecond. Each object of this (almost) simply constrained attribute class _always_ represents a valid time value to a resolution of one microsecond. The valid range for times is 00:00:00.000000 through 23:59:59.999999, except that 24:00:00.000000 represents the default‐constructed value. The value 24:00:00.000000 behaves, in most cases, as if it were the value 00:00:00.000000; however, for all relational comparison operators, 24:00:00.000000 is not a valid argument and, therefore, would result in undefined behavior. Each add operation on a `Time` object returns the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed while performing the operation. Attempting to construct a `Time` with any attribute outside its valid range (or with an hour attribute value of 24 and any other attribute non‐zero) has undefined behavior.

== Synopsis

Declared in `<bdlt_time.h>`

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

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/Time/2constructor-07.adoc[`Time`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlt/Time/operator_assign.adoc[`operator=`] 
| Assign to this time object the value of the specified `rhs` object, and return a reference providing modifiable access to this object.
| xref:BloombergLP/bdlt/Time/addHours.adoc[`addHours`] 
| Increase the value of this time object by the specified number of `hours`, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Note that `hours` may be negative.
| xref:BloombergLP/bdlt/Time/addInterval.adoc[`addInterval`] 
| Increase the value of this time object by the specified `interval` of time, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. The behavior is undefined unless the number of crossings that would be returned can be represented by an `int`.
| xref:BloombergLP/bdlt/Time/addMicroseconds.adoc[`addMicroseconds`] 
| Increase the value of this time object by the specified number of `microseconds`, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Note that `microseconds` may be negative.
| xref:BloombergLP/bdlt/Time/addMilliseconds.adoc[`addMilliseconds`] 
| Increase the value of this time object by the specified number of `milliseconds`, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Note that `milliseconds` may be negative.
| xref:BloombergLP/bdlt/Time/addMinutes.adoc[`addMinutes`] 
| Increase the value of this time object by the specified number of `minutes`, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Note that `minutes` may be negative.
| xref:BloombergLP/bdlt/Time/addSeconds.adoc[`addSeconds`] 
| Increase the value of this time object by the specified number of `seconds`, and return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Note that `seconds` may be negative.
| xref:BloombergLP/bdlt/Time/addTime.adoc[`addTime`] 
| Add to the value of this time object the specified (signed) number of `hours`, and the optionally specified (signed) numbers of `minutes`, `seconds`, `milliseconds`, and `microseconds`; return the (signed) number of times that the 23:59:59.999999 ‐ 00:00:00.000000 boundary was crossed in performing the operation. Unspecified arguments default to 0.
| xref:BloombergLP/bdlt/Time/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/Time/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/Time/getTime.adoc[`getTime`] 
| Load, into the specified `hour`, and the optionally specified `minute`, `second`, `millisecond`, and `microsecond`, the respective `hour`, `minute`, `second`, `millisecond`, and `microsecond` attribute values from this time object. Unspecified arguments default to 0. Supplying 0 for an address argument suppresses the loading of the value for the corresponding attribute, but has no effect on the loading of other attribute values.
| xref:BloombergLP/bdlt/Time/hour.adoc[`hour`] 
| Return the value of the `hour` attribute of this time object.
| xref:BloombergLP/bdlt/Time/microsecond.adoc[`microsecond`] 
| Return the value of the `microsecond` attribute of this time object.
| xref:BloombergLP/bdlt/Time/millisecond.adoc[`millisecond`] 
| Return the value of the `millisecond` attribute of this time object.
| xref:BloombergLP/bdlt/Time/minute.adoc[`minute`] 
| Return the value of the `minute` attribute of this time object.
| xref:BloombergLP/bdlt/Time/operator_plus_eq.adoc[`operator+=`] 
| Add to this time object the value of the specified `rhs` datetime interval, and return a reference providing modifiable access to this object.
| xref:BloombergLP/bdlt/Time/operator_minus_eq.adoc[`operator‐=`] 
| Subtract from this time object the value of the specified `rhs` datetime interval, and return a reference providing modifiable access to this object.
| xref:BloombergLP/bdlt/Time/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 this human‐readable format is not fully specified, and can change without notice.
| xref:BloombergLP/bdlt/Time/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/Time/second.adoc[`second`] 
| Return the value of the `second` attribute of this time object.
| xref:BloombergLP/bdlt/Time/setHour.adoc[`setHour`] 
| Set the "hour" attribute of this time object to the specified `hour`; if `hour` is 24, set the remaining attributes of this object to 0. The behavior is undefined unless `0 <= hour <= 24`.
| xref:BloombergLP/bdlt/Time/setHourIfValid.adoc[`setHourIfValid`] 
| Set the "hour" attribute of this time object to the specified `hour` value _if_ `0 <= hour <= 24`. If `24 == hour`, set the remaining attributes to 0. Return 0 on success, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/Time/setMicrosecond.adoc[`setMicrosecond`] 
| Set the "microsecond" attribute of this time object to the specified `microsecond`; if the `hour` attribute is 24, set the `hour` attribute to 0. The behavior is undefined unless `0 <= microsecond < 1000`.
| xref:BloombergLP/bdlt/Time/setMicrosecondIfValid.adoc[`setMicrosecondIfValid`] 
| Set the "microsecond" attribute of this time object to the specified `microsecond` _if_ `0 <= microsecond < 1000`; if the `hour` attribute is 24, set the `hour` attribute to 0. Return 0 on success, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/Time/setMillisecond.adoc[`setMillisecond`] 
| Set the "millisecond" attribute of this time object to the specified `millisecond`; if the `hour` attribute is 24, set the `hour` attribute to 0. The behavior is undefined unless `0 <= millisecond < 1000`.
| xref:BloombergLP/bdlt/Time/setMillisecondIfValid.adoc[`setMillisecondIfValid`] 
| Set the "millisecond" attribute of this time object to the specified `millisecond` _if_ `0 <= millisecond < 1000`; if the `hour` attribute is 24, set the `hour` attribute to 0. Return 0 on success, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/Time/setMinute.adoc[`setMinute`] 
| Set the "minute" attribute of this time object to the specified `minute`; if the `hour` attribute is 24, set the `hour` attribute to 0. The behavior is undefined unless `0 <= minute < 60`.
| xref:BloombergLP/bdlt/Time/setMinuteIfValid.adoc[`setMinuteIfValid`] 
| Set the "minute" attribute of this time object to the specified `minute` _if_ `0 <= minute < 60`; if the `hour` attribute is 24, set the `hour` attribute to 0. Return 0 on success, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/Time/setSecond.adoc[`setSecond`] 
| Set the "second" attribute of this time object to the specified `second`; if the `hour` attribute is 24, set the `hour` attribute to 0. The behavior is undefined unless `0 <= second < 60`.
| xref:BloombergLP/bdlt/Time/setSecondIfValid.adoc[`setSecondIfValid`] 
| Set the "second" attribute of this time object to the specified `second` _if_ `0 <= second < 60`; if the `hour` attribute is 24, set the `hour` attribute to 0. Return 0 on success, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/bdlt/Time/setTime.adoc[`setTime`] 
| Set the value of this time object to the specified `hour`, and the optionally specified `minute`, `second`, `millisecond`, and `microsecond`. Unspecified arguments default to 0. The behavior is undefined unless all of the specified values are within their valid ranges (see `isValid`).
| xref:BloombergLP/bdlt/Time/setTimeIfValid.adoc[`setTimeIfValid`] 
| Set the value of this time object to the specified `hour`, and the optionally specified `minute`, `second`, `millisecond`, and `microsecond`, if they would comprise a valid `Time` value (see `isValid`). Return 0 on success, and a non‐zero value (with no effect) otherwise. Unspecified arguments default to 0.
| xref:BloombergLP/bdlt/Time/streamOut.adoc[`streamOut`] 
| Format this time to the specified output `stream`, and return a reference to the modifiable `stream`.
| xref:BloombergLP/bdlt/Time/validateAndSetTime.adoc[`validateAndSetTime`] 
| Set the value of this time object to the specified `hour`, and the optionally specified `minute`, `second`, and `millisecond`, if they would comprise a valid `Time` value (see `isValid`). Return 0 on success, and a non‐zero value (with no effect) otherwise. Unspecified arguments default to 0.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/Time/isValid.adoc[`isValid`] 
| Return `true` if the specified `hour`, and the optionally specified `minute`, `second`, `millisecond`, and `microsecond`, represent a valid `Time` value, and `false` otherwise. Unspecified arguments default to 0. The `hour`, `minute`, `second`, `millisecond`, and `microsecond` attributes comprise a valid `Time` value if `0 <= hour < 24`, `0 <= minute < 60`, `0 <= second < 60`, `0 <= millisecond < 1000`, and `0 <= microsecond < 1000`. Additionally, 24:00:00.000000 also represents a valid `Time` value.
| xref:BloombergLP/bdlt/Time/maxSupportedBdexVersion-06.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| xref:BloombergLP/bdlt/Time/maxSupportedVersion.adoc[`maxSupportedVersion`] 
| Return the most current BDEX streaming version number supported by this class.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlt/hashAppend-06d.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 `Time`.
| `xref:BloombergLP/bdlt/operator_gt-0a.adoc[BloombergLP::bdlt::operator>]`
| Return `true` if the specified `lhs` time value is greater than the specified `rhs` time value, and `false` otherwise. The behavior is undefined unless `lhs != Time()` and `rhs != Time()` (i.e., they do not have the, default, value 24:00:00.000000).
| `xref:BloombergLP/bdlt/operator_ge-0f.adoc[BloombergLP::bdlt::operator>=]`
| Return `true` if the specified `lhs` time value is greater than or equal to the specified `rhs` time value, and `false` otherwise. The behavior is undefined unless `lhs != Time()` and `rhs != Time()` (i.e., they do not have the, default, value 24:00:00.000000).
| `xref:BloombergLP/bdlt/operator_le-0f.adoc[BloombergLP::bdlt::operator<=]`
| Return `true` if the specified `lhs` time value is less than or equal to the specified `rhs` time value, and `false` otherwise. The behavior is undefined unless `lhs != Time()` and `rhs != Time()` (i.e., they do not have the, default, value 24:00:00.000000).
| `xref:BloombergLP/bdlt/operator_lt-0a.adoc[BloombergLP::bdlt::operator<]`
| Return `true` if the specified `lhs` time value is less than the specified `rhs` time value, and `false` otherwise. The behavior is undefined unless `lhs != Time()` and `rhs != Time()` (i.e., they do not have the, default, value 24:00:00.000000).
| `xref:BloombergLP/bdlt/operator_not_eq-0ad.adoc[BloombergLP::bdlt::operator!=]`
| Return `true` if the specified `lhs` and `rhs` time objects do not have the same value, and `false` otherwise. Two time objects do not have the same value if any of their corresponding `hour`, `minute`, `second`, `millisecond`, and `microsecond` attributes respectively do not have the same value.
| `xref:BloombergLP/bdlt/operator_eq-04c.adoc[BloombergLP::bdlt::operator==]`
| Return `true` if the specified `lhs` and `rhs` time objects have the same value, and `false` otherwise. Two time objects have the same value if each of their corresponding `hour`, `minute`, `second`, `millisecond`, and `microsecond` attributes respectively have the same value.
| `xref:BloombergLP/bdlt/operator_minus-003.adoc[BloombergLP::bdlt::operator‐]`
| Return a `DatetimeInterval` object initialized with the difference between the specified `lhs` and `rhs` time values.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/operator_plus-082.adoc[`operator+`]
| Return a `Time` value that is the sum of the specified `lhs` time and the specified `rhs` datetime interval.
| 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_minus-03.adoc[`operator‐`]
| Return a `Time` value that is the difference between the specified `lhs` time and the specified `rhs` datetime interval.
| xref:BloombergLP/bdlt/operator_lt-08c.adoc[`operator<`]
| Return `true` if the specified `lhs` has a value less than the specified `rhs`, and `false` otherwise. Time `lhs` has a value less than compactable transition `rhs` if `lhs < rhs.time()`. The behavior is undefined unless `24 > lhs.hour()`.
|===


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