UniversalDateTime Manual

Table of Contents

• About
• Creation and initialization
• Comparison
• Conversion
• Utilities
• Further Reading

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:

• maxon::UniversalDateTime::GetNow(): creates a maxon::UniversalDateTime initialized at the current time;
• maxon::UniversalDateTime::FromUnixTimestamp(): creates a maxon::UniversalDateTime object initialized at the given Unix Time-stamp;
• maxon::UniversalDateTime::FromJulianDay(): creates a maxon::UniversalDateTime initialized at the given Julian Day;
• maxon::UniversalDateTime::FromValues(): creates a maxon::UniversalDateTime given year, month, day, hours, minutes and seconds.

    // This example allocates a few maxon::UniversalDateTime objects showing different initialization methods.
 
    // allocate a UniversalDateTime object on the stack initialized at the current time
    const maxon::UniversalDateTime udtNow(maxon::UniversalDateTime::GetNow());
 
    // define a unix-compliant timestamp equal to 01.07.2016 09:00:00
    const UInt64 aTimeStamp(1467363600);
 
    // allocate and initialize a second UniversalDateTime object using a unix time stamp
    const maxon::UniversalDateTime udtFromUnixTimestamp(maxon::UniversalDateTime::FromUnixTimestamp(aTimeStamp));
 
    // define a Julian day equal to 01.07.2016 09:00:00
    // http://www.onlineconversion.com/julian_date.htm
 
    const Float64 aJulianDay = 2457570.875;
 
    // allocate and initialize a third UniversalDateTime object using a Julian date
    const maxon::UniversalDateTime udtFromJulianDay(maxon::UniversalDateTime::FromJulianDay(JULIANDATE::STANDARD, aJulianDay));
 
    // assign a UniversalDateTime given the year, month, day, hours, minutes, seconds
    const maxon::UniversalDateTime udtFromValues = maxon::UniversalDateTime::FromValues(2016, 7, 1, 9, 0, 0) iferr_return;

Comparison

A maxon::UniversalDateTime can be compared by using standard operators:

