DateTime

class

A Date and time representation in the Gregorian calendar.

This class represents a point in time, defined in the gregorian calendar. Such a timestamp are given in year, month, day of month, hours since midnight, minutes and seconds. This class also defined if the timestamp is in UTC / GMT or a defined local time zone.

The class handles leap years and the varying length of months. You can add seconds, minutes, hours and days to a DateTime object and get the result as a new DateTime object.

When you create DateTime objects they are created in the local time zone by default. The local time zone is defined as a offset in hours relative to UTC. There is no notion of IANA Time Zone names of alike - just an offset to the UTC time.

There are two convenient method to print DateTime as readable strings. The toString method print a human readable (MySql compatible) timestamp. The other toISO8601 returns a string formatted in the ISO 8601 standard format used in JSON objects.

When printing DateTime objects, they are returned in the time zone that they are created in.

System Wall Clock

This class also has a global DateTime object reserved for use by a RTC feature. A subsystem manages the RTC and increments the global system DateTime object.

You can get the current DateTime time by using the static method now To set the system clock use the static method setSystemClock

Public Types

enum type mono::DateTime::TimeTypes

DateTime timestamps can be one of three types

Values:

The DateTime is specified in local time zone

The DateTime is specified in UTC / GMT time zone

The DateTime do not have a specified time zone

Public Functions

DateTime::DateTime()

Construct an empty / invalid DateTime object.

DateTime::DateTime(uint16_t years, uint8_t months, uint8_t days, uint8_t hours = 0, uint8_t minutes = 0, uint8_t seconds = 0, TimeTypes zone = LOCAL_TIME_ZONE)

Construct a DateTime object with a given date and time.

Parameters
  • years: The Year component of the date, for example 2016
  • months: The month component of the date from 1 to 12, May is 5
  • days: The day component of the date, 1-indexed, from 1 to 31
  • hours: Optional: The hour component of the timestamp, range is 0 to 23
  • minutes: The minute component of the timestamp, range is 0 to 59
  • seconds: The seconds component of the timestamp, range is 0 to 59
  • zone: The timezone where this DateTime define its time, default is the local timezone

String DateTime::toString() const

Return the DateTime object as a huamn readable string.

Return
A mono string on the format: yyyy-MM-dd hh:mm:ss

String DateTime::toISO8601() const

Return an ISO8601 formatted timestamp as a string.

This returned string is on the format: yyyy-MM-ddTHH:mm:ss+tt:00 if not UTC or yyyy-MM-ddTHH:mm:ssZ

String DateTime::toTimeString() const

Return only a time string from the DateTime.

The format is: HH:mm:ss

String DateTime::toDateString() const

Return only a date string from the DateTime.

The format is: yyyy-MM-dd

bool DateTime::isValid() const

Return true if the DateTime is valid.

Invalid date object is contructed by the default constructor

DateTime DateTime::toUtcTime() const

Convert this DateTime to UTC time.

DateTime DateTime::addSeconds(int seconds) const

Return a new object with a number of seconds added.

This method increments the timestamp for the given second interval

Return
The new DateTime object with seconds added
Parameters
  • seconds: The seconds to add

DateTime DateTime::addMinutes(int minutes) const

Return a new object with a number of minutes added.

This method increments the timestamp for the given minute interval

Return
The new DateTime object with minutes added
Parameters
  • minutes: The minutes to add

DateTime DateTime::addHours(int hours) const

Return a new object with a number of hours added.

This method increments the timestamp for the given hour interval

Return
The new DateTime object with hours added
Parameters
  • hours: The hours to add

DateTime DateTime::addDays(int days) const

Return a new object with a number of days added.

This method increments the timestamp for the given day interval

Return
The new DateTime object with days added
Parameters
  • days: The days to add

Public Static Functions

static DateTime mono::DateTime::maxValue()

Get the maximum possible DateTime value (far in the future)

static DateTime mono::DateTime::minValue()

Get the lowest possible DateTime value (the distant past)

bool DateTime::isLeapYear(uint16_t year)

Check is a year is a leap year.

DateTime DateTime::fromISO8601(String date)

Parse a subset of ISO 8601 compatible date time representations.

This static method takes a ISO 8601 formatted string, and creates a DateTime object from that. This method only parses a subset of the possible date representations allowed in ISO 8601. Specifically it can handle dates in these format:

  • yyyy-MM-ddTHH:mm:ssZ
  • yyyy-MM-ddTHH:mm:ss+01:00 or other time zones
  • yyyy-MM-dd HH:mm:ssZ
  • yyyy-MM-dd HH:mm:ss

Return
The parsed DateTime object, that might be valid or invalid

void DateTime::setSystemDateTime(DateTime dt)

Set a new system DateTime.

DateTime DateTime::now()

Get the current DateTime from the system RTC clock.

void DateTime::incrementSystemClock()

Internal method used by the RTC system to increment the system DateTime. You should not call this manually.

Public Static Attributes

int DateTime::LocalTimeZoneHourOffset

The systems current TimeZone setting.

MARK: STATIC SYSTEM DATETIME.

The timezone is just an hour-offset from the UTC / GMT time