Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
DateTime Struct Reference

Represents an instant in time, typically expressed as a date and time of day. More...

#include <DateTime.h>

Classes

struct  Info
 Provides the metadata portion of a DateTime object. More...
 

Public Types

enum  Kind { Unspecified = 0, Utc = 1, Local = 2 }
 Specifies whether a DateTime represents a local time, a Coordinated Universal Time (UTC), or is not specified as either local time or UTC. More...
 
enum  Component { Date = 0, DateAndTime = 1 }
 Specifies whether a DateTime represents a date (without time component) or a date time. More...
 
enum  DayOfWeek {
  Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3,
  Thursday = 4, Friday = 5, Saturday = 6
}
 Specifies the days of the week. More...
 
enum  CompareResult { EarlierThan, Equals, LaterThan, Error }
 Result of comparing two DateTimes. More...
 

Public Member Functions

 DateTime ()
 Initializes a new empty instance of the DateTime struct. More...
 
 DateTime (Int16 year, UInt8 month, UInt8 day)
 Initializes a new instance of the DateTime struct. More...
 
 DateTime (Kind kind, Int16 year, UInt8 month, UInt8 day, UInt8 hour, UInt8 minute, UInt8 second=0, UInt32 hectoNanosecond=0)
 Initializes a new instance of the DateTime struct. More...
 
bool IsValid () const
 Indicates whether this DateTime instance is a valid date/time or not. More...
 
bool operator== (DateTime const &rhs) const
 Compares the given DateTime with this DateTime. More...
 
bool operator!= (DateTime const &rhs) const
 Checks the given DateTime with this DateTime for inequality. More...
 
bool Equals (DateTime const &rhs, bool ignoreDateTimeInfo=false) const
 Compares the given DateTime with this DateTime. More...
 

Static Public Member Functions

static CompareResult Compare (DateTime const &lhs, DateTime const &rhs)
 Compares two DateTimes. More...
 

Current time

static DateTime GetCurrentTime ()
 Gets the current system time in local time. More...
 
static DateTime GetCurrentTimeUtc ()
 Gets the current system time in UTC. More...
 

Julian Day Conversion

The Julian Day is the count of days and fractions since noon on November 24, 4714 BCE UTC proleptic Gregorian calendar (-4713-11-24 12:00:00 UTC).

See Julian Day for details. If the date to convert to Julian Day is in local time, the DateTime is converted from local time to UTC. The time zone conversion works fine on most of the platforms within the Unix epoch only (1970-01-01 00:00:00 UTC through 2038-01-19 03:14:07 UTC). For dates outside this epoch the offset computation is performed by using a default date within the epoch (2000-01-01 00:00:00 UTC). In some cases this can lead to wrong offset computations and consequently to wrong Julian Day numbers. Clients can avoid this by using UTC date times for dates outside this epoch.

BentleyStatus ToJulianDay (UInt64 &julianDayInHns) const
 Computes the Julian Day number in hecto-nanoseconds from this DateTime instance. More...
 
BentleyStatus ToJulianDay (double &julianDay) const
 Computes the Julian Day number from this DateTime instance. More...
 
static BentleyStatus FromJulianDay (DateTime &dateTime, UInt64 julianDayInHns, Info const &targetInfo)
 Computes the DateTime from the given Julian Day number. More...
 
static BentleyStatus FromJulianDay (DateTime &dateTime, double julianDay, Info const &targetInfo)
 Computes the DateTime from the given Julian Day number. More...
 

Conversions

BentleyStatus ToUtc (DateTime &utcDateTime) const
 Converts this local DateTime to UTC. More...
 
BentleyStatus ToLocalTime (DateTime &localDateTime) const
 Converts this UTC DateTime to local time. More...
 
BentleyStatus ToUnixMilliseconds (Int64 &unixMilliseconds) const
 Converts this DateTime to Unix epoch milliseconds (UTC). More...
 
BentleyStatus ToCommonEraTicks (Int64 &commonEraTicks) const
 Computes the Common Era ticks from this DateTime instance. More...
 
static BentleyStatus FromUnixMilliseconds (DateTime &dateTime, UInt64 unixMilliseconds)
 Creates a DateTime in UTC from the given Unix epoch milliseconds. More...
 
static Int64 JulianDayToUnixMilliseconds (UInt64 julianDayInHectoNanoseconds)
 Computes the Unix milliseconds from the given Julian Day number. More...
 