• maxon::UniversalDateTime::operator==(): compares two UniversalDateTime used in expression checking values for equality;
• maxon::UniversalDateTime::operator<(): compares two UniversalDateTime used in expression checking the first being smaller than the second.

    // This example shows how to compare two UniversalDateTime objects
 
    // allocate and initialize a UniversalDateTime
    const UInt64 timestamp = 1467363600;
    const maxon::UniversalDateTime udt = maxon::UniversalDateTime::FromUnixTimestamp(timestamp);
 
    // clone into a new UniversalDateTime
    const maxon::UniversalDateTime udtCloned(udt);
 
    // allocate and initialize a UniversalDateTime with a slightly different unix timestamp
    const maxon::UniversalDateTime udtPast = maxon::UniversalDateTime::FromUnixTimestamp(1467363600 - 1);
 
    // compare the initial with the clone
    if (udt == udtCloned)
    {
      // the two instances are equal
      // do something here
      DiagnosticOutput("udt and udtCloned are equal.");
    }
 
    // compare the initial with the clone
    if (udtPast < udt)
    {
      // the first instance is smaller than the second
      // do something here
      DiagnosticOutput("udtPast refers to a previous date than 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:

• maxon::UniversalDateTime::ConvertToLocalDateTime(): converts to maxon::LocalDateTime using the current time zone;
• maxon::UniversalDateTime::ConvertToLocalDateTime(const TimeValue& utcOffset, DST dst) const: converts to maxon::RemoteDateTime given a time offset and the DST information.

    // This example shows how to convert a UniversalDateTime to a LocalDateTime / RemoteDateTime
 
    // allocate a UniversalDateTime and initialize to the current time stamp
    const maxon::UniversalDateTime udtNow = maxon::UniversalDateTime::GetNow();
 
    // convert, in the current timezone, the UniversalDateTime to a LocalDateTime
    const maxon::LocalDateTime localNow_currentTZ = udtNow.ConvertToLocalDateTime();
 
    // allocate and initialize a TimeValue
    maxon::TimeValue timeoffset;
    timeoffset.SetHours(2.0);
 
    // allocate and initialize a maxon::DST
    const maxon::DST dstFlag(maxon::DST::SET);
 
    // convert the UniversalDateTime to a RemoteDateTime using the specified offset and the DST information
    const maxon::RemoteDateTime remoteNow_offsetDST = udtNow.ConvertToLocalDateTime(timeoffset, dstFlag);

Similarly the following methods return maxon::String representations of the maxon::UniversalDateTime via:

• maxon::UniversalDateTime::FormatTime(): returns a customizable maxon::String based on the given string format used;
• maxon::UniversalDateTime::ToString(): returns a maxon::String representation of the maxon::UniversalDateTime object.

Note

maxon::UniversalDateTime::FormatTime() uses the same formatting specified in C++ strftime() function.

    // This example shows how to return a properly formatted string representing the data stored in UniversalDateTime.
 
    // allocate and initialize a UniversalDateTime object
    const UInt64 timestamp = 1467363600;
    const maxon::UniversalDateTime udt = maxon::UniversalDateTime::FromUnixTimestamp(timestamp);
 
    // extract useful strings to represent the given timestamp
    const maxon::String dayOfTheTS  = udt.FormatTime("%A the %j-th day of year %Y");
    const maxon::String weekOfTheTS = udt.FormatTime("the date %d/%m/%Y is in %W-th week");
    const maxon::String timeOfTS = udt.FormatTime("the time set is %I:%M:%S %p");
 
    DiagnosticOutput("The unix timestamp [@], refers to @, @, and @.", timestamp, dayOfTheTS, weekOfTheTS, timeOfTS);

Utilities

A few helpful methods are provided with the maxon::UniversalDateTime as utilities:

• maxon::UniversalDateTime::Reset(): reset all values to zero;
• maxon::UniversalDateTime::GetJulianDay(): given the Julian Date variant, returns the Julian day representation of the maxon::UniversalDateTime object;
• maxon::UniversalDateTime::GetUnixTimestamp(): returns the Unix time stamp representation of the maxon::UniversalDateTime object;
• maxon::UniversalDateTime::IsValid(): checks it the maxon::UniversalDateTime object has a time stamp not equal to zero;
• maxon::UniversalDateTime::GetHashCode(): returns the hash code of the maxon::UniversalDateTime object.

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;

    // This example shows how to use the utilities found in the UniversalDateTime class
 
    // allocate and initialize an UniversalDateTime at the current timestamp
    maxon::UniversalDateTime udtNow = maxon::UniversalDateTime::GetNow();
 
    // convert to the Julian day representation using a legacy variant
    const maxon::Float jday = udtNow.GetJulianDay(maxon::JULIANDATE::LEGACY);
 
    // convert to the unix timestamp
    const maxon::UInt64 tstamp = udtNow.GetUnixTimestamp();
 
    // retrieve the hash code representation
    const maxon::UInt udtHC = udtNow.GetHashCode();
 
    // check the UniversalDateTime's validity
    if (udtNow.IsValid())
    {
      // if valid just reset it
      udtNow.Reset();
    }
    DiagnosticOutput("udtNow has been reset to @", udtNow);

Finally a Julian day can be obtained using:

• maxon::UniversalDateTime::ToJulianDay(): given the Julian Date variant, year, month, day, hours, minutes and second returns the corresponding Julian day value.

    // This example shows how to compute the Julian day given the required parameters
 
    // set the required parameters
    const JULIANDATE var   = maxon::JULIANDATE::STANDARD;
    const Int32      year  = 2016;
    const UChar      month = 7;
    const UChar      day   = 1;
    const UChar      hour  = 9;
    const UChar      min   = 0;
    const UChar      sec   = 0;
 
    // compute the Julian day
    const maxon::Float64 julianDay = maxon::UniversalDateTime::ToJulianDay(var, year, month, day, hour, min, sec);
 
    // prepare the string representation of the Julian day variant
    maxon::String varStr;
    switch (var)
    {
      case maxon::JULIANDATE::DUBLIN:
        varStr = "Dublin"_s;
        break;
      case maxon::JULIANDATE::LEGACY:
        varStr = "Legacy"_s;
        break;
      case maxon::JULIANDATE::LILIAN:
        varStr = "Lilian"_s;
        break;
      case maxon::JULIANDATE::MARSSOL:
        varStr = "Mars Sol"_s;
        break;
      case maxon::JULIANDATE::MODIFIED:
        varStr = "Modified"_s;
        break;
      case maxon::JULIANDATE::RATEDIE:
        varStr = "Rata die"_s;
        break;
      case maxon::JULIANDATE::REDUCED:
        varStr = "Reduced"_s;
        break;
      case maxon::JULIANDATE::STANDARD:
        varStr = "Standard"_s;
        break;
    }
 
    // show the result
    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.

    // This example shows how to store and retrieve a UniversalDateTime from a file.
 
    // allocate and initialize a UniversalDateTime
    const maxon::UniversalDateTime savedUDT = maxon::UniversalDateTime::GetNow();
 
    // allocate a file URL
    const maxon::Url url = (targetFolder + "universaldatetime.txt"_s)iferr_return;
    const maxon::Id  fileID { "net.maxonexample.universaldatetime" };
 
    // save to file
    maxon::WriteDocument(url, maxon::OPENSTREAMFLAGS::NONE, fileID, savedUDT, maxon::IOFORMAT::JSON) iferr_return;
 
    // read back from file
    maxon::UniversalDateTime loadedUDT;
    maxon::ReadDocument(url, fileID, loadedUDT) iferr_return;

Further Reading

• Data & Algorithms
• Time-based Types
• TimeValue Manual
• DescribeIO Manual