About
maxon::UniversalDateTime is a MAXON API class used to create an object capable to represent Universal date-time (UTC+0000) in a convenient and effective form provided with numerous helpful methods to manage date & time representation.
It's highly recommended to use this class to store any date and time and conversion to maxon::LocalDateTime for a localized output should occur as late as possible to prevent time representation issues. The internal representation is an unsigned 64-bit length integer with the start time set at 01/01/1970-00:00 UTC+0000 and a time resolution of 1 second.
Creation and initialization
A maxon::UniversalDateTime can be created on the stack and initialized using:
const UInt64 aTimeStamp(1467363600);
const Float64 aJulianDay = 2457570.875;
Comparison
A maxon::UniversalDateTime can be compared by using standard operators:
const UInt64 timestamp = 1467363600;
if (udt == udtCloned)
{
}
if (udtPast < udt)
{
}
- Note
- From the above operators all the remaining operators (!=, >, >=, <=) are derived and can thus be used as usual.
Conversion
A maxon::UniversalDateTime can be converted to maxon::LocalDateTime using:
Similarly the following methods return maxon::String representations of the maxon::UniversalDateTime via:
- Note
- maxon::UniversalDateTime::FormatTime() uses the same formatting specified in C++ strftime() function.
const UInt64 timestamp = 1467363600;
DiagnosticOutput(
"The unix timestamp [@], refers to @, @, and @.", timestamp, dayOfTheTS, weekOfTheTS, timeOfTS);
Utilities
A few helpful methods are provided with the maxon::UniversalDateTime as utilities:
- Note
- The Julian day variants have been introduced across the years to adapt to different reference epoch and return a proper Julian day representation of a given time/date. See Variants in Julian day;
Finally a Julian day can be obtained using:
switch (var)
{
varStr = "Dublin"_s;
break;
varStr = "Legacy"_s;
break;
varStr = "Lilian"_s;
break;
varStr = "Mars Sol"_s;
break;
varStr = "Modified"_s;
break;
varStr = "Rata die"_s;
break;
varStr = "Reduced"_s;
break;
varStr = "Standard"_s;
break;
}
DiagnosticOutput(diagIDString +
"On date @/@/@ and time @:@:@ , the Julian day computed using the @ variant is @.", day, month, year, hour, min, sec, varStr, julianDay);
A maxon::UniversalDateTime object can be read from and written to disk by serializing the data contained using the conventional functions.
const maxon::Id fileID {
"net.maxonexample.universaldatetime" };
Further Reading
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, Result< void > >::type ReadDocument(const Url &url, const Id &id, T &object, const DataDictionary &dict=DataDictionary())
Definition: io.h:35
@ SET
When a date-time object gets converted the Daylight Saving Time is added to the target time.
UInt64 GetUnixTimestamp() const
Definition: datetime.h:267
@ DUBLIN
Dublin variant with epoch of 12h Dec 31, 1899.
Definition: string.h:1197
static UniversalDateTime FromUnixTimestamp(UInt64 timestamp)
static Float64 ToJulianDay(JULIANDATE variant, Int32 year, UChar month, UChar day, UChar hour, UChar minute, UChar second)
static Result< UniversalDateTime > FromValues(Int32 year, UChar month, UChar day, UChar hour, UChar minute, UChar second)
STANDARD
Create standard material.
Definition: lib_substance.h:226
void SetHours(Float64 hours)
Definition: timevalue.h:196
Definition: apibaseid.h:250
#define iferr_return
Definition: resultbase.h:1434
double Float64
64 bit floating point value (double)
Definition: apibase.h:179
HashInt GetHashCode() const
Returns the hash value of this object. This value can be used for all HashSet<>/HashMap<> classes.
Definition: datetime.h:345
Float64 Float
Definition: apibase.h:193
LocalDateTime ConvertToLocalDateTime() const
Definition: datetime.h:231
@ LEGACY
Legacy mode with Julian Day + 0.5.
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
void Reset()
Reset all values to zero.
Definition: datetime.h:237
@ REDUCED
Reduced JD with epoch of 12h Nov 16, 1858.
maxon::UChar UChar
Definition: ge_sys_math.h:55
String FormatTime(const Char *formatString) const
@ LILIAN
Lilian variant with epoch of Oct 15, 1582[9].
@ MARSSOL
Mars Sol Date variant with epoch of 12h Dec 29, 1873.
Definition: datetime.h:91
JULIANDATE
Variants of Julian Day.
Definition: datetime.h:52
maxon::Int32 Int32
Definition: ge_sys_math.h:58
Result< void > WriteDocument(const Url &url, OPENSTREAMFLAGS flags, const Id &id, const T &object, IOFORMAT format=IOFORMAT::DEFAULT, const DataDictionary &dict=DataDictionary())
Definition: io.h:67
static UniversalDateTime FromJulianDay(JULIANDATE variant, Float64 j)
static UniversalDateTime GetNow()
@ MODIFIED
Modified variant with epoch of 0h Nov 17, 1858.
The TimeValue class encapsulates a timer value.
Definition: timevalue.h:33
uint64_t UInt64
64 bit unsigned integer datatype.
Definition: apibase.h:175
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:185
@ RATEDIE
Rate Die variant with epoch of Jan 1, 1, proleptic Gregorian calendar.
DST
Daylight Saving Time information.
Definition: datetime.h:42
maxon::UInt64 UInt64
Definition: ge_sys_math.h:61
Float64 GetJulianDay(JULIANDATE variant) const
maxon::Float64 Float64
Definition: ge_sys_math.h:65
Bool IsValid() const
Definition: datetime.h:323
@ STANDARD
Standard variant with epoch of 12h Jan 1, 4713 BC.