LocalDateTime Manual

Table of Contents

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

About

maxon::LocalDateTime is a Maxon API class used to create an object capable of representing local time and date in a convenient and effective manner to reduce the effort of handling localized time and date representation. It's indeed recommended to use the maxon::UniversalDateTime whenever possible to store normalized time and date values and convert them the localized as late as possible.

Warning

maxon::LocalDateTime exposes all the available members as public leaving the developer the option to customize them. It must be noted that, if the customized values are incorrect, it could lead to an unpredictable behaviour when converting back to maxon::UniversalDateTime.

Creation and initialization

A maxon::LocalDateTime can be created and initialized using:

• maxon::LocalDateTime::GetNow(): creates a maxon::LocalDateTime initialized at the current time and date;
• maxon::LocalDateTime::FromUnixTimestamp(): creates a maxon::LocalDateTime object initialized at the given Unix timestamp;
• maxon::LocalDateTime::FromString(): creates a maxon::LocalDateTime initialized at the given date/time string and date/time formatting string;
• maxon::LocalDateTime::FromValues(): creates a maxon::LocalDateTime given year, month, day, hours, minutes and seconds.

    // This example allocates a few maxon::LocalDateTime objects showing different initialization methods.
 
    // allocate a UniversalDateTime object on the stack initialized with the current time
    const maxon::LocalDateTime ldtNow(maxon::LocalDateTime::GetNow());
 
    // define a unix-compliant timestamp equal to 01.07.2016 09:00:00 (in UTC time)
    const UInt64 aTimeStamp(1467363600);
 
    // allocate and initialize a second LocalDateTime object using a unix timestamp
    // NOTE: using LocalDateTime::FromUnixTimeStamp will add the local timezone to the passed timestamp
    const maxon::LocalDateTime ldtFromUnixTimestamp(maxon::LocalDateTime::FromUnixTimestamp(aTimeStamp));
 
    // allocate and initialize a third LocalDateTime object using spare date/time values
    const maxon::LocalDateTime ldtFromValues = maxon::LocalDateTime::FromValues(2016, 7, 1, 9, 0, 0) iferr_return;
 
    // allocate and initialize a forth LocalDateTime object using a properly formatted date/time string
    const maxon::String        timedateStr = "2016-07-01 09:00:00"_s;
    const Char*                timedateFrmtStr = "%Y-%m-%d %H:%M:%S";
    const maxon::LocalDateTime ldtFromString = maxon::LocalDateTime::FromString(timedateStr, timedateFrmtStr) iferr_return;

Comparison

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

• maxon::LocalDateTime::operator==(): compares two LocalDateTime used in the expression returning true if all the member values are equal;
• maxon::LocalDateTime::operator!=(): compares two LocalDateTime used in expression returning true if at least one of the member values is different.

    // This example shows how to compare two LocalDateTime objects
 
    // allocate and initialize a LocalDateTime
    const UInt64 timestamp = 1467363600;
    const maxon::LocalDateTime ldt = maxon::LocalDateTime::FromUnixTimestamp(timestamp);
 
    // clone into a new LocalDateTime
    const maxon::LocalDateTime ldtCloned(ldt);
 
    // allocate and initialize a LocalDateTime starting from the first one
    maxon::LocalDateTime ldtAnother(ldt);
 
    // update the hours
    ldtAnother._hour -= 2;
 
    // compare the initial with the clone
    if (ldt == ldtCloned)
    {
      // the two instances are equal
      // do something here
      DiagnosticOutput("ldt and ldtCloned share the same time/date values.");
    }
 
    // compare the initial with the clone
    if (ldtAnother != ldt)
    {
      // the first instance is smaller than the second
      // do something here
      DiagnosticOutput("ldtAnother time/date values are different than those stored in ldt.");
    }

Conversion

A maxon::LocalDateTime can be converted to maxon::UniversalDateTime using:

• maxon::LocalDateTime::ConvertToUniversalDateTime(): converts to maxon::UniversalDateTime using the local time/date settings.

    // This example shows how to convert a LocalDateTime to a UniversalDateTime
 
    // allocate and initialize a LocalDateTime to the current time/date
    const maxon::LocalDateTime ldtNow(maxon::LocalDateTime::GetNow());
 
    const maxon::UniversalDateTime udtNow = ldtNow.ConvertToUniversalDateTime();
 
    DiagnosticOutput("Current date/time in local time is: @", ldtNow);
    DiagnosticOutput("Current date/time in universal time is: @", udtNow);

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

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

