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

Instance Method Summary collapse

Instance Method Details

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



8483
8484
# File 'Monkeybrains.rb', line 8483

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



8500
8501
# File 'Monkeybrains.rb', line 8500

def today()
end