static UInt64 UnixMillisecondsToJulianDay (UInt64 unixMilliseconds)
 Computes the Julian Day number from the given Unix milliseconds. More...
 
static BentleyStatus FromCommonEraTicks (DateTime &dateTime, Int64 commonEraTicks, Info const &targetInfo)
 Computes the DateTime from the given Common Era ticks. More...
 
static Int64 JulianDayToCommonEraTicks (UInt64 julianDayInHectoNanoseconds)
 Computes Common Era ticks from the given the Julian Day number. More...
 
static UInt64 CommonEraTicksToJulianDay (Int64 commonEraTicks)
 Computes the Julian Day number from the given Common Era ticks. More...
 

ToString and FromString

Utf8String ToUtf8String () const
 Converts the value of this DateTime into a string representation. More...
 
WString ToString () const
 Converts the value of this DateTime into a string representation. More...
 
static BentleyStatus FromString (DateTime &dateTime, Utf8CP dateTimeIso8601)
 Parses an ISO 8601 date time string into a DateTime instance. More...
 
static BentleyStatus FromString (DateTime &dateTime, WCharCP dateTimeIso8601)
 Parses an ISO 8601 date time string into a DateTime instance. More...
 

DateTime components

Info const & GetInfo () const
 Gets meta data about this DateTime object. More...
 
Int16 GetYear () const
 Gets the year component of this DateTime object. More...
 
UInt8 GetMonth () const
 Gets the month component of this DateTime object. More...
 
UInt8 GetDay () const
 Gets the day component of this DateTime object. More...
 
UInt8 GetHour () const
 Gets the hour component of this DateTime object. More...
 
UInt8 GetMinute () const
 Gets the minute component of this DateTime object. More...
 
UInt8 GetSecond () const
 Gets the second component of this DateTime object. More...
 
UInt16 GetMillisecond () const
 Gets the milliseconds component of this DateTime object. More...
 
UInt32 GetHectoNanosecond () const
 Gets the hecto-nanosecond component of this DateTime object. More...
 
DayOfWeek GetDayOfWeek () const
 Gets the day of the week of this DateTime object. More...
 
UInt16 GetDayOfYear () const
 Gets the day of the year of this DateTime object. More...
 
BentleyStatus ComputeOffsetToUtcInHns (Int64 &offset) const
 If this object is of kind Local, this computes the offset from local time to UTC in HNS (hectonanoseconds). Otherwise, it sets the parameter to 0. More...
 
static bool IsLeapYear (UInt16 year)
 Indicates whether the specified year is a leap year or not. More...
 

Detailed Description

Represents an instant in time, typically expressed as a date and time of day.

A DateTime also holds additional metadata about the actual date time in its DateTime::Info member.

A DateTime's accuracy is 100's of nanoseconds (i.e hecto-nanoseconds, i.e. 1e-7 seconds)

Member Enumeration Documentation

enum CompareResult
strong

Result of comparing two DateTimes.

See also
DateTime::Compare
Enumerator
EarlierThan 

Left hand side operand is earlier than right hand side.

Equals 

Left hand side operand is same as right hand side.

LaterThan 

Left hand side operand is later than right hand side.

Error 

Comparison failed.

enum Component
strong

Specifies whether a DateTime represents a date (without time component) or a date time.

Enumerator
Date 

The DateTime represents a date only (without time component)

DateAndTime 

The DateTime represents a date and a time.

enum DayOfWeek
strong

Specifies the days of the week.

Enumerator
Sunday 

Sunday.

Monday 

Monday.

Tuesday 

Tuesday.

Wednesday 

Wednesday.

Thursday 

Thursday.

Friday 

Friday.

Saturday 

Saturday.

enum Kind
strong

Specifies whether a DateTime represents a local time, a Coordinated Universal Time (UTC), or is not specified as either local time or UTC.

Enumerator
Unspecified 

The time represented is not specified as either local time or Coordinated Universal Time (UTC).

Only use that for legacy data when the time zone information is not known.

Utc 

The time represented is UTC.

Local 

