Module: Toybox::Time

Overview

The Time module provides functionality for dealing with times and dates.

There are two main concepts used by Monkey C when working with time: the Moment and Duration. A Moment is a single point in time, while a Duration is a span of time. Moments and Durations can be used together for time calculations in the following ways:

Expression           Method               Result    Notes
---------------------------------------------------------------------------
Moment + Moment      -                    -         Invalid
Moment + Duration    Moment.add()         Moment    A later Moment
Moment - Moment      Moment.subtract()    Duration  The span between Moments
Moment - Duration    Moment.subtract()    Moment    An earlier Moment

Duration + Duration  Duration.add()       Duration  A longer Duration
Duration + Moment    Duration.add()       Moment    A later Moment
Duration - Duration  Duration.subtract()  Duration  A shorter Duration
Duration - Moment    -                    -         Invalid

Dates and times are generally represented in UTC time from the UNIX epoch, with the exception of the Gregorian Moment, which are created relative to the current local time.

Date and time formatting in Monkey C is relatively open-ended, providing some formatting constants for short, medium, and long formatting (long and medium formatting are currently equivalent).

Constant          Seconds  Minutes  Hours  Day of Week  Day  Month  Year
---------------------------------------------------------------------------
FORMAT_SHORT   |  0        0        0      4            1    3      2017
FORMAT_MEDIUM  |  0        0        0      Wed          1    Mar    2017
FORMAT_LONG    |  0        0        0      Wed          1    Mar    2017

Examples:

Formatting and printing a date

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var today = Gregorian.info(Time.now(), Time.FORMAT_MEDIUM);
var dateString = Lang.format(
    "$1$:$2$:$3$ $4$ $5$ $6$ $7$",
    [
        today.hour,
        today.min,
        today.sec,
        today.day_of_week,
        today.day,
        today.month,
        today.year
    ]
);
System.println(dateString); // e.g. "16:28:32 Wed 1 Mar 2017"

Creating a Moment representing May 16, 2003

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var options = {
    :year   => 2003,
    :month  => 5,
    :day    => 16,
    :hour   => 6    // UTC offset, in this case for CST
};
var birthday = Gregorian.moment(options);

See Also:

Since:

  • 1.0.0

Defined Under Namespace

Modules: Gregorian Classes: Duration, Moment

Constant Summary

FORMAT_SHORT = 0

Short formatting is a numerical representation of date/time.

Since:

  • 1.0.0

FORMAT_MEDIUM = 1

Medium formatting is a mix of Numbers and Strings depending on which function is called. If formatted as a String, the result is an abbreviated form of the time or date.

Since:

  • 1.0.0

FORMAT_LONG = 2

Long formatting is a mix of Numbers and Strings depending on which function is called. If formatted as a String, the result is an abbreviated form of the time or date.

Since:

  • 1.0.0

CURRENT_TIME_DEFAULT = 0

The default system clock, which may be user-modified.

Since:

  • 3.0.10

CURRENT_TIME_GPS = 1

The clock time based on your current GPS location if a GPS signal is available.

Since:

  • 3.0.10

CURRENT_TIME_RTC = 2

The system's real-time clock that cannot be overridden by user settings. This value may be synced with GPS time when a GPS fix is available.

Since:

  • 3.0.10

Instance Method Summary collapse

Instance Method Details

getCurrentTime(options) ⇒ Object

Get a Moment for the current time based on the specified source.

This method behaves the same as Time.now(), but accepts an options argument that allows the time source to be selected.

Parameters:

Options Hash (options):

See Also:

Since:

  • 3.0.10


10817
10818
# File 'Monkeybrains.rb', line 10817

def getCurrentTime(options)
end

nowToybox::Time::Moment

Get a Moment for the current time based on your current GPS location.

Since this is based on your current location, it returns local time. If UTC values are desired, it is necessary to account for the local UTC offset.

Examples:

Using now() on December 31, 1989 at 5:00 pm CST

using Toybox.Time;
var now = new Time.Moment(Time.now().value()); // UNIX epoch 631148400

Returns:

See Also:

Since:

  • 1.0.0


10769
10770
# File 'Monkeybrains.rb', line 10769

def now()
end

todayToybox::Time::Moment

Get a Moment for midnight today based on your current GPS location.

Since this is based on your current location, it returns midnight local time. If UTC values are desired, it is necessary to account for the local UTC offset.

Examples:

Using today() on December 31, 1989 at 5:00 pm CST

using Toybox.Time;
var now = new Time.Moment(Time.today().value()); // UNIX epoch 631087200

Returns:

See Also:

Since:

  • 1.0.0


10786
10787
# File 'Monkeybrains.rb', line 10786

def today()
end