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().

Created with MrDocs