The time represented is local time (in machine's time zone).

Constructor & Destructor Documentation

DateTime ( )

Initializes a new empty instance of the DateTime struct.

Remarks
DateTime::IsValid returns false in that case, as it doesn't represent any date time.
DateTime ( Int16  year,
UInt8  month,
UInt8  day 
)

Initializes a new instance of the DateTime struct.

Remarks
This creates a "date-only" DateTime, i.e. the DateTime::Component of this DateTime amounts to DateTime::Component::Date. DateTime::Kind is irrelevant for "date-only" DateTime;
Parameters
[in]yearThe year (-4713 through 9999)
[in]monthThe month (1 through 12)
[in]dayThe day in the month (1 through the number in month)
DateTime ( Kind  kind,
Int16  year,
UInt8  month,
UInt8  day,
UInt8  hour,
UInt8  minute,
UInt8  second = 0,
UInt32  hectoNanosecond = 0 
)

Initializes a new instance of the DateTime struct.

Parameters
[in]kindthe Kind for this DateTime
[in]yearThe year (-4713 through 9999)
[in]monthThe month (1 through 12)
[in]dayThe day in the month (1 through the number in month)
[in]hourThe hours (0 through 23)
[in]minuteThe minutes (0 through 59)
[in]secondThe seconds (0 through 59)
[in]hectoNanosecondThe hecto-nanoseconds (0 through 9,999,999)

Member Function Documentation

static UInt64 CommonEraTicksToJulianDay ( Int64  commonEraTicks)
static

Computes the Julian Day number from the given Common Era ticks.

The Common Era begins at 0001-01-01 00:00:00 UTC.

Parameters
[in]commonEraTicksCommon Era ticks in hecto-nanoseconds
Returns
Julian Day number in hecto-nanoseconds
static CompareResult Compare ( DateTime const &  lhs,
DateTime const &  rhs 
)
static

Compares two DateTimes.

This method internally converts the DateTime objects to Julian Days and compares those. As the conversion can fail, this method can return an error (see DateTime::CompareResult). This is also the reason why the class does not provide comparison operators other than equality and inequality.

Parameters
[in]lhsLeft-hand side DateTime
[in]rhsRight-hand side DateTime
Returns
A CompareResult value.
BentleyStatus ComputeOffsetToUtcInHns ( Int64 offset) const

If this object is of kind Local, this computes the offset from local time to UTC in HNS (hectonanoseconds). Otherwise, it sets the parameter to 0.

bool Equals ( DateTime const &  rhs,
bool  ignoreDateTimeInfo = false 
) const

Compares the given DateTime with this DateTime.

Parameters
[in]rhsDateTime to compare with this DateTime
[in]ignoreDateTimeInfotrue if the date time info should be ignored when comparing. false otherwise.
Returns
true, if the two DateTimes are equal, false otherwise
static BentleyStatus FromCommonEraTicks ( DateTime dateTime,
Int64  commonEraTicks,
Info const &  targetInfo 
)
static

Computes the DateTime from the given Common Era ticks.

The Common Era begins at 0001-01-01 00:00:00 UTC.

Parameters
[out]dateTimeResulting DateTime object (on the proleptic Gregorian calendar)
[in]commonEraTicksCommon Era ticks in hecto-nanoseconds
[in]targetInfoDateTime::Info the resulting DateTime should have
Returns
SUCCESS if computation was successful. ERROR in case of errors, e.g. if computation of local time zone offset failed.
static BentleyStatus FromJulianDay ( DateTime dateTime,
UInt64  julianDayInHns,
Info const &  targetInfo 
)
static

Computes the DateTime from the given Julian Day number.

Parameters
[out]dateTimeResulting DateTime object (on the proleptic Gregorian calendar)
[in]julianDayInHnsJulian Day number in hecto-nanoseconds to convert to DateTime
[in]targetInfoDateTime::Info the resulting DateTime should have
Returns
SUCCESS if computation was successful. ERROR in case of errors, e.g. if computation of local time zone offset failed.
static BentleyStatus FromJulianDay ( DateTime dateTime,
double  julianDay,
Info const &  targetInfo 
)
static

Computes the DateTime from the given Julian Day number.

Parameters
[out]dateTimeResulting DateTime object (on the proleptic Gregorian calendar)
[in]julianDayJulian Day number with the time component being the fractional component of the double value.
[in]targetInfoDateTime::Info the resulting DateTime should have
Returns
SUCCESS if computation was successful. ERROR in case of errors, e.g. if computation of local time zone offset failed.
static BentleyStatus FromString ( DateTime dateTime,
Utf8CP  dateTimeIso8601 
)
static

Parses an ISO 8601 date time string into a DateTime instance.

Remarks
This method supports T and a space as delimiter of the date and time component, e.g. both 2013-09-15T12:05:39 and 2013-09-15 12:05:39 can be parsed into a DateTime object. This is a minor deviation from the ISO standard (specifies the T delimiter), which allows to parse SQL-99 date time literals (specifies the space delimiter)
Parameters
[out]dateTimethe resulting DateTime instance
[in]dateTimeIso8601the ISO 8601 date time string to parse
Returns
SUCCESS, if parsing was successful. ERROR, otherwise
static BentleyStatus FromString ( DateTime dateTime,
WCharCP  dateTimeIso8601 
)
static

Parses an ISO 8601 date time string into a DateTime instance.

Remarks
This method supports T and a space as delimiter of the date and time component, e.g. both 2013-09-15T12:05:39 and 2013-09-15 12:05:39 can be parsed into a DateTime object. This is a minor deviation from the ISO standard (specifies the T delimiter), which allows to parse SQL-99 date time literals (specifies the space delimiter)
Parameters
[out]dateTimethe resulting DateTime instance
[in]dateTimeIso8601the ISO 8601 date time string to parse
Returns
SUCCESS, if parsing was successful. ERROR, otherwise
static BentleyStatus FromUnixMilliseconds ( DateTime dateTime,
UInt64  unixMilliseconds 
)
static

Creates a DateTime in UTC from the given Unix epoch milliseconds.

Parameters
[out]dateTimeThe resulting DateTime object on the proleptic Gregorian calendar (in UTC).
[in]unixMillisecondsThe Unix epoch milliseconds. Negative if they refer to a date before the Unix epoch (1970-01-01 00:00:00 UTC)
Returns
SUCCESS if conversion was successful. ERROR otherwise
static DateTime GetCurrentTime ( )
static

Gets the current system time in local time.

Returns
Current system time in local time
static DateTime GetCurrentTimeUtc ( )
static

Gets the current system time in UTC.

Returns
Current system time in UTC
UInt8 GetDay ( ) const

Gets the day component of this DateTime object.

Returns
Day in the month (1 through the number in GetMonth)
DayOfWeek GetDayOfWeek ( ) const

Gets the day of the week of this DateTime object.

Remarks
Only call this method if the DateTime is valid (see DateTime::IsValid)
Returns
Day of the week
UInt16 GetDayOfYear ( ) const

Gets the day of the year of this DateTime object.

Returns
Day of the year or 0 if the DateTime object is not valid (see DateTime::IsValid)
UInt32 GetHectoNanosecond ( ) const

Gets the hecto-nanosecond component of this DateTime object.

Remarks
1 hecto-nanosecond is 1e-7 seconds.
Returns
Hecto-nanoseconds (0 through 9,999,999)
UInt8 GetHour ( ) const

Gets the hour component of this DateTime object.

Returns
Hours (0 through 59)
Info const& GetInfo ( ) const

Gets meta data about this DateTime object.

Returns
DateTime::Info of this DateTime object.
UInt16 GetMillisecond ( ) const

Gets the milliseconds component of this DateTime object.

Remarks
The hecto-nanoseconds are truncated (not rounded) at the millisecond position.
Returns
Milliseconds (0 through 999)
UInt8 GetMinute ( ) const

Gets the minute component of this DateTime object.

Returns
Minutes (0 through 59)
UInt8 GetMonth ( ) const

Gets the month component of this DateTime object.

Returns
Month (1 through 12).
UInt8 GetSecond ( ) const

Gets the second component of this DateTime object.

Returns
Seconds (0 through 59)
Int16 GetYear ( ) const

Gets the year component of this DateTime object.

Returns
Year (negative if BCE, positive otherwise).
static bool IsLeapYear ( UInt16  year)
static

Indicates whether the specified year is a leap year or not.

Returns
true, if year is a leap year. false, otherwise.
bool IsValid ( ) const

Indicates whether this DateTime instance is a valid date/time or not.

Remarks
Using the default constructor creates an invalid date time as none of the components have been set.
Returns
true, if the DateTime instance is valid, false otherwise
static Int64 JulianDayToCommonEraTicks ( UInt64  julianDayInHectoNanoseconds)
static

Computes Common Era ticks from the given the Julian Day number.

The Common Era begins at 0001-01-01 00:00:00 UTC.

Parameters
[in]julianDayInHectoNanosecondsJulian Day number
Returns
Common Era ticks in hecto-nanoseconds
static Int64 JulianDayToUnixMilliseconds ( UInt64  julianDayInHectoNanoseconds)
static

Computes the Unix milliseconds from the given Julian Day number.

Parameters
[in]julianDayInHectoNanosecondsJulian day in hecto-nanoseconds.unixMilliseconds Unix milliseconds.
Returns
Unix milliseconds. Negative numbers indicate dates before the Unix epoch.
bool operator!= ( DateTime const &  rhs) const

Checks the given DateTime with this DateTime for inequality.

Parameters
[in]rhsDateTime to compare with this DateTime
Returns
true if the two DateTimes are not equal, false if they are equal
bool operator== ( DateTime const &  rhs) const

Compares the given DateTime with this DateTime.

Parameters
[in]rhsDateTime to compare with this DateTime
Returns
true if the two DateTimes are equal, false otherwise
BentleyStatus ToCommonEraTicks ( Int64 commonEraTicks) const

Computes the Common Era ticks from this DateTime instance.

This DateTime must be on the proleptic Gregorian calendar. The Common Era begins at 0001-01-01 00:00:00 UTC.

Parameters
[out]commonEraTicksCommon Era ticks in hecto-nanoseconds
Returns
SUCCESS if successful. ERROR in case of errors, e.g. if this date time instance is invalid (see DateTime::IsValid) or if computation of local time zone offset failed.
BentleyStatus ToJulianDay ( UInt64 julianDayInHns) const

Computes the Julian Day number in hecto-nanoseconds from this DateTime instance.

Remarks
This DateTime must be on the proleptic Gregorian calendar.
Parameters
[out]julianDayInHnsJulian Day number in hecto-nanoseconds
Returns
SUCCESS if computation was successful. ERROR in case of errors, e.g. if date time instance is not valid (see DateTime::IsValid) or if computation of local time zone offset failed.
BentleyStatus ToJulianDay ( double &  julianDay) const

Computes the Julian Day number from this DateTime instance.

Remarks
This DateTime must be on the proleptic Gregorian calendar.
Parameters
[out]julianDayJulian Day number with the time component being the fractional component of the double value.
Returns
SUCCESS if computation was successful. ERROR in case of errors, e.g. if date time instance is not valid (see DateTime::IsValid) or if computation of local time zone offset failed.
BentleyStatus ToLocalTime ( DateTime localDateTime) const

Converts this UTC DateTime to local time.

Parameters
[out]localDateTimeResulting DateTime object in local time
Returns
SUCCESS if successful. ERROR in case of errors, e.g. if this date time instance is invalid (see DateTime::IsValid) or if computation of local time zone offset failed.
WString ToString ( ) const

Converts the value of this DateTime into a string representation.

Remarks
The resulting string is formatted according to the ISO8601 standard. Second fractions are rounded to milliseconds.
Returns
String representation of this DateTime object. An empty string is returned if this date time info object is not valid (see DateTime::IsValid )
BentleyStatus ToUnixMilliseconds ( Int64 unixMilliseconds) const

Converts this DateTime to Unix epoch milliseconds (UTC).

This DateTime must be on the proleptic Gregorian calendar.

The resulting Unix milliseconds are UTC based. If this DateTime object is in local time, the method internally accounts for converting to UTC first.

Parameters
[out]unixMillisecondsUnix epoch milliseconds. The value is negative for dates before the beginning of the Unix epoch (1970-01-01 00:00:00 UTC)
Returns
SUCCESS if successful. ERROR in case of errors, e.g. if this date time instance is invalid (see DateTime::IsValid) or if computation of local time zone offset failed.
BentleyStatus ToUtc ( DateTime utcDateTime) const

Converts this local DateTime to UTC.

Parameters
[out]utcDateTimeResulting DateTime object in UTC
Returns
SUCCESS if successful. ERROR in case of errors, e.g. if this date time instance is invalid (see DateTime::IsValid) or if computation of local time zone offset failed.
Utf8String ToUtf8String ( ) const

Converts the value of this DateTime into a string representation.

Remarks
The resulting string is formatted according to the ISO8601 standard. Second fractions are rounded to milliseconds.
Returns
String representation of this DateTime object. An empty string is returned if this date time info object is not valid (see DateTime::IsValid )
static UInt64 UnixMillisecondsToJulianDay ( UInt64  unixMilliseconds)
static

Computes the Julian Day number from the given Unix milliseconds.

Parameters
[in]unixMillisecondsUnix milliseconds. Negative numbers indicate dates before the Unix epoch.
Returns
Julian Day number in hecto-nanoseconds

The documentation for this struct was generated from the following file:

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.