Skip to content

TimeSpan

Object that represents a time interval (duration of time or elapsed time) that is measured as a positive or negative number of days, hours, minutes, seconds, and fractions of a second.

Usage

Basic

ts
import { TimeSpan } from 'utilix';

// initializes with the total number of milliseconds
const time = new TimeSpan(44711000);

console.log(time.hours);   // 12
console.log(time.minutes); // 25
console.log(time.seconds); // 11

// initializes with specified number of hours, minutes, and seconds
console.log((new TimeSpan(2, 99, 18)).toString()); // 03:39:18

From time unit

ts
import { TimeSpan } from 'utilix';

console.log(TimeSpan.fromDays(1.23456).toString());    // 1.05:37:45.984
console.log(TimeSpan.fromHours(0.2539).toString());    // 00:15:14.040
console.log(TimeSpan.fromMinutes(60).toString());      // 01:00:00
console.log(TimeSpan.fromSeconds(32.157).toString());  // 00:00:32.157

Parse

ts
import { TimeSpan } from 'utilix';

console.log(TimeSpan.parse('54864').toString('s.ff'));   // 54.86
console.log(TimeSpan.parse('77:88:99.100').toString());  // 3.06:29:39.100
console.log(TimeSpan.parse('498.57s').toString());       // 00:08:18.570
console.log(TimeSpan.parse('1:1').toString());           // 00:01:01
console.log(TimeSpan.parse('-24.3d').toString());        // -24.07:12:00

Getter function

ts
import { TimeSpan } from "utilix";

const initTime = Date.now();
const upTime =  new TimeSpan(() => Date.now() - initTime);

setInterval(() => {
	console.log("Up time:", upTime.toString());
}, 1000);

TimeSpan class

ts
class TimeSpan

Represents a time interval (duration of time or elapsed time).

Constructors

ts
constructor(milliseconds: ValueOrGetter<number>)

Initializes TimeSpan object to the specified number of milliseconds.

Parameters

  • milliseconds: ValueOrGetter<number> Number of milliseconds, or getter function that return number of milliseconds.

ts
constructor(minutes: number, seconds: number)

Initializes TimeSpan object to a specified number of minutes, and seconds.

Parameters

  • minutes: number Number of minutes.
  • seconds: number Number of seconds.

ts
constructor(hours: number, minutes: number, seconds: number)

Initializes TimeSpan object to a specified number of hours, minutes, and seconds.

Parameters

  • hours: number Number of hours.
  • minutes: number Number of minutes.
  • seconds: number Number of seconds.

ts
constructor(days: number, hours: number, minutes: number, seconds: number, milliseconds?: number | undefined)

Initializes TimeSpan object to a specified number days, hours, minutes, seconds, and optional milliseconds.

Parameters

  • days: number Number of days.
  • hours: number Number of hours.
  • minutes: number Number of minutes.
  • seconds: number Number of seconds.
  • milliseconds?: number | undefined Number of milliseconds.

Properties

NameTypeDescription
totalMillisecondsnumberget Gets the value of the TimeSpan expressed in whole milliseconds.
totalSecondsnumberget Gets the value of the TimeSpan expressed in whole and fractional seconds.
totalMinutesnumberget Gets the value of the TimeSpan expressed in whole and fractional minutes.
totalHoursnumberget Gets the value of the TimeSpan expressed in whole and fractional hours.
totalDaysnumberget Gets the value of the TimeSpan expressed in whole and fractional days.
millisecondsnumberget Gets the milliseconds component of the time interval.
secondsnumberget Gets the seconds component of the time interval.
minutesnumberget Gets the minutes component of the time interval.
hoursnumberget Gets the hours component of the time interval.
daysnumberget Gets the days component of the time interval.
formattedstringget Get string representation of the TimeSpan value in the default format.

setDefaultFormat method

ts
setDefaultFormat(format: string): void

Set the default format that will be used in formatted property.

Parameters

  • format: string A format string.

toString method

ts
toString(format: string = this._defaultFormat): string

Converts the value of the current TimeSpan object to string representation by using the specified format.

Parameters

  • format: string = this._defaultFormat A format string.

Return string

The string representation of the current TimeSpan value in the format specified by the format parameter.

fromSeconds static method

ts
fromSeconds(value: ValueOrGetter<number>): TimeSpan

Get a TimeSpan object that represents a specified number of seconds.

Parameters

  • value: ValueOrGetter<number> Number of seconds.

Return TimeSpan

An object that represents value.

fromMinutes static method

ts
fromMinutes(value: ValueOrGetter<number>): TimeSpan

Get a TimeSpan object that represents a specified number of minutes.

Parameters

  • value: ValueOrGetter<number> Number of minutes.

Return TimeSpan

An object that represents value.

fromHours static method

ts
fromHours(value: ValueOrGetter<number>): TimeSpan

Get a TimeSpan object that represents a specified number of hours.

Parameters

  • value: ValueOrGetter<number> Number of hours.

Return TimeSpan

An object that represents value.

fromDays static method

ts
fromDays(value: ValueOrGetter<number>): TimeSpan

Get a TimeSpan object that represents a specified number of days.

Parameters

  • value: ValueOrGetter<number> Number of days.

Return TimeSpan

An object that represents value.

parse static method

ts
parse(str: string): TimeSpan

Converts a string representation of a time interval to its TimeSpan equivalent.

Parameters

  • str: string A string that specifies the time interval to convert.

Return TimeSpan

TimeSpan object

formatTimeSpan function

ts
function formatTimeSpan(ts: TimeSpan, formatStr: string): string

Converts the value of a TimeSpan object to string representation by using the specified format.

Parameters

  • ts: TimeSpan The TimeSpan object.
  • formatStr: string A custom format string.

Return string

The string representation of the TimeSpan value.

Format

You can use the formatted property or toString function to get formatted time interval according to the string of tokens passed in (-[d\.]hh:mm:ss[\.fff] by default).

ts
const time = new TimeSpan(251000);

console.log(time.formatted); // 00:04:11
console.log(time.toString('m:ss')); // 4:11

TIP

The [] token can be used in the format string to conditionally print time unit only when the absolute value of the total number (except for seconds fractions which in this case the value itself) is not zero, you can also add suffix and/or prefix but it should be with literal string delimiter '' or escape character \.

ts
const time = new TimeSpan(518651000);
console.log(time.toString('[d\\:][hh\\:]mm:ss[\\.fff]')); // 6:00:04:11

List of all available format tokens:

TokenOutputDescription
--Negative sign, which indicates a negative time interval.
++ -Positive or negative sign, that indicates the time interval.
d0-...The number of days.
dd-dddddddd00-...The number of days, padded with leading zeros as needed.
h0-23The number of hours.
hh00-23The number of hours, 2-digits.
H0-...The total number of hours.
HH0-...The total number of hours, padded with leading zeros as needed.
hh00-23The number of hours, 2-digits.
m0-59The number of minutes.
mm00-59The number of minutes, 2-digits.
M0-...The total number of minutes.
MM0-...The total number of minutes, padded with leading zeros as needed.
s0-59The number of seconds.
ss00-59The number of seconds, 2-digits.
S0-...The total number of seconds.
SS-SSSSSSSS00-...The total number of seconds, padded with leading zeros as needed.
f0-9The tenths of a second.
ff00-99The hundredths of a second.
fff000-999The number of milliseconds.
'string'stringLiteral string delimiter.
\SSThe escape character.
[hh\:]05:Conditionally print with suffix and/or prefix when the value of the total number is not zero.

MIT License, Made with ❤️