DateTimeData Manual

About

A DateTimeData stores a date and a time. Using a ::DateTime structure, it stores the year, month, day, hour, minute and second.
For more specific operation related to time, see TimeValue Manual.

Access

Use C4DAtom::GetParameter() to retrieve the data of a parameter and cast it to DateTimeData.

// This example retrieves the actual DateTime from a sky object.
GeData data;
// Retrieves the parameter from the physical sky object.
Bool success = mySkyObject->GetParameter(ConstDescID(DescLevel(SKY_DATE_TIME)), data, DESCFLAGS_GET::NONE);
// Checks if we retrieved the data and its type.
if (!success || data.GetType() != DATETIME_DATA)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// Retrieves the data from data container.
const DateTimeData* dateTimeData = data.GetCustomDataType<DateTimeData>();
if (dateTimeData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
NONE
Definition: asset_browser.h:1
#define DATETIME_DATA
DateTime custom data ID.
Definition: customgui_datetime.h:22
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:69
#define ConstDescID(...)
Definition: lib_description.h:596
maxon::Bool Bool
Definition: ge_sys_math.h:46
@ SKY_DATE_TIME
Definition: oskyshader.h:54
  • DateTimeData::GetDateTime().
    Retrieves the DateTime from DateTimeData.
    // Retrieves the DateTime from DateTimeData.
    // Gets the DateTime.
    const DateTime timeRetrieved = dateTimeData->GetDateTime();
    // Converts DateTime To string.
    maxon::String dateString = DateToString(timeRetrieved);
    maxon::String timeString = TimeToString(timeRetrieved);
    // Outputs the result.
    DiagnosticOutput("the date is @ and the time is @", dateString, timeString);
    Definition: string.h:1287
    String DateToString(const DateTime &d)
    String TimeToString(const DateTime &d, const Bool bShowSeconds=true)
    #define DiagnosticOutput(formatString,...)
    Definition: debugdiagnostics.h:170
  • DateTimeData::SetDateTime().
    Allows to set the DateTime to a DateTimeData.
    // Sets the date and time of a physical sky object.
    // Allocates a new DateTimeData.
    AutoAlloc<DateTimeData> dateTimeData;
    if (dateTimeData == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
    // Creates a Date time.
    DateTime dateTime(1912, 6, 23, 23, 59, 59);
    // Sets the DateTimeData.
    dateTimeData->SetDateTime(dateTime);

Use C4DAtom::SetParameter() to set the DateTimeData of your parameter.
The custom data type must be specified in the GeData constructor.

// Sets the physical sky object parameter with the new data.
GeData dat = GeData(DATETIME_DATA, DEFAULTVALUE);
DateTimeData* dt = dat.GetCustomDataTypeWritable<DateTimeData>();
if (dt)
{
dt->SetDateTime(dateTime);
}
Bool success = mySkyObject->SetParameter(ConstDescID(DescLevel(SKY_DATE_TIME)), dat, DESCFLAGS_SET::NONE);
if (!success)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
@ DEFAULTVALUE
Dummy value for the default value GeData constructor.
Definition: c4d_gedata.h:64

Add a parameter in a description

A parameter can be added to a description with the function ::GetDDescription(). To attach a custom GUI to that parameter define DESC_CUSTOMGUI settings and call SetParameter(). See DateTimeControl Manual.

// This example shows how to implement a BaseTimeData parameter with a custom GUI.
const DescID cid = ConstDescID(DescLevel(dateTimeID, DATETIME_DATA, 0));
if (!singleid || cid.IsPartOf(*singleid, nullptr))
{
BaseContainer settings = GetCustomDataTypeDefault(DATETIME_DATA);
// Sets the name
settings.SetString(DESC_NAME, "Date Time"_s);
settings.SetString(DESC_SHORT_NAME, "Date Time"_s);
// Sets the custom GUI displaying that parameter.
// GetCustomDataTypeDefault sets it to DATETIME_GUI by default.
settings.SetInt32(DESC_CUSTOMGUI, DATETIME_GUI);
// Activates the now button
settings.SetBool(DATETIME_NOW_BUTTON, true);
// Activates the clock
settings.SetBool(DATETIME_TIME_CONTROL, true);
// Activates the calendar
settings.SetBool(DATETIME_DATE_CONTROL, true);
// The maximized GUI is shown by default.
settings.SetBool(DESC_GUIOPEN, true);
// Inserts the parameter in the description
if (!description->SetParameter(cid, settings, ConstDescID(DescLevel(ID_OBJECTPROPERTIES))))
return false;
}
#define DATETIME_GUI
DateTime custom GUI ID.
Definition: customgui_datetime.h:19
#define DATETIME_DATE_CONTROL
::Bool true, if it is a calendar.
Definition: customgui_datetime.h:28
#define DATETIME_TIME_CONTROL
::Bool true, if it is a clock.
Definition: customgui_datetime.h:27
#define DATETIME_NOW_BUTTON
::Bool true, to add "Now" button.
Definition: customgui_datetime.h:29
@ DESC_CUSTOMGUI
Int32 The ID of the GUI for this element. Either a custom ID or one of: CUSTOMGUI
Definition: lib_description.h:124
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:90
@ DESC_SHORT_NAME
String Short name, for attributes dialog.
Definition: lib_description.h:91
@ DESC_GUIOPEN
Bool true if the maximized GUI is shown by default.
Definition: lib_description.h:129
BaseContainer GetCustomDataTypeDefault(Int32 type)
@ ID_OBJECTPROPERTIES
Definition: obase.h:56

DateTime Structure

Represents a date and a time.

Inside DateTimeData, DataTime is only accessible via those functions:

  • DateTimeData::GetDateTime() Returns a DateTime.
  • DateTimeData::SetDateTime() Sets the date / time.
// This example shows how to set and get a DateTimeData.
// Creates a DateTime for Alan Turing's birthday.
DateTime timeSet(1912, 6, 23, 23, 59, 59);
// Allocates a new DateTimeData.
AutoAlloc<DateTimeData> dateTimeData;
if (dateTimeData == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// Sets the DateTimeData to the new time/date.
dateTimeData->SetDateTime(timeSet);
// Retrieves the DateTime From DateTimeData.
const DateTime timeGet = dateTimeData->GetDateTime();

DateTime Properties

The Structure of the DateTime is composed by those properties.

  • DateTime::year.
  • DateTime::month.
  • DateTime::day.
  • DateTime::hour.
  • DateTime::minute.
  • DateTime::second.

Constructors

A DateTime can be created passing some argument in the constructor as follow:

DateTime (Int32 t_year, Int32 t_month, Int32 t_day, Int32 t_hour, Int32 t_minute, Int32 t_second);

// Allocates a new DateTimeData using AutoAlloc.
AutoAlloc<DateTimeData> dateTimeData;
if (dateTimeData == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// Released the pointer if needed.
DateTimeData* anotherPointer = dateTimeData.Release();
// Another way to Alloc a DateTimeData using GeData.
GeData data = GeData(DATETIME_DATA, DEFAULTVALUE);
DateTimeData* value = data.GetCustomDataTypeWritable<DateTimeData>();
if (value == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// Creates a Date time.
DateTime dateTime(1912, 6, 23, 23, 59, 59);
// Sets the DateTimeData.
value->SetDateTime(dateTime);
// Frees the pointer as we took ownership.
DateTimeData::Free(anotherPointer);
PyObject * value
Definition: abstract.h:715

Functionality

There are several functions to manipulate dates and times.

String

DateTime can be converted as a String with:

  • FormatTime() Formats the given DateTime t and output it as a string. The format options are the same as strftime().
    // Retrieves a DateTime to a string format.
    // Displays a DateTime 22:32:44 Thursday - 23 / Aug / 2001.
    const Char* pszFormat = "%H:%M:%S - %A - %d / %b / %G";
    maxon::String dateTimeString = FormatTime(pszFormat, currentTime);
    DiagnosticOutput("The DateTime @ in string using @ format result is @", dateTimeToString, pszFormat, dateTimeString);
    String FormatTime(const char *pszFormat, const DateTime &t)
    maxon::Char Char
    Definition: ge_sys_math.h:47
  • TimeToString() Converts a time as a formatted string (e.g. "12:34:56").
  • DateToString() Converts a date as a formatted string. The format of the returned string depends on the current OS date and time settings.
    // Converts a date as a formatted string.
    const maxon::String dateToString = DateToString(currentTime);
    // The output format depends on the os Date and time settings.
    DiagnosticOutput("The current time @ converted to a string @", dateTimeToString, dateToString);
  • GetMonthName() Retrieves the name of a month in the current Cinema 4D interface language.
    // This example gets the month's name from today's Date.
    // Sets a DateTime to now.
    DateTime now;
    // Retrieves the month's name in the current Cinema 4D interface language.
    const maxon::String month = GetMonthName(now.month);
    // Outputs the result.
    DiagnosticOutput("The actual monmth is @", month);
    void GetDateTimeNow(DateTime &t)
    String GetMonthName(Int month)
    DateTime can also be parsed from String to ::Int32 with thoses functions:
  • ParseTimeString() Parses a time string (e.g. "12:34:56").
  • ParseDateString() Parses a date string (e.g. "31/12/2010").
    // Parses a time string to Int32.
    maxon::String time = "12:34:56"_s;
    // Checks the result of the function.
    if (!ParseTimeString(time, hrs, min, sec))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
    DiagnosticOutput("This time @ can be parse to @ hours @ minutes @ seconds", time, hrs, min, sec);
    int32_t Int32
    32 bit signed integer datatype.
    Definition: apibase.h:175
    Bool ParseTimeString(String timestr, Int32 &hour, Int32 &minute, Int32 &second)
    const char Py_ssize_t const char Py_ssize_t min
    Definition: modsupport.h:58
    time_t * sec
    Definition: pytime.h:57

Julian format

Transforms DateTime to Julian date in both directions.

  • GetJulianDay() return the modified Julian date. To get the correct Julian day, take the integer of the value and subtract 0.5.
  • FromJulianDay() return a DateTime from the modified Julian date.
    // This example use a Julian day.
    const DateTime dateTime = DateTime(2015, 12, 25, 12, 32, 59);
    maxon::Float julianDay = GetJulianDay(dateTime);
    // Outputs "2457382.523".
    DiagnosticOutput("The date 25 December 2015 converted to a julian day is @", julianDay);
    // Outputs "2457382.023".
    julianDay -= 0.5;
    DiagnosticOutput("To get the correct Julian day, subtract 0.5 @", julianDay);
    // We need to add 0.5 to a Julian day before using FromJulianDay.
    julianDay += 0.5;
    const DateTime backToTime = FromJulianDay(julianDay);
    // Outputs "12:32:59 - Friday - 25 / Dec / 2014".
    DiagnosticOutput("Date from julian day is @", FormatString(FormatTime(pszFormat, backToTime)));
    Float64 Float
    Definition: apibase.h:196
    Float64 GetJulianDay(const DateTime &t)
    DateTime FromJulianDay(Float64 j)
    #define FormatString(...)
    Definition: string.h:2218

Current DateTime

Retrieves the current date and time.

Convert DateTime

Converts date and time to GMT or local date and time.

  • LocalToGMTime() Converts local time to GMT depending on the OS time zone settings.
    Warning
    LocalToGMTime will fail if the local date is before Jan 1, 1970 2.01 am or after Jan 18, 2038 7 pm.
  • GMTimeToLocal() Converts GMT time to local depending on the OS time zone settings.
    // This example transform a DateTime to a LocalGMT time value.
    // Sets a DateTime to now.
    DateTime now;
    DateTime outGMT;
    if (LocalToGMTime(now, outGMT))
    {
    const maxon::String localTimeToString = FormatTime("%H:%M:%S - %A - %d / %b / %G", now);
    const maxon::String gmtTimeToString = FormatTime("%H:%M:%S - %A - %d / %b / %G", outGMT);
    DiagnosticOutput("Local time @ to GMT result is @", localTimeToString, gmtTimeToString);
    }
    else
    {
    DiagnosticOutput("Failed to convert the local time to a GMT");
    }
    Bool LocalToGMTime(const DateTime &tLocal, DateTime &tGMT)

Day of week

Gets the day of the week.

  • GetDayOfWeek() Gets the day of the week of the date lYear-lMonth-lDay and return ::DAYOFWEEK.
    // Retrieves witch day of the week Alan Turing is born.
    // Create an array for all days of the week.
    const maxon::String days[7] = { "Monday"_s, "Tuesday"_s, "Wednesday"_s, "Thursday"_s, "Friday"_s, "Saturday"_s, "Sunday"_s };
    // GetDayOfWeek return a DAYOFWEEK so we need to cast that into a Int32 to retrieves the text in our days' array.
    const maxon::Int32 day = static_cast<maxon::Int32>(GetDayOfWeek(1912, 6, 23));
    // Outputs the result.
    DiagnosticOutput("Alan Turing is born a @", days[day]);
    DAYOFWEEK GetDayOfWeek(Int32 lYear, Int32 lMonth, Int32 lDay)

Validate

Tries to correct invalid data.

  • ValidateDate() Tries to correct invalid date values, e.g. clamping the values within valid limits. (1700-2299, 1-12, compatible day for the passed month)
  • ValidateTime() Tries to correct invalid time values, e.g. clamping the values within valid limits. (0h-23h 0-59m 0-59s)
    // Tries to correct the data of a DateTime.
    maxon::Int32 year = 2042, month = 125, day = 412, hrs = 42, min = 25, sec = 123456;
    ValidateDate(year, month, day);
    DiagnosticOutput("Date before validate @ @ @ and after @ @ @", 2042, 125, 412, year, month, day);
    DiagnosticOutput("Time before validate @ @ @ and after @ @ @", 42, 25, 123456, hrs, min, sec);
    void ValidateDate(Int32 &year, Int32 &month, Int32 &day)
    void ValidateTime(Int32 &hour, Int32 &minute, Int32 &second)

Compare

There are several operators that can be used to compare DateTime.

  • DateTime::operator== : return true if the first DateTime is the same as the second.
  • DateTime::operator != : return true if the first DateTime is not the same as the second.
  • DateTime::operator<= : return true if the first DateTime is before or equal to the second.
  • DateTime::operator< : return true if the first DateTime is before the second.
  • DateTime::operator >= : return true if the first DateTime is after or equal to the second.
  • DateTime::operator > : return true if the first DateTime is after the second.
  • ::CompareDateTime (const DateTime &a, const DateTime &b) compare two DateTime and return less than 0 if a < b, equal to 0 if a == b and greater than 0 if a > b.
    // Compares two DateTime.
    const DateTime t1(1976, 04, 02, 18, 55, 22);
    const DateTime t2(2019, 12, 25, 12, 55, 22);
    // Check if both value are equals.
    DiagnosticOutput("Compare DateTime : @ and @ equality is @", FormatString(FormatTime(pszFormat, t1)), FormatString(FormatTime(pszFormat, t2)), t1 == t2);
    // Another way to compare DateTime is using the function.
    // Result is guaranty to be less than 0 , equal to 0 , or greater than 0.
    if (result < 0)
    DiagnosticOutput("@ is less than @", FormatString(FormatTime(pszFormat, t1)), FormatString(FormatTime(pszFormat, t2)));
    else if (result == 0)
    DiagnosticOutput("@ is equal to @", FormatString(FormatTime(pszFormat, t1)), FormatString(FormatTime(pszFormat, t2)));
    else
    DiagnosticOutput("@ is greater than @", FormatString(FormatTime(pszFormat, t1)), FormatString(FormatTime(pszFormat, t2)));
    PyObject PyObject * result
    Definition: abstract.h:43
    Int32 CompareDateTime(const DateTime &a, const DateTime &b)

Further Reading