LocalDateTime Manual

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:

// This example allocates a few maxon::LocalDateTime objects showing different initialization methods.
// allocate a UniversalDateTime object on the stack initialized with the current time
// 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:

// This example shows how to compare two LocalDateTime objects
// allocate and initialize a LocalDateTime
const UInt64 timestamp = 1467363600;
// 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:

// This example shows how to convert a LocalDateTime to a UniversalDateTime
// allocate and initialize a LocalDateTime to the current time/date
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:

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
// 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:

// This example shows how to use the utilities found in the LocalDateTime class
// allocate and initialize a LocalDateTime to the current time
// 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)
{
dayStr = "Monday"_s;
break;
dayStr = "Tuesday"_s;
break;
dayStr = "Wednesday"_s;
break;
dayStr = "Thursday"_s;
break;
dayStr = "Friday"_s;
break;
dayStr = "Saturday"_s;
break;
dayStr = "Sunday"_s;
break;
}
DiagnosticOutput("On @/@/@ was a @. ", day, month, year, dayStr);

Further Reading

maxon::TimeValue::GetHours
Float64 GetHours() const
Definition: timevalue.h:187
maxon::LocalDateTime::FromUnixTimestamp
static LocalDateTime FromUnixTimestamp(UInt64 timestamp)
maxon::DAYOFWEEK
DAYOFWEEK
Day of Week.
Definition: datetime.h:15
maxon::DAYOFWEEK::TUESDAY
@ TUESDAY
Tuesday.
maxon
The maxon namespace contains all declarations of the MAXON API.
Definition: c4d_basedocument.h:15
maxon::String
Definition: string.h:1197
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::DAYOFWEEK::THURSDAY
@ THURSDAY
Thursday.
maxon::DAYOFWEEK::FRIDAY
@ FRIDAY
Friday.
maxon::UniversalDateTime
Definition: datetime.h:231
maxon::LocalDateTime::IsLeapYear
Bool IsLeapYear() const
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
UChar
maxon::UChar UChar
Definition: ge_sys_math.h:55
String
Definition: c4d_string.h:38
M
M
Meter.
Definition: customgui_unitscale.h:4
maxon::LocalDateTime::FromValues
static Result< LocalDateTime > FromValues(Int32 year, UChar month, UChar day, UChar hour, UChar minute, UChar second, DST daylightSavingTime=DST::AUTOMATIC)
maxon::LocalDateTime::FormatTime
String FormatTime(const Char *formatString) const
maxon::LocalDateTime
Definition: datetime.h:91
maxon::DAYOFWEEK::WEDNESDAY
@ WEDNESDAY
Wednesday.
maxon::DAYOFWEEK::SATURDAY
@ SATURDAY
Saturday.
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:58
maxon::LocalDateTime::GetNow
static LocalDateTime GetNow()
maxon::LocalDateTime::ToString
String ToString(const FormatStatement *formatStatement=nullptr) const
maxon::TimeValue
The TimeValue class encapsulates a timer value.
Definition: timevalue.h:33
maxon::LocalDateTime::GetDayOfWeek
DAYOFWEEK GetDayOfWeek() const
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:185
S
S
Scale morphing.
Definition: lib_ca.h:83
maxon::DAYOFWEEK::MONDAY
@ MONDAY
Monday.
Char
maxon::Char Char
Definition: ge_sys_math.h:54
UInt64
maxon::UInt64 UInt64
Definition: ge_sys_math.h:61
maxon::DAYOFWEEK::SUNDAY
@ SUNDAY
Sunday.