Utilix

Appearance

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)

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 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 ❤️

© 2024 Waleed-KH