Documentation

Documentation / @zerotal/core / datetime / CarbonInterval

Class: CarbonInterval

Defined in: datetime/CarbonInterval.ts:44

An immutable, calendar-aware duration backed by Temporal.Duration; every modifier returns a new instance. Build durations fluently, do arithmetic on them, apply them to a Carbon, and render them for humans or as ISO 8601.

Example

import { Carbon, CarbonInterval } from "@zerotal/core/carbon";

const span = CarbonInterval.days(1).andHours(2).andMinutes(30);
span.forHumans();          // "1 day 2 hours 30 minutes"
span.toISO();              // "P1DT2H30M"
Carbon.now().add(span);    // apply to a date

CarbonInterval.fromISO("PT90M").cascade(); // → 1 hour 30 minutes

Constructors

Constructor

new CarbonInterval(duration?): CarbonInterval

Defined in: datetime/CarbonInterval.ts:48

Parameters

duration?

DurationLike | Duration

Returns

CarbonInterval

Accessors

years

Get Signature

get years(): number

Defined in: datetime/CarbonInterval.ts:139

Returns

number

months

Get Signature

get months(): number

Defined in: datetime/CarbonInterval.ts:142

Returns

number

weeks

Get Signature

get weeks(): number

Defined in: datetime/CarbonInterval.ts:145

Returns

number

days

Get Signature

get days(): number

Defined in: datetime/CarbonInterval.ts:148

Returns

number

hours

Get Signature

get hours(): number

Defined in: datetime/CarbonInterval.ts:151

Returns

number

minutes

Get Signature

get minutes(): number

Defined in: datetime/CarbonInterval.ts:154

Returns

number

seconds

Get Signature

get seconds(): number

Defined in: datetime/CarbonInterval.ts:157

Returns

number

milliseconds

Get Signature

get milliseconds(): number

Defined in: datetime/CarbonInterval.ts:160

Returns

number

microseconds

Get Signature

get microseconds(): number

Defined in: datetime/CarbonInterval.ts:163

Returns

number

nanoseconds

Get Signature

get nanoseconds(): number

Defined in: datetime/CarbonInterval.ts:166

Returns

number

sign

Get Signature

get sign(): -1 | 0 | 1

Defined in: datetime/CarbonInterval.ts:171

Sign of the duration: 1, -1, or 0.

Returns

-1 | 0 | 1

isZero

Get Signature

get isZero(): boolean

Defined in: datetime/CarbonInterval.ts:175

Returns

boolean

Methods

years()