Note

maxon::LocalDateTime::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 LocalDateTime.
 
    // allocate and initialize a timestamp
    const UInt64 timestamp = 1467363600;
    // allocate and initialize a LocalDateTime object
    const maxon::LocalDateTime ldt = maxon::LocalDateTime::FromUnixTimestamp(timestamp);
 
    // extract useful strings to represent the given timestamp
    const maxon::String dayOfTheTS  = ldt.FormatTime("%A the %j-th day of year %Y");
    const maxon::String weekOfTheTS = ldt.FormatTime("the date %d/%m/%Y is in %W-th week");
    const maxon::String timeOfTS = ldt.FormatTime("the time set is %I:%M:%S %p");
    DiagnosticOutput("Today [@] is @, @, and @.", ldt.ToString(nullptr), dayOfTheTS, weekOfTheTS, timeOfTS);

Utilities

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

• maxon::LocalDateTime::Reset(): reset all member values to zero;
• maxon::LocalDateTime::GetDayOfWeek(): returns the day of the week (see DAYOFWEEK) for the date stored;
• maxon::LocalDateTime::GetDayOfWeek(Int lYear, Int lMonth, Int lDay): returns the day of the week for the date passed given years, month and day;
• maxon::LocalDateTime::IsLeapYear(): returns true if the current date belongs to a leap year;
• maxon::LocalDateTime::IsLeapYear(Int year): returns true if the passed year is a leap year;
• maxon::LocalDateTime::GetTimezoneOffset(): returns the timezone offset to UTC based on the local time/date;
• maxon::LocalDateTime::GetHashCode(): returns the hash code of the maxon::LocalDateTime object.
  

    // This example shows how to use the utilities found in the LocalDateTime class
 
    // allocate and initialize a LocalDateTime to the current time
    const maxon::LocalDateTime ldtNow(maxon::LocalDateTime::GetNow());
 
    // retrieve the status about the leap year
    const maxon::Bool isLeapYear(ldtNow.IsLeapYear());
 
    // retrieve the hash code representation
    const maxon::UInt ldtHash = ldtNow.GetHashCode();
    DiagnosticOutput("Current date [@] hash-code is @", ldtNow, ldtHash);
 
    if (isLeapYear)
      DiagnosticOutput("Current date [@] belongs to a leap year", ldtNow);
    else
      DiagnosticOutput("Current date [@] doesn't belong to a leap year", ldtNow);
 
    // retrieve the information about the timezone offset
    maxon::Bool isDSTaffecting;
    const maxon::TimeValue timezoneOffset = ldtNow.GetTimezoneOffset(&isDSTaffecting);
 
    if (isDSTaffecting)
      DiagnosticOutput("Local date/time is offsetted by @h respect to UTC and DST is affecting the offset", timezoneOffset.GetHours());
    else
      DiagnosticOutput("Local date/time is offsetted by @h respect to UTC", timezoneOffset.GetHours());
 
    const Int32 year  = 2016;
    const UChar month = 12;
    const UChar day = 21;
 
    // retrieve the status about the leap year for a given date
    const maxon::Bool isAnotherLeapYear(maxon::LocalDateTime::IsLeapYear(year));
    if (isAnotherLeapYear)
      DiagnosticOutput("@ was a leap year. ", year);
    else
      DiagnosticOutput("@ wasn't a leap year. ", year);
 
    // check the current day of the week
    const maxon::DAYOFWEEK dayOfWeek = maxon::LocalDateTime::GetDayOfWeek(year, month, day);
 
    // prepare the string representation of the day
    maxon::String dayStr;
    switch (dayOfWeek)
    {
      case maxon::DAYOFWEEK::MONDAY:
        dayStr = "Monday"_s;
        break;
      case maxon::DAYOFWEEK::TUESDAY:
        dayStr = "Tuesday"_s;
        break;
      case maxon::DAYOFWEEK::WEDNESDAY:
        dayStr = "Wednesday"_s;
        break;
      case maxon::DAYOFWEEK::THURSDAY:
        dayStr = "Thursday"_s;
        break;
      case maxon::DAYOFWEEK::FRIDAY:
        dayStr = "Friday"_s;
        break;
      case maxon::DAYOFWEEK::SATURDAY:
        dayStr = "Saturday"_s;
        break;
      case maxon::DAYOFWEEK::SUNDAY:
        dayStr = "Sunday"_s;
        break;
    }
    DiagnosticOutput("On @/@/@ was a @. ", day, month, year, dayStr);

Further Reading

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