ts-time/LocalTime

import LocalTime, {MIN_TIME, MAX_TIME, MAX_TIME12, MIDNIGHT, NOON} from "ts-time/LocalTime";

Hierarchy#

• class LocalTime

Description#

Comprises a specific time, without date and time zone relation. In other words, this is a tuple of (hour, minute, second, millisecond), or a number of milliseconds since day start (from 0 inclusive to MS_PER_DAY exclusive).

Construct#

A common way to construct an object in ts-time is to call its of static method. For example, the following LocalTime instance represents 18 hours, 30 minutes, 15 seconds, 225 milliseconds:

LocalTime.of(18, 30, 15, 225);

As opposed to Java API, there's no common way to get the current instance of an object in ts-time, because ts-time doesn't have a concept of default time zone. Instead, you must get the current Instant and convert it to an object that you need, taking time zone into consideration.

Instant.now().atZone(UTC).time;             // Current LocalTime in UTC
Instant.now().atZone(LOCAL_ZONE_ID).time;   // Current LocalTime in the local time zone
Instant.now().atZone(zone).time;            // Current LocalTime in a given ZoneId/ZoneOffset

It makes ts-time API more robust. It leaves less room for a mistake.

A common way to convert a native JavaScript Date object to a ts-time object is to call fromNative* static method:

LocalTime.fromNativeUtc(date);              // LocalTime from a given Date in UTC
LocalTime.fromNativeLocal(date);            // LocalTime from a given Date in the local time zone
Instant.fromNative(date).atZone(zone).time; // LocalTime from a given Date in a given ZoneId/ZoneOffset

You can convert instances of other ts-time classes to LocalTime via their properties and methods:

instant.atZone(zone).time;                  // From Instant in a given ZoneId/ZoneOffset
localDateTime.time;                         // From LocalDateTime
offsetDateTime.time;                        // From OffsetDateTime in the same ZoneOffset
zonedDateTime.time;                         // From ZonedDateTime in the same ZoneId

Please notice that all these conversions result in a partial data loss (date, time zone, offset).

For some commonly used time moments, there are predefined LocalTime instances: MIDNIGHT, NOON, MIN_TIME, MAX_TIME, MAX_TIME12.

Another sophisticated constructor: ofTotalMs.

Parse#

A common way to parse an ISO 8601 compliant string in ts-time is to call parse static method. For example, the following LocalTime instance represents 18 hours, 30 minutes, 15 seconds, 225 milliseconds:

LocalTime.parse("18:30:15.225");

The library doesn't yet support parsing non-compliant strings.

Inspect#

In the following example, we inspect various properties of a LocalTime object:

const time   = LocalTime.of(18, 30, 15, 225);
const hour   = time.hour;   // 18
const minute = time.minute; // 30
const second = time.second; // 15
const ms     = time.ms;     // 225

Another sophisticated feature for LocalTime inspection: totalMs.

Compare#

A common way to compare objects in ts-time is to call equals, isBefore, isAfter, compareTo methods:

const t1 = LocalTime.of(18, 30, 15, 225);
const t2 = LocalTime.of(18, 30, 15, 226);
t1.equals(t2);    // false
t1.isBefore(t2);  // true
t1.isAfter(t2);   // false
t1.compareTo(t2); // -1

For nullable objects, use static methods instead. Null and undefined are considered less than anything, except each other:

const t1: LocalTime = null;
const t2 = LocalTime.of(18, 30, 15, 225);
LocalTime.equal(t1, t2);     // false
LocalTime.isBefore(t1, t2);  // true
LocalTime.isAfter(t1, t2);   // false
LocalTime.compare(t1, t2);   // -1

Manipulate#

Every object in ts-time is immutable. Therefore every manipulation returns a new object.

To add/subtract a Duration, call plus/minus method. Please notice that the result is always between 00:00:00.000 inclusive and 24:00:00.000 exclusive:

const time = LocalTime.of(18, 30, 15, 225);
const t1 = time.plus(MINUTE_DURATION);         // 18:31:15.225
const t2 = time.plus(Duration.ofHours(10));    // 04:30:15.225
const t3 = time.minus(Duration.ofSeconds(30)); // 18:29:45.225

If you need to take full days (positive or negative) into consideration, use Duration or LocalDateTime instead of LocalTime.

To change one of the components, preserving all the rest, call with* methods:

const time = LocalTime.of(18, 30, 15, 225);
const t1 = time.withHour(20);                  // 20:30:15.225
const t2 = time.withMinute(20);                // 18:20:15.225
const t3 = time.withSecond(20);                // 18:30:20.225
const t4 = time.withMs(20);                    // 18:30:15.020

To truncate all the least-significant components, call truncate* methods:

const time = LocalTime.of(18, 30, 15, 225);
const t1 = time.truncateToHour;                // 18:00:00.000
const t2 = time.truncateToMinute;              // 18:30:00.000
const t3 = time.truncateToSecond;              // 18:30:15.000

Convert#

You can convert LocalTime to other kinds of objects via its methods:

const time = LocalTime.of(18, 30, 15, 225);
time.atDate(date);                      // To LocalDateTime on a given LocalDate
time.atDate(date).atOffset(offset);     // To OffsetDateTime on a given LocalDate in a given ZoneOffset
time.atDate(date).atZone(zone);         // To ZonedDateTime on a given LocalDate in a given ZoneId
time.atDate(date).atZone(zone).instant; // To Instant on a given LocalDate in a given ZoneId/ZoneOffset

In order to convert LocalTime from one ZoneId to another, you must explicitly specify the date of conversion (as certain time zones have varying offsets over the time line), get an Instant and then convert it to the target ZoneId:

time.atDate(date).atZone(sourceZone).instant.atZone(targetZone).time;

Conversion of ZoneOffset doesn't depend on a date:

time.minus(Duration.ofSeconds(sourceOffset.totalSeconds)).plus(Duration.ofSeconds(targetOffset.totalSeconds));

You can as well convert LocalTime to a native JavaScript Date, provided you know a LocalDate and a ZoneId/ZoneOffset:

const time = LocalTime.of(18, 30, 15, 225);
LocalDateTime.of(date, time).atZone(zone).native; // Date representing 18:30:15.225 on a given LocalDate in a given ZoneId/ZoneOffset

For backward conversion, see Construct.

Format#

Every class in ts-time has ISO 8601 compliant toString method:

const time = LocalTime.of(18, 30, 15, 225);
time.toString(); // "18:30:15.225"

For more sophisticated string formatting, add ts-time-format library to your list of dependencies:

npm install --save ts-time-format

Now you can construct an instance of TimeFormatter in order to format arbitrary LocalTime instances:

const formatter = TimeFormatter.ofPattern("hh:mm a");
const time = LocalTime.of(18, 30, 15, 225);
formatter.format(time); // "06:30 PM"

Fields#

totalMs#

hour#

minute#

second#

ms#

truncateToHour#

truncateToMinute#

truncateToSecond#

Methods#

get#

compareTo#

equals#

isBefore#

isAfter#

atDate#

plus#

minus#

withHour#

withMinute#

withSecond#

withMs#

toString#

Static methods#

of#

ofTotalMs#

fromNativeLocal#

fromNativeUtc#

parse#

compare#

equal#

isBefore#

isAfter#

MIN_TIME: LocalTime

Minimal LocalTime (00:00:00.000).

MAX_TIME: LocalTime

Maximum LocalTime (23:59:59.999).

MAX_TIME12: LocalTime

Maximum LocalTime in 12-hour system (11:59:59.999).

MIDNIGHT: LocalTime

Midnight (00:00:00.000).

NOON: LocalTime

Noon (12:00:00.000).