Class: Toybox.Time.Moment

Inherits:

Toybox.Lang.Object

• Toybox.Lang.Object
• Toybox.Time.Moment

Overview

A Moment is an immutable moment in time.

Moment objects are closely related to Duration objects, and are frequently used together for time calculations. While a Duration represents a span of time, a Moment represents a single point in time such as a specific date.

Internally, Moment objects are stored as 32-bit integers representing the number of seconds since the UNIX epoch (January 1, 1970 at 00:00:00 UTC).

See Also:

• UTC Time
• UNIX Time

Example:

using Toybox.System;
using Toybox.Time.Gregorian;

// Options for Saturday February 24th, 2018 12:12am
var options = {
    :year   => 2018,
    :month  => 2,
    :day    => 24,
    :hour   => 0,
    :minute => 12
};

var now = Gregorian.moment(options);
var info;
info = Gregorian.utcInfo(now, Time.FORMAT_SHORT);

// Prints "2018-02-24" to the console
System.println(Lang.format("$1$-$2$-$3$", [
    info.year.format("%04u"),
    info.month.format("%02u"),
    info.day.format("%02u")
]));

// Prints "day_of_week=7 month=2" to the console
System.println(Lang.format("day_of_week=$1$ month=$2$", [
    info.day_of_week,
    info.month
]));

info = Gregorian.utcInfo(now, Time.FORMAT_LONG);

// Prints "day_of_week=Sat month=Feb" to the console
System.println(Lang.format("day_of_week=$1$ month=$2$", [
    info.day_of_week,
    info.month
]));

Since:

API Level 1.0.0

Instance Method Summary

• add(duration as Time.Duration) as Time.Moment

  Add a Duration to a Moment.

• compare(moment as Time.Moment) as Lang.Number

  Determine if a Moment is before or after another Moment.

• greaterThan(moment as Time.Moment) as Lang.Boolean

  Determine if a Moment is greater than another Moment.

• initialize(seconds as Lang.Number) Time.Moment

  Constructor.

• lessThan(moment as Time.Moment) as Lang.Boolean

  Determine if a Moment is less than another Moment.

• subtract(subtrahend as Time.Moment or Time.Duration) as Time.Moment or Time.Duration

  Subtract a Duration or Moment from a Moment.

• value() as Lang.Number

  Get the UTC value of a Moment.

Instance Method Details

add(duration as Time.Duration) as Time.Moment

Add a Duration to a Moment.

This method functions the same as the Duration.add() method when adding a Duration to a Moment.

Parameters:

• duration — (Time.Duration) —

  The Duration to add to this Moment

Example:

Add one day to today

using Toybox.Time;
using Toybox.Time.Gregorian;
var today = new Time.Moment(Time.today().value());
var oneDay = new Time.Duration(Gregorian.SECONDS_PER_DAY);
var tomorrow = today.add(oneDay);

Returns:

• Time.Moment —

  A Moment object that is the sum of self and the provided Duration object

See Also:

• Duration.add()
• SECONDS_PER_DAY

Since:

API Level 1.0.0

compare(moment as Time.Moment) as Lang.Number

Determine if a Moment is before or after another Moment.

This computes a Number representing the difference between the two Moment objects in seconds. The subtract() method can also be used to get the absolute Duration between two Moment objects.

Parameters:

• moment — (Time.Moment) —

  The Moment to compare to this Moment

Example:

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var today = new Time.Moment(Time.today().value());
var oneDay = new Time.Duration(Gregorian.SECONDS_PER_DAY);
var tomorrow = today.add(oneDay);

System.println(today.compare(tomorrow)); // -86400, or one day in the past
System.println(tomorrow.compare(today)); //  86400, or one day in the future

Returns:

• Lang.Number —

  The Number of seconds difference between the two Moment objects. If the Moment supplied for comparison is after this Moment, the value will be negative.

See Also:

• Moment.subtract()
• SECONDS_PER_DAY

Since:

API Level 1.0.0

greaterThan(moment as Time.Moment) as Lang.Boolean

Determine if a Moment is greater than another Moment.

Parameters:

• moment — (Time.Moment) —

  The Moment to compare to this Moment

Example:

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var today = new Time.Moment(Time.today().value());
var oneDay = new Time.Duration(Gregorian.SECONDS_PER_DAY);
var tomorrow = today.add(oneDay);

System.println(today.greaterThan(tomorrow)); // false
System.println(tomorrow.greaterThan(today)); // true

Returns:

• Lang.Boolean —

  true if this Moment is greater than the Moment supplied for comparison, otherwise false

See Also:

• SECONDS_PER_DAY

Since:

API Level 1.0.0

initialize(seconds as Lang.Number) Time.Moment

Constructor

Parameters:

• seconds — (Lang.Number) —

  The Number of seconds with which to initialize the Moment

Example:

Create a Moment with a UNIX time stamp

using Toybox.Time;
var garminFounded = new Time.Moment(631065600);

Example:

Create a Moment representing today

using Toybox.Time;
var today = new Time.Moment(Time.today().value());

Returns:

• Time.Moment —

  A Moment representing the specified moment in time

See Also:

• UTC Time
• UNIX Time

Since:

API Level 1.1.2

lessThan(moment as Time.Moment) as Lang.Boolean

Determine if a Moment is less than another Moment.

Parameters:

• moment — (Time.Moment) —

  The Moment to compare to this Moment

Example:

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var today = new Time.Moment(Time.today().value());
var oneDay = new Time.Duration(Gregorian.SECONDS_PER_DAY);
var tomorrow = today.add(oneDay);

System.println(today.lessThan(tomorrow)); // true
System.println(tomorrow.lessThan(today)); // false

Returns:

• Lang.Boolean —

  true if this Moment is less than the Moment supplied for comparison, otherwise false

See Also:

• SECONDS_PER_DAY

Since:

API Level 1.0.0

subtract(subtrahend as Time.Moment or Time.Duration) as Time.Moment or Time.Duration

Subtract a Duration or Moment from a Moment.

Note:

Subtracting a Duration from a Moment was not supported until ConnectIQ 3.0.0. If backward compatibility is a concern, it may be best to add a negative Duration instead.

Parameters:

• subtrahend — (Time.Moment, Time.Duration) —

  The Moment or Duration to subtract from this Moment

Example:

using Toybox.System;
using Toybox.Time;
using Toybox.Time.Gregorian;
var today = new Time.Moment(Time.today().value());
var oneDay = new Time.Duration(Gregorian.SECONDS_PER_DAY);
var tomorrow = today.add(oneDay);

var duration1 = today.subtract(tomorrow);
var duration2 = tomorrow.subtract(today);

System.println(duration1.value()); // 86400, or one day
System.println(duration2.value()); // 86400, or one day

Returns:

• Time.Duration, Time.Moment —

  The Duration between the two Moment objects or the Moment offset by a Duration. When subtracting Moments, the computed Duration is always a positive value. The compare() method can be used to determine whether one Moment is before or after another Moment.

See Also:

• Moment.compare()
• SECONDS_PER_DAY

Since:

API Level 1.0.0

value() as Lang.Number

Get the UTC value of a Moment.

Returns:

• Lang.Number —

  The UTC date of the Moment in seconds since the UNIX epoch

See Also:

• UTC Time
• UNIX Time

Since:

API Level 1.0.0