static years(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:77

Parameters

amount

number

Returns

CarbonInterval

months()

static months(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:80

Parameters

amount

number

Returns

CarbonInterval

weeks()

static weeks(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:83

Parameters

amount

number

Returns

CarbonInterval

days()

static days(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:86

Parameters

amount

number

Returns

CarbonInterval

hours()

static hours(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:89

Parameters

amount

number

Returns

CarbonInterval

minutes()

static minutes(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:92

Parameters

amount

number

Returns

CarbonInterval

seconds()

static seconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:95

Parameters

amount

number

Returns

CarbonInterval

milliseconds()

static milliseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:98

Parameters

amount

number

Returns

CarbonInterval

microseconds()

static microseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:101

Parameters

amount

number

Returns

CarbonInterval

nanoseconds()

static nanoseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:104

Parameters

amount

number

Returns

CarbonInterval

fromDuration()

static fromDuration(duration): CarbonInterval

Defined in: datetime/CarbonInterval.ts:115

Wrap an existing Temporal.Duration.

Parameters

duration

Duration

Returns

CarbonInterval

Example

const dur = Temporal.Duration.from('P1Y2M3DT4H5M6S');
const interval = CarbonInterval.fromDuration(dur);

fromISO()

static fromISO(iso): CarbonInterval

Defined in: datetime/CarbonInterval.ts:126

Parse an ISO 8601 duration string.

Parameters

iso

string

Returns

CarbonInterval

Example

CarbonInterval.fromISO('P1Y2M3DT4H5M6S')
CarbonInterval.fromISO('PT30M')

abs()

static abs(interval): CarbonInterval

Defined in: datetime/CarbonInterval.ts:133

Return the absolute (non-negative) version of all fields.

Parameters

interval

CarbonInterval

Returns

CarbonInterval

andYears()

andYears(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:187

Return a new interval that also adds the given years.

Parameters

amount

number

Returns

CarbonInterval

Example

CarbonInterval.days(3).andHours(6).andMinutes(30)

andMonths()

andMonths(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:190

Parameters

amount

number

Returns

CarbonInterval

andWeeks()

andWeeks(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:193

Parameters

amount

number

Returns

CarbonInterval

andDays()

andDays(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:196

Parameters

amount

number

Returns

CarbonInterval

andHours()

andHours(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:199

Parameters

amount

number

Returns

CarbonInterval

andMinutes()

andMinutes(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:202

Parameters

amount

number

Returns

CarbonInterval

andSeconds()

andSeconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:205

Parameters

amount

number

Returns

CarbonInterval

andMilliseconds()

andMilliseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:208

Parameters

amount

number

Returns

CarbonInterval

andMicroseconds()

andMicroseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:211

Parameters

amount

number

Returns

CarbonInterval

andNanoseconds()

andNanoseconds(amount): CarbonInterval

Defined in: datetime/CarbonInterval.ts:214

Parameters

amount

number

Returns

CarbonInterval

add()

add(other): CarbonInterval

Defined in: datetime/CarbonInterval.ts:226

Return a new interval that is the sum of this and another.

Parameters

other

CarbonInterval

Returns

CarbonInterval

Example

CarbonInterval.hours(2).add(CarbonInterval.minutes(30))

subtract()

subtract(other): CarbonInterval

Defined in: datetime/CarbonInterval.ts:233

Return a new interval that is this minus another.

Parameters

other

CarbonInterval

Returns

CarbonInterval

negate()

negate(): CarbonInterval

Defined in: datetime/CarbonInterval.ts:240

Return a new interval with all fields negated.

Returns

CarbonInterval

abs()

abs(): CarbonInterval

Defined in: datetime/CarbonInterval.ts:247

Return a new interval with all negative fields made positive.

Returns

CarbonInterval

multiply()

multiply(factor): CarbonInterval

Defined in: datetime/CarbonInterval.ts:257

Multiply all fields by a scalar.

Parameters

factor

number

Returns

CarbonInterval

Example

CarbonInterval.hours(1).multiply(3)  // → 3 hours

cascade()

cascade(relativeTo?): CarbonInterval

Defined in: datetime/CarbonInterval.ts:287

Cascade (normalize) excess sub-units up to higher units.

Requires a reference ZonedDateTime to resolve calendar ambiguities (e.g. how many days are in a month). Defaults to "now" in UTC.

Parameters

relativeTo?

ZonedDateTime

Returns

CarbonInterval

Example

CarbonInterval.seconds(90).cascade()
// → CarbonInterval { minutes: 1, seconds: 30 }

CarbonInterval.minutes(90).cascade()
// → CarbonInterval { hours: 1, minutes: 30 }

totalSeconds()

totalSeconds(): number

Defined in: datetime/CarbonInterval.ts:302

Convert this interval to a total number of seconds. Calendar units (years, months) are approximated.

Returns

number

totalMinutes()

totalMinutes(): number

Defined in: datetime/CarbonInterval.ts:317

Returns

number

totalHours()

totalHours(): number

Defined in: datetime/CarbonInterval.ts:320

Returns

number

totalDays()

totalDays(): number

Defined in: datetime/CarbonInterval.ts:323

Returns

number

totalWeeks()

totalWeeks(): number

Defined in: datetime/CarbonInterval.ts:326

Returns

number

forHumans()

forHumans(options?): string

Defined in: datetime/CarbonInterval.ts:342

Return a human-readable description of the interval.

Parameters

options?

join?

string

short?

boolean

Returns

string

Example

CarbonInterval.days(1).andHours(2).andMinutes(30).forHumans()
// → "1 day 2 hours 30 minutes"

CarbonInterval.years(2).andMonths(3).forHumans({ join: ' and ' })
// → "2 years and 3 months"

toISO()

toISO(): string

Defined in: datetime/CarbonInterval.ts:381

Return the ISO 8601 duration string.

Returns

string

Example

CarbonInterval.days(1).andHours(2).toISO()
// → "P1DT2H"

toJSON()

toJSON(): string

Defined in: datetime/CarbonInterval.ts:386

Alias for toISO(). Used by JSON.stringify.

Returns

string

toString()

toString(): string

Defined in: datetime/CarbonInterval.ts:390

Returns

string

toDuration()

toDuration(): Duration

Defined in: datetime/CarbonInterval.ts:395

Return the backing Temporal.Duration.

Returns

Duration

compare()

static compare(a, b): -1 | 0 | 1

Defined in: datetime/CarbonInterval.ts:405

Compare two intervals by total seconds (approximate for calendar units). Returns -1, 0, or 1.

Parameters

a

CarbonInterval

b

CarbonInterval

Returns

-1 | 0 | 1

isLessThan()

isLessThan(other): boolean

Defined in: datetime/CarbonInterval.ts:412

Parameters

other

CarbonInterval

Returns

boolean

isGreaterThan()

isGreaterThan(other): boolean

Defined in: datetime/CarbonInterval.ts:415

Parameters

other

CarbonInterval

Returns

boolean

isEqualTo()

isEqualTo(other): boolean

Defined in: datetime/CarbonInterval.ts:418

Parameters

other

CarbonInterval

Returns

boolean