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

This `class` implements a value&hyphen;semantic type that represents the time of day to a resolution of one microsecond&period; Each object of this (almost) simply constrained attribute class _always_ represents a valid time value to a resolution of one microsecond&period; The valid range for times is 00&colon;00&colon;00&period;000000 through 23&colon;59&colon;59&period;999999, except that 24&colon;00&colon;00&period;000000 represents the default&hyphen;constructed value&period; The value 24&colon;00&colon;00&period;000000 behaves, in most cases, as if it were the value 00&colon;00&colon;00&period;000000&semi; however, for all relational comparison operators, 24&colon;00&colon;00&period;000000 is not a valid argument and, therefore, would result in undefined behavior&period; Each add operation on a `Time` object returns the (signed) number of times that the 23&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed while performing the operation&period; 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&hyphen;zero) has undefined behavior&period;

== Synopsis

Declared in `&lt;bdlt&lowbar;time&period;h&gt;`

[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&equals;`] 
| Assign to this time object the value of the specified `rhs` object, and return a reference providing modifiable access to this object&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Note that `hours` may be negative&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; The behavior is undefined unless the number of crossings that would be returned can be represented by an `int`&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Note that `microseconds` may be negative&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Note that `milliseconds` may be negative&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Note that `minutes` may be negative&period;
| 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&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Note that `seconds` may be negative&period;
| 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`&semi; return the (signed) number of times that the 23&colon;59&colon;59&period;999999 &hyphen; 00&colon;00&colon;00&period;000000 boundary was crossed in performing the operation&period; Unspecified arguments default to 0&period;
| 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`&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/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`&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/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&period; Unspecified arguments default to 0&period; 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&period;
| xref:BloombergLP/bdlt/Time/hour.adoc[`hour`] 
| Return the value of the `hour` attribute of this time object&period;
| xref:BloombergLP/bdlt/Time/microsecond.adoc[`microsecond`] 
| Return the value of the `microsecond` attribute of this time object&period;
| xref:BloombergLP/bdlt/Time/millisecond.adoc[`millisecond`] 
| Return the value of the `millisecond` attribute of this time object&period;
| xref:BloombergLP/bdlt/Time/minute.adoc[`minute`] 
| Return the value of the `minute` attribute of this time object&period;
| xref:BloombergLP/bdlt/Time/operator_plus_eq.adoc[`operator&plus;&equals;`] 
| Add to this time object the value of the specified `rhs` datetime interval, and return a reference providing modifiable access to this object&period;
| xref:BloombergLP/bdlt/Time/operator_minus_eq.adoc[`operator&hyphen;&equals;`] 
| Subtract from this time object the value of the specified `rhs` datetime interval, and return a reference providing modifiable access to this object&period;
| xref:BloombergLP/bdlt/Time/print.adoc[`print`] 
| Write the value of this object to the specified output `stream` in a human&hyphen;readable format, and return a reference 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 this human&hyphen;readable format is not fully specified, and can change without notice&period;
| 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&period; Optionally specify `fractionalSecondPrecision` digits to indicate how many fractional second digits to output&period; If `fractionalSecondPrecision` is not specified then 6 fractional second digits will be output (3 digits for milliseconds and 3 digits for microseconds)&period; Return the number of characters (not including the null character) that would have been written if the limit due to `numBytes` were not imposed&period; `result` is null&hyphen;terminated unless `numBytes` is 0&period; The behavior is undefined unless `0 &lt;&equals; numBytes`, `0 &lt;&equals; fractionalSecondPrecision &lt;&equals; 6`, and `result` refers to at least `numBytes` contiguous bytes&period; Note that the return value is greater than or equal to `numBytes` if the output representation was truncated to avoid `result` overrun&period;
| xref:BloombergLP/bdlt/Time/second.adoc[`second`] 
| Return the value of the `second` attribute of this time object&period;
| xref:BloombergLP/bdlt/Time/setHour.adoc[`setHour`] 
| Set the &quot;hour&quot; attribute of this time object to the specified `hour`&semi; if `hour` is 24, set the remaining attributes of this object to 0&period; The behavior is undefined unless `0 &lt;&equals; hour &lt;&equals; 24`&period;
| xref:BloombergLP/bdlt/Time/setHourIfValid.adoc[`setHourIfValid`] 
| Set the &quot;hour&quot; attribute of this time object to the specified `hour` value _if_ `0 &lt;&equals; hour &lt;&equals; 24`&period; If `24 &equals;&equals; hour`, set the remaining attributes to 0&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period;
| xref:BloombergLP/bdlt/Time/setMicrosecond.adoc[`setMicrosecond`] 
| Set the &quot;microsecond&quot; attribute of this time object to the specified `microsecond`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; The behavior is undefined unless `0 &lt;&equals; microsecond &lt; 1000`&period;
| xref:BloombergLP/bdlt/Time/setMicrosecondIfValid.adoc[`setMicrosecondIfValid`] 
| Set the &quot;microsecond&quot; attribute of this time object to the specified `microsecond` _if_ `0 &lt;&equals; microsecond &lt; 1000`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period;
| xref:BloombergLP/bdlt/Time/setMillisecond.adoc[`setMillisecond`] 
| Set the &quot;millisecond&quot; attribute of this time object to the specified `millisecond`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; The behavior is undefined unless `0 &lt;&equals; millisecond &lt; 1000`&period;
| xref:BloombergLP/bdlt/Time/setMillisecondIfValid.adoc[`setMillisecondIfValid`] 
| Set the &quot;millisecond&quot; attribute of this time object to the specified `millisecond` _if_ `0 &lt;&equals; millisecond &lt; 1000`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period;
| xref:BloombergLP/bdlt/Time/setMinute.adoc[`setMinute`] 
| Set the &quot;minute&quot; attribute of this time object to the specified `minute`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; The behavior is undefined unless `0 &lt;&equals; minute &lt; 60`&period;
| xref:BloombergLP/bdlt/Time/setMinuteIfValid.adoc[`setMinuteIfValid`] 
| Set the &quot;minute&quot; attribute of this time object to the specified `minute` _if_ `0 &lt;&equals; minute &lt; 60`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period;
| xref:BloombergLP/bdlt/Time/setSecond.adoc[`setSecond`] 
| Set the &quot;second&quot; attribute of this time object to the specified `second`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; The behavior is undefined unless `0 &lt;&equals; second &lt; 60`&period;
| xref:BloombergLP/bdlt/Time/setSecondIfValid.adoc[`setSecondIfValid`] 
| Set the &quot;second&quot; attribute of this time object to the specified `second` _if_ `0 &lt;&equals; second &lt; 60`&semi; if the `hour` attribute is 24, set the `hour` attribute to 0&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period;
| 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`&period; Unspecified arguments default to 0&period; The behavior is undefined unless all of the specified values are within their valid ranges (see `isValid`)&period;
| 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`)&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period; Unspecified arguments default to 0&period;
| xref:BloombergLP/bdlt/Time/streamOut.adoc[`streamOut`] 
| Format this time to the specified output `stream`, and return a reference to the modifiable `stream`&period;
| 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`)&period; Return 0 on success, and a non&hyphen;zero value (with no effect) otherwise&period; Unspecified arguments default to 0&period;
|===


== 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&period; Unspecified arguments default to 0&period; The `hour`, `minute`, `second`, `millisecond`, and `microsecond` attributes comprise a valid `Time` value if `0 &lt;&equals; hour &lt; 24`, `0 &lt;&equals; minute &lt; 60`, `0 &lt;&equals; second &lt; 60`, `0 &lt;&equals; millisecond &lt; 1000`, and `0 &lt;&equals; microsecond &lt; 1000`&period; Additionally, 24&colon;00&colon;00&period;000000 also represents a valid `Time` value&period;
| 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&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlt/hashAppend-06d.adoc[BloombergLP::bdlt::hashAppend]`
| Pass the specified `object` to the specified `hashAlg`&period; This function integrates with the `bslh` modular hashing system and effectively provides a `bsl&colon;&colon;hash` specialization for `Time`&period;
| `xref:BloombergLP/bdlt/operator_gt-0a.adoc[BloombergLP::bdlt::operator&gt;]`
| Return `true` if the specified `lhs` time value is greater than the specified `rhs` time value, and `false` otherwise&period; The behavior is undefined unless `lhs !&equals; Time()` and `rhs !&equals; Time()` (i&period;e&period;, they do not have the, default, value 24&colon;00&colon;00&period;000000)&period;
| `xref:BloombergLP/bdlt/operator_ge-0f.adoc[BloombergLP::bdlt::operator&gt;&equals;]`
| Return `true` if the specified `lhs` time value is greater than or equal to the specified `rhs` time value, and `false` otherwise&period; The behavior is undefined unless `lhs !&equals; Time()` and `rhs !&equals; Time()` (i&period;e&period;, they do not have the, default, value 24&colon;00&colon;00&period;000000)&period;
| `xref:BloombergLP/bdlt/operator_le-0f.adoc[BloombergLP::bdlt::operator&lt;&equals;]`
| Return `true` if the specified `lhs` time value is less than or equal to the specified `rhs` time value, and `false` otherwise&period; The behavior is undefined unless `lhs !&equals; Time()` and `rhs !&equals; Time()` (i&period;e&period;, they do not have the, default, value 24&colon;00&colon;00&period;000000)&period;
| `xref:BloombergLP/bdlt/operator_lt-0a.adoc[BloombergLP::bdlt::operator&lt;]`
| Return `true` if the specified `lhs` time value is less than the specified `rhs` time value, and `false` otherwise&period; The behavior is undefined unless `lhs !&equals; Time()` and `rhs !&equals; Time()` (i&period;e&period;, they do not have the, default, value 24&colon;00&colon;00&period;000000)&period;
| `xref:BloombergLP/bdlt/operator_not_eq-0ad.adoc[BloombergLP::bdlt::operator!&equals;]`
| Return `true` if the specified `lhs` and `rhs` time objects do not have the same value, and `false` otherwise&period; 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&period;
| `xref:BloombergLP/bdlt/operator_eq-04c.adoc[BloombergLP::bdlt::operator&equals;&equals;]`
| Return `true` if the specified `lhs` and `rhs` time objects have the same value, and `false` otherwise&period; Two time objects have the same value if each of their corresponding `hour`, `minute`, `second`, `millisecond`, and `microsecond` attributes respectively have the same value&period;
| `xref:BloombergLP/bdlt/operator_minus-003.adoc[BloombergLP::bdlt::operator&hyphen;]`
| Return a `DatetimeInterval` object initialized with the difference between the specified `lhs` and `rhs` time values&period;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlt/operator_plus-082.adoc[`operator&plus;`]
| Return a `Time` value that is the sum of the specified `lhs` time and the specified `rhs` datetime interval&period;
| xref:BloombergLP/bdlt/operator_plus-0b.adoc[`operator&plus;`]
| Return a `Time` value that is the sum of the specified `lhs` datetime interval and the specified `rhs` time&period;
| xref:BloombergLP/bdlt/operator_minus-03.adoc[`operator&hyphen;`]
| Return a `Time` value that is the difference between the specified `lhs` time and the specified `rhs` datetime interval&period;
| xref:BloombergLP/bdlt/operator_lt-08c.adoc[`operator&lt;`]
| Return `true` if the specified `lhs` has a value less than the specified `rhs`, and `false` otherwise&period; Time `lhs` has a value less than compactable transition `rhs` if `lhs &lt; rhs&period;time()`&period; The behavior is undefined unless `24 &gt; lhs&period;hour()`&period;
|===


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