BloombergLP::bdlt::Datetime

This class implements a simply-constrained value-semantic type representing the composition of date and time values. Valid date values for the "date" part of a Datetime object are the same as those defined for Date objects; similarly, valid time values for the "time" part of a Datetime object are similar to those defined for Time objects (but with additional precision). Relational operators are disallowed on Datetime objects whose "time" part has the same value as that of a default constructed Time object.

Synopsis

Declared in <bdlt_datetime.h>

class Datetime;

Member Functions

Name	Description
`Datetime` [constructor]	Constructors
`operator=`	Assign to this object the value of the specified `rhs` object, and return a reference providing modifiable access to this object.
`addDays`	Add the specified number of `days` to the value of this object. Return a reference providing modifiable access to this object. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that this method has no effect on the "time" part of this object. Also note that `days` may be positive, 0, or negative.
`addDaysIfValid`	Add the specified number of `days` to the value of this object, if the resulting value is in the valid range for a `Datetime` object. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "time" part of this object. Also note that `days` may be positive, 0, or negative.
`addHours`	Add the specified number of `hours` to the value of this object, adjusting the "date" part of the object accordingly. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that `hours` may be positive, negative, or 0.
`addHoursIfValid`	Add the specified number of `hours` to the value of this object, adjusting the "date" part of the object accordingly, if the resulting value is in the valid range for a `Datetime` object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that `hours` may be positive, negative, or 0.
`addMicroseconds`	Add the specified number of `microseconds` to the value of this object, adjusting the "date" part of the object accordingly. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that `microseconds` may be positive, negative, or 0.
`addMicrosecondsIfValid`	Add the specified number of `microseconds` to the value of this object, adjusting the "date" part of the object accordingly, if the resulting value is in the valid range for a `Datetime` object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that `microseconds` may be positive, negative, or 0.
`addMilliseconds`	Add the specified number of `milliseconds` to the value of this object, adjusting the "date" part of the object accordingly. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that `milliseconds` may be positive, negative, or 0.
`addMillisecondsIfValid`	Add the specified number of `milliseconds` to the value of this object, adjusting the "date" part of the object accordingly, if the resulting value is in the valid range for a `Datetime` object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that `milliseconds` may be positive, negative, or 0.
`addMinutes`	Add the specified number of `minutes` to the value of this object, adjusting the "date" part of the object accordingly. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that `minutes` may be positive, negative, or 0.
`addMinutesIfValid`	Add the specified number of `minutes` to the value of this object, adjusting the "date" part of the object accordingly, if the resulting value is in the valid range for a `Datetime` object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that `minutes` may be positive, negative, or 0.
`addSeconds`	Add the specified number of `seconds` to the value of this object, adjusting the "date" part of the object accordingly. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that `seconds` may be positive, negative, or 0.
`addSecondsIfValid`	Add the specified number of `seconds` to the value of this object, adjusting the "date" part of the object accordingly, if the resulting value is in the valid range for a `Datetime` object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that `seconds` may be positive, negative, or 0.
`addTime`	Add the specified number of `hours`, and the optionally specified number of `minutes`, `seconds`, `milliseconds`, and `microseconds` to the value of this object, adjusting the "date" part of this object accordingly. Unspecified trailing optional parameters default to 0. Return a reference providing modifiable access to this object. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object. Note that each argument independently may be positive, negative, or 0.
`addTimeIfValid`	Add the specified number of `hours`, and the optionally specified number of `minutes`, `seconds`, `milliseconds`, and `microseconds` to the value of this object, adjusting the "date" part of this object accordingly, if the resulting value is in the valid range for a `Datetime` object. Unspecified trailing optional parameters default to 0. If `24 == hour()` on entry, set the `hour` attribute to 0 before performing the addition. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that each argument independently may be positive, negative, or 0.
`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.
`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.
`date`	Return the value of the "date" part of this object.
`day`	Return the value of the `day` (of the month) attribute of this object.
`dayOfWeek`	Return the value of the `dayOfWeek` attribute associated with the `day` (of the month) attribute of this object.
`dayOfYear`	Return the value of the `dayOfYear` attribute of this object.
`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.
`hour`	Return the value of the `hour` attribute of this object.
`microsecond`	Return the value of the `microsecond` attribute of this object.
`millisecond`	Return the value of the `millisecond` attribute of this object.
`minute`	Return the value of the `minute` attribute of this object.
`month`	Return the value of the `month` attribute of this object.
`operator+=`	Addition assignment operators
`operator-=`	Subtraction assignment operators
`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.
`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.
`second`	Return the value of the `second` attribute of this object.
`setDate`	Set the "date" part of this object to have the value of the specified `date`. Note that this method has no effect on the "time" part of this object.
`setDatetime`	`setDatetime` overloads
`setDatetimeIfValid`	`setDatetimeIfValid` overloads
`setHour`	Set the "hour" attribute of this object to the specified `hour` value. If `24 == hour`, set the `minute`, `second`, `millisecond`, and `microsecond` attributes to 0. The behavior is undefined unless `0 <= hour <= 24`. Note that this method has no effect on the "date" part of this object.
`setHourIfValid`	Set the "hour" attribute of this object to the specified `hour` value if `0 <= hour <= 24`. If `24 == hour`, set the `minute`, `second`, `millisecond`, and `microsecond` attributes to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setMicrosecond`	Set the "microsecond" attribute of this object to the specified `microsecond` value. If `24 == hour()`, set the `hour` attribute to 0. The behavior is undefined unless `0 <= microsecond <= 999`. Note that this method has no effect on the "date" part of this object.
`setMicrosecondIfValid`	Set the "microsecond" attribute of this object to the specified `microsecond` value if `0 <= microsecond <= 999`. If `24 == hour()`, set the `hour` attribute to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setMillisecond`	Set the "millisecond" attribute of this object to the specified `millisecond` value. If `24 == hour()`, set the `hour` attribute to 0. The behavior is undefined unless `0 <= millisecond <= 999`. Note that this method has no effect on the "date" part of this object.
`setMillisecondIfValid`	Set the "millisecond" attribute of this object to the specified `millisecond` value if `0 <= millisecond <= 999`. If `24 == hour()`, set the `hour` attribute to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setMinute`	Set the "minute" attribute of this object to the specified `minute` value. If `24 == hour()`, set the `hour` attribute to 0. The behavior is undefined unless `0 <= minute <= 59`. Note that this method has no effect on the "date" part of this object.
`setMinuteIfValid`	Set the "minute" attribute of this object to the specified `minute` value if `0 <= minute <= 59`. If `24 == hour()`, set the `hour` attribute to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setSecond`	Set the "second" attribute of this object to the specified `second` value. If `24 == hour()`, set the `hour` attribute to 0. The behavior is undefined unless `0 <= second <= 59`. Note that this method has no effect on the "date" part of this object.
`setSecondIfValid`	Set the "second" attribute of this object to the specified `second` value if `0 <= second <= 59`. If `24 == hour()`, set the `hour` attribute to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setTime`	`setTime` overloads
`setTimeIfValid`	Set the "time" part of this object to have the value represented by the specified `hour` attribute value and the optionally specified `minute`, `second`, `millisecond`, and `microsecond` attribute values if they comprise a valid "time" portion of a `DateTime` value. Unspecified trailing optional parameters default to 0. Return 0 on success, and a non-zero value (with no effect) otherwise. Note that this method has no effect on the "date" part of this object.
`setYearDay`	Set the "date" part of this object to have the value represented by the specified `year` and `dayOfYear` attribute values. The behavior is undefined unless `year` and `dayOfYear` represent a valid `Date` value (i.e., `true == Date::isValidYearDay(year, dayOfYear)`). Note that this method has no effect on the "time" part of this object.
`setYearDayIfValid`	Set this object to have the value represented by the specified `year` and `dayOfYear` if they comprise a valid `Date` value (see `Date::isValidYearDay`). Return 0 on success, and a non-zero value (with no effect) otherwise.
`setYearMonthDay`	Set the "date" part of this object to have the value represented by the specified `year`, `month`, and `day` attribute values. The behavior is undefined unless `year`, `month`, and `day` represent a valid `Date` value (i.e., `true == Date::isValidYearMonthDay(year, month, day)`). Note that this method has no effect on the "time" part of this object.
`setYearMonthDayIfValid`	Set this object to have the value represented by the specified `year`, `month`, and `day` if they comprise a valid `Date` value (see `Date::isValidYearMonthDay`). Return 0 on success, and a non-zero value (with no effect) otherwise.
`streamOut`	Format this datetime to the specified output `stream` and return a reference to the modifiable `stream`.
`time`	Return the value of the "time" part of this object.
`validateAndSetDatetime`	Set the "date" part of this object's value to the specified `year`, `month`, and `day`, and the "time" part to the optionally specified `hour`, `minute`, `second`, and `millisecond`, if they represent a valid `Datetime` value, with trailing fields that are not specified set to 0. Return 0 on success, and a non-zero value (with no effect) otherwise.
`year`	Return the value of the `year` attribute of this object.

Static Member Functions

Name	Description
`isValid`	Return `true` if the specified `year`, `month`, and `day` attribute values, and the optionally specified `hour`, `minute`, `second`, `millisecond`, and `microsecond` attribute values, represent a valid `Datetime` value, and `false` otherwise. Unspecified trailing optional parameters default to 0. `year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, and `microsecond` attribute values represent a valid `Datetime` value if `true == Date::isValidYearMonthDay(year, month, day)`, `0 <= hour < 24`, `0 <= minute < 60`, `0 <= second < 60`, `0 <= millisecond < 1000`, and `0 <= microsecond < 1000`. Additionally, a valid `year`, `month`, `day` with the time portion equal to 24:00:00.000000 also represents a valid `Datetime` value.
`maxSupportedBdexVersion`	`maxSupportedBdexVersion` overloads
`maxSupportedVersion`	Return the most current BDEX streaming version number supported by this class.

Friends

Name	Description
`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 `Datetime`.
`BloombergLP::bdlt::operator>=`	Return `true` if the value of the specified `lhs` object is greater than or equal to the value of the specified `rhs` object, and `false` otherwise. The behavior is undefined unless `24 != lhs.hour() && 24 != rhs.hour()`.
`BloombergLP::bdlt::operator>`	Return `true` if the value of the specified `lhs` object is greater than the value of the specified `rhs` object, and `false` otherwise. A `Datetime` object `a` is greater than a `Datetime` object `b` if `a.date() > b.date()`, or if `a.date() == b.date()` and the time portion of `a` is greater than the time portion of `b`. The behavior is undefined unless `24 != lhs.hour() && 24 != rhs.hour()`.
`BloombergLP::bdlt::operator<=`	Return `true` if the value of the specified `lhs` object is less than or equal to the value of the specified `rhs` object, and `false` otherwise. The behavior is undefined unless `24 != lhs.hour() && 24 != rhs.hour()`.
`BloombergLP::bdlt::operator<`	Return `true` if the value of the specified `lhs` object is less than the value of the specified `rhs` object, and `false` otherwise. A `Datetime` object `a` is less than a `Datetime` object `b` if `a.date() < b.date()`, or if `a.date() == b.date()` and the time portion of `a` is less than the time portion of `b`. The behavior is undefined unless `24 != lhs.hour() && 24 != rhs.hour()`.
`BloombergLP::bdlt::operator!=`	Return `true` if the specified `lhs` and `rhs` `Datetime` objects do not have the same value, and `false` otherwise. Two `Datetime` objects do not have the same value if they do not have the same values for either of their "date" or "time" parts, respectively.
`BloombergLP::bdlt::operator==`	Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `Datetime` objects have the same value if they have the same values for their "date" and "time" parts, respectively.
`BloombergLP::bdlt::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.

Non-Member Functions

Name	Description
`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.
`operator+`	Return a `Datetime` object having a value that is the sum of the specified `lhs` (`Datetime`) and the specified `rhs` (`bsls::TimeInterval`). If `24 == lhs.hour()`, the result is the same as if the `hour` attribute of `lhs` is 0. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object.
`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.
`operator+`	Return a `Datetime` object having a value that is the sum of the specified `lhs` (`Datetime`) and the specified `rhs` (`DatetimeInterval`). If `24 == lhs.hour()`, the result is the same as if the `hour` attribute of `lhs` is 0. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object.
`operator-`	Return a `Datetime` object having a value that is the difference between the specified `lhs` (`Datetime`) and the specified `rhs` (`bsls::TimeInterval`). If `24 == lhs.hour()`, the result is the same as if the `hour` attribute of `lhs` is 0. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object.
`operator-`	Return a `Datetime` object having a value that is the difference between the specified `lhs` (`Datetime`) and the specified `rhs` (`DatetimeInterval`). If `24 == lhs.hour()`, the result is the same as if the `hour` attribute of `lhs` is 0. The behavior is undefined unless the resulting value is in the valid range for a `Datetime` object.
`operator<`	Return `true` if the specified `lhs` has a value less than the specified `rhs`, and `false` otherwise. Datetime `lhs` has a value less than timetable transition `rhs` if `lhs < rhs.datetime()`. The behavior is undefined unless `24 > lhs.hour()`.