DateTimeData Manual

Table of Contents

• About
• Access
• Add a parameter in a description
• DateTime Structure
  • DateTime Properties
  • Constructors
• Functionality
  • String
  • Julian format
  • Current DateTime
  • Convert DateTime
  • Day of week
  • Validate
  • Compare
• Further Reading

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);

• 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);

• 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);
    

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;
      }

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);
 

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);

• 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;
      GetDateTimeNow(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);

  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::Int32 hrs, min, sec;
      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);

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)));
   

Current DateTime

Retrieves the current date and time.

• GetDateTimeNow() Retrieves the current system date time and fill the parameter t with it.
• GetDateTimeNowGM() Retrieves the current system date time in GMT and fill the parameter t with it.

    // Retrieves the current date.
    DateTime currentTime;
    GetDateTimeNow(currentTime);
    const maxon::String dateTimeToString = FormatTime("%H:%M:%S - %A - %d / %b / %G", currentTime);
   
    DiagnosticOutput("The current time is @", dateTimeToString);

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;
      GetDateTimeNow(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");
      }

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]);
   

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);
   
        ValidateTime(hrs, min, sec);
        DiagnosticOutput("Time before validate @ @ @  and after @ @ @", 42, 25, 123456, hrs, min, sec);

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.
    maxon::Int32 result = CompareDateTime(t1, t2);
    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)));
   

Further Reading

• DateTimeControl Manual
• GeData Manual
• BaseContainer Manual
• Primitive Data Types Manual (Cinema API)
• Description Manual