Class DataAPIDuration

Overview

Represents a duration column for Data API tables.

Internally represented as a number of months, days, and nanoseconds (units which are not directly convertible to each other).

Format

The duration may be one of four different formats:

Standard duration format

Matches -?(<number><unit>)+, where the unit is one of:

y (years; 12 months)
mo (months)
w (weeks; 7 days)
d (days)
h (hours; 3,600,000,000,000 nanoseconds)
m (minutes; 60,000,000,000 nanoseconds)
s (seconds; 1,000,000,000 nanoseconds)
ms (milliseconds; 1,000,000 nanoseconds)
us or µs (microseconds; 1,000 nanoseconds)
ns (nanoseconds)

At least one of the above units must be present, and they must be in the order shown above.

Units in this format are case-insensitive.

Example

duration('1y2mo3w4d5h6m7s8ms9us10ns');
duration('-2w');
duration('0s');

ISO 8601 duration format

Matches -?P<date>[T<time>]?, where <date> is (<number><date_unit>)* and <time> is (<number><time_unit>)+.

<date_unit> is one of:

Y (years)
M (months)
D (days)

<time_unit> is one of:

H (hours)
M (minutes)
S (seconds)

The P delimiter is required, and the T delimiter is only required if <time> is present.

Units (case-sensitive) must appear in the order shown above.

Milli/micro/nanoseconds may be provided as a fractional component of the seconds unit.

Example

duration('P1Y2M3DT4H5M6.007S');
duration('-P7D');
duration('PT0S');

ISO 8601 week duration format

Matches -?P<weeks>W exactly. No trailing T, or any other units, are allowed in this (case-sensitive) format.

Example

duration('P2W');
duration('-P2W');

ISO 8601 alternate duration format

Matches -?P<YYYY>-<MM>-<DD>T<hh>:<mm>:<ss> exactly.

The date and time components must be in the order, length, and case shown, and the P & T delimiters are required.

Example

duration('-P0001-02-03T04:05:06');

Creation

There are a few different ways to initialize a new DataAPIDuration:

Example

// Parse a duration given one of the above duration-string formats
new DataAPIDuration('1y2mo3w4d5h6m7s8ms9us10ns');
new DataAPIDuration('P1Y2M3DT4H5M6.007S');
new DataAPIDuration('-P2W');
new DataAPIDuration('P0001-02-03T04:05:06');

// Create a `DataAPIDuration` from months, days, and nanoseconds
new DataAPIDuration(0, 10, 1000 * 60 * 60 * 24 * 3).negate();

// Create a `DataAPIDuration` using the builder class
DataAPIDuration.builder()
  .addYears(1)
  .addDays(3)
  .addSeconds(5)
  .negate()
  .build();

The `duration` shorthand

You may use the duration shorthand function-object anywhere when creating new DataAPIDurations.

Example

// equiv. to `new DataAPIDuration('-2w')`
duration('-2w')

// equiv. to `new DataAPIDuration(2, 1, 0)`
duration(12, 1, 0)

// equiv. to `DataAPIDuration.builder().build()`
duration.builder().build()

See the official DataStax documentation for more information.

See

duration
DataAPIDurationBuilder

Implements

TableCodec<typeof DataAPIDuration>

Constructors

constructor

new DataAPIDuration(duration): DataAPIDuration
Overview
Parses a DataAPIDuration from a string in one of the supported formats.

See DataAPIDuration for more info about the supported formats.
Parameters
- duration: string
  The duration to parse
Returns DataAPIDuration
Example
```
new DataAPIDuration('1y2mo3w4d5h6m7s8ms9us10ns');

new DataAPIDuration('P1Y2M3DT4H5M6.007S');

duration('-2w');

duration('P0001-02-03T04:05:06');
```
- Defined in src/documents/datatypes/duration.ts:285
new DataAPIDuration(duration, fromDataAPI): DataAPIDuration
Internal
Should not be called by user directly.
Parameters
- duration: string
- fromDataAPI: boolean
Returns DataAPIDuration
- Defined in src/documents/datatypes/duration.ts:292
new DataAPIDuration(months, days, nanoseconds): DataAPIDuration
Overview
Creates a DataAPIDuration from the given months, days, and nanoseconds.

Either all parts must be positive, or all parts must be negative, to represent the duration's sign.

The parts must be integers in the following ranges:
- months and days must be less than or equal to 2147483647 (2^31 - 1)
- nanoseconds must be less than or equal to 9223372036854775807 (2^31 - 1)
Parameters
- months: number
  The months component of the duration
- days: number
  The days component of the duration
- nanoseconds: number | bigint
  The nanoseconds component of the duration
Returns DataAPIDuration
Example
```
new DataAPIDuration(2, 1, 0);

duration(0, 10, 1000 * 60 * 60 * 24 * 3).negate();
```
- Defined in src/documents/datatypes/duration.ts:316

Properties

`Readonly` days

days: number

The days component of this DataAPIDuration.

May be negative if and only if the other components are also negative.

`Readonly` months

months: number

The months component of this DataAPIDuration.

May be negative if and only if the other components are also negative.

`Readonly` nanoseconds

nanoseconds: bigint

The nanoseconds component of this DataAPIDuration.

May be negative if and only if the other components are also negative.

`Static` `Readonly` NS_PER_HOUR

NS_PER_HOUR: 3600000000000n = ...

Nanoseconds per hour.

`Static` `Readonly` NS_PER_MIN

NS_PER_MIN: 60000000000n = ...

Nanoseconds per minute.

`Static` `Readonly` NS_PER_MS

NS_PER_MS: 1000000n = ...

Nanoseconds per millisecond.

`Static` `Readonly` NS_PER_SEC

NS_PER_SEC: 1000000000n = ...

Nanoseconds per second.

`Static` `Readonly` NS_PER_US

NS_PER_US: 1000n = ...

Nanoseconds per microsecond.

Methods

[$SerializeForCollection]

[$SerializeForCollection](): void
Errorful implementation of $SerializeForCollection for TableCodec

Throws a human-readable error message warning that this datatype may not be used with collections without writing a custom ser/des codec.

Returns void
Implementation of TableCodec.[$SerializeForCollection]
- Defined in src/documents/datatypes/duration.ts:207

[$SerializeForTable]

[$SerializeForTable](ctx): readonly [0, undefined | string]
Implementation of $SerializeForTable for TableCodec
Parameters
- ctx: TableSerCtx
Returns readonly [0, undefined | string]
Implementation of TableCodec.[$SerializeForTable]
- Defined in src/documents/datatypes/duration.ts:216

abs

abs(): DataAPIDuration
Overview
Makes this DataAPIDuration unconditionally positive.

Returns DataAPIDuration
A new DataAPIDuration with the sign flipped
Example
```
duration('1y').abs() // '1y'

duration('-1y').abs() // '1y'
```
Implementation of TableCodec.abs
- Defined in src/documents/datatypes/duration.ts:493

equals

equals(other): boolean
Overview
Checks if this DataAPIDuration is equal to another DataAPIDuration.

Two durations are only equal if all of their individuals components are equal to each other.
Parameters
- other: DataAPIDuration
  The other DataAPIDuration to compare to
Returns boolean
true if the durations are exactly equal, or false otherwise
Example
```
duration('1y2d').equals(duration('P1Y2D')) // true

duration('-7d').equals(duration('-P1W')) // true

duration('1y').equals(duration('12mo')) // true

duration('1y').equals(duration('365d')) // false
```
Implementation of TableCodec.equals
- Defined in src/documents/datatypes/duration.ts:366

hasDayPrecision

hasDayPrecision(): boolean
Overview
Checks if this DataAPIDuration has day precision—that is, if the nanoseconds component is zero.

This means that no hours, minutes, seconds, milliseconds, microseconds, or nanoseconds are present.

Returns boolean
true if this DataAPIDuration has day precision, or false otherwise
Implementation of TableCodec.hasDayPrecision
- Defined in src/documents/datatypes/duration.ts:382

hasMillisecondPrecision

hasMillisecondPrecision(): boolean
Overview
Checks if this DataAPIDuration has millisecond precision—that is, if the nanoseconds component is a multiple of 1,000,000.

This means that no microseconds or nanoseconds are present.

If true, it entails that DataAPIDuration.nanoseconds & DataAPIDuration.toMicros may be safely cast to number.

Returns boolean
true if this DataAPIDuration has millisecond precision, or false otherwise
Implementation of TableCodec.hasMillisecondPrecision
- Defined in src/documents/datatypes/duration.ts:397

isNegative

isNegative(): boolean
Overview
Checks if the sign of this DataAPIDuration is negative.

Returns boolean
true if the sign of this DataAPIDuration is negative, or false otherwise
Implementation of TableCodec.isNegative
- Defined in src/documents/datatypes/duration.ts:408

isZero

isZero(): boolean
Overview
Checks if this DataAPIDuration is zero—that is, if all components are zero.

Returns boolean
true if this DataAPIDuration is zero, or false otherwise
Implementation of TableCodec.isZero
- Defined in src/documents/datatypes/duration.ts:419

negate

negate(): DataAPIDuration
Overview
Flips the sign of this DataAPIDuration.

Returns DataAPIDuration
A new DataAPIDuration with the sign flipped
Example
```
duration('1y').negate() // '-1y'

duration('-1y').negate() // '1y'
```
Implementation of TableCodec.negate
- Defined in src/documents/datatypes/duration.ts:475

plus

plus(other): null | DataAPIDuration
Overview
Returns a new DataAPIDuration that is the sum of this DataAPIDuration and another DataAPIDuration.

Each component of the other DataAPIDuration is added to the corresponding component of this DataAPIDuration.

However, if the signs of the two durations differ, null is returned. A positive duration cannot be added to a negative duration, and vice versa.
Parameters
- other: DataAPIDuration
  The other DataAPIDuration to add to this DataAPIDuration
Returns null | DataAPIDuration
A new DataAPIDuration that is the sum of this DataAPIDuration and the other DataAPIDuration, or null if the signs differ
Example
```
duration('1y').plus(duration('1y')) // '2y'

duration('1y').plus(duration('1mo1s')) // '1y1mo1s'

duration('1y').plus(duration('-1mo').abs()) // '1y1mo'

duration('1y').plus(duration('-1mo')) // null
```
Note that this may lead to an error being thrown if any of the individual components exceed their maximum values.
Implementation of TableCodec.plus
- Defined in src/documents/datatypes/duration.ts:449

toHours

toHours(): number
Overview
Returns the number of hours in this DataAPIDuration, calculated solely from the nanoseconds component.

Note: this does not factor in the months or days components.

Equivalent to Number(duration.nanoseconds / 3_600_000_000_000).

Returns number
The number of hours in this DataAPIDuration derived from the nanoseconds component
Example
```
duration('10m').toHours() // 0

duration('-50h150m').toHours() // -52

duration('1y15mo1h').toHours() // 1

duration('500d').toHours() // 0
```
Implementation of TableCodec.toHours
- Defined in src/documents/datatypes/duration.ts:543

toMicros

toMicros(): bigint
Overview
Returns the number of microseconds in this DataAPIDuration, calculated solely from the nanoseconds component.

Note: this does not factor in the months or days components.

Equivalent to Number(duration.nanoseconds / 1_000).

Returns bigint
The number of microseconds in this DataAPIDuration derived from the nanoseconds component
Example
```
duration('1y50us').toMicros() // 50n

duration('1y50ns').toMicros() // 0n

duration('1h50ns').toMicros() // 3600000000n
```
Implementation of TableCodec.toMicros
- Defined in src/documents/datatypes/duration.ts:639

toMillis

toMillis(): number
Overview
Returns the number of milliseconds in this DataAPIDuration, calculated solely from the nanoseconds component.

Note: this does not factor in the months or days components.

Equivalent to Number(duration.nanoseconds / 1_000_000).

Returns number
The number of milliseconds in this DataAPIDuration derived from the nanoseconds component
Example
```
duration('10ns').toMillis() // 0

duration('1y50h150m').toMillis() // 189000000

duration('-1y15mo1h').toMillis() // -3600000
```
Implementation of TableCodec.toMillis
- Defined in src/documents/datatypes/duration.ts:615

toMinutes

toMinutes(): number
Overview
Returns the number of minutes in this DataAPIDuration, calculated solely from the nanoseconds component.

Note: this does not factor in the months or days components.

Equivalent to Number(duration.nanoseconds / 60_000_000_000).

Returns number
The number of minutes in this DataAPIDuration derived from the nanoseconds component
Example
```
duration('10ms').toMinutes() // 0

duration('2y50h150m').toMinutes() // 3150

duration('-1y15mo1h').toMinutes() // -60
```
Implementation of TableCodec.toMinutes
- Defined in src/documents/datatypes/duration.ts:567

toSeconds

toSeconds(): number
Overview
Returns the number of seconds in this DataAPIDuration, calculated solely from the nanoseconds component.

Note: this does not factor in the months or days components.

Equivalent to Number(duration.nanoseconds / 1_000_000_000).

Returns number
The number of seconds in this DataAPIDuration derived from the nanoseconds component
Example
```
duration('10ns').toSeconds() // 0

duration('1y50h150m').toSeconds() // 189000

duration('-1y15mo1h').toSeconds() // -3600
```
Implementation of TableCodec.toSeconds
- Defined in src/documents/datatypes/duration.ts:591

toString

toString(): string
Overview
Returns the human-friendly string representation of this DataAPIDuration

Returns string
The string representation of this DataAPIDuration
Example
```
duration('15mo').toString() // '1y3mo'

duration('-5ms10000us').toString() // '-15ms'
```
Implementation of TableCodec.toString
- Defined in src/documents/datatypes/duration.ts:657

toYears

toYears(): number
Overview
Returns the number of years in this DataAPIDuration, calculated solely from the months component.

Note: this does not factor in the days or nanoseconds components.

Equivalent to Math.floor(duration.months / 12).

Returns number
The number of years in this DataAPIDuration derived from the months component
Example
```
duration('1y15mo').toYears() // 2

duration('-1y15mo').toYears() // -2

duration('1y800d').toYears() // 1
```
Implementation of TableCodec.toYears
- Defined in src/documents/datatypes/duration.ts:517

`Static` [$DeserializeForTable]

[$DeserializeForTable](value, ctx): readonly [0, undefined | DataAPIDuration]
Implementation of $DeserializeForTable for TableCodec
Parameters
- value: any
- ctx: TableDesCtx
Returns readonly [0, undefined | DataAPIDuration]
- Defined in src/documents/datatypes/duration.ts:223

`Static` builder

builder(this, base?): DataAPIDurationBuilder
Overview
Helpful utility for manually creating new DataAPIDuration instances.

Contains builder methods for incrementally adding duration components, and negating the final result.

Usage
You may call each .add*() method any number of times, in any order, before calling build.

The .negate(sign?) method may be called at any time to negate the final result.
- You may pass a boolean to .negate(sign?) to definitively set the sign
- Otherwise, the sign will be toggled.
A base duration may be provided to initialize the builder with its components and its sign.
Parameters
- this: void
- Optional base: DataAPIDuration
  The base DataAPIDuration to initialize the builder with, if any
Returns DataAPIDurationBuilder
Example
```
const base = duration('1y');

// '-1y3d15h'
const span = duration.builder(base)
  .addHours(10)
  .addDays(3)
  .addHours(5)
  .negate()
  .build();
```
See
DataAPIDurationBuilder
- Defined in src/documents/datatypes/duration.ts:261

Class DataAPIDuration

Example

Example

Example

Example

Example

Example

See

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DataAPIDuration

Example

Parameters

Returns DataAPIDuration

Parameters

Returns DataAPIDuration

Example

Properties

Readonly days

Readonly months

Readonly nanoseconds

Static Readonly NS_PER_HOUR

Static Readonly NS_PER_MIN

Static Readonly NS_PER_MS

Static Readonly NS_PER_SEC

Static Readonly NS_PER_US

Methods

[$SerializeForCollection]

Returns void

[$SerializeForTable]

Parameters

Returns readonly [0, undefined | string]

abs

Returns DataAPIDuration

Example

equals

Parameters

Returns boolean

Example

hasDayPrecision

Returns boolean

hasMillisecondPrecision

Returns boolean

isNegative

Returns boolean

isZero

Returns boolean

negate

Returns DataAPIDuration

Example

plus

Parameters

Returns null | DataAPIDuration

Example

toHours

Returns number

Example

toMicros

Returns bigint

Example

toMillis

Returns number

Example

toMinutes

Returns number

Example

toSeconds

Returns number

Example

toString

Returns string

Example

toYears

Returns number

`Readonly` days

`Readonly` months

`Readonly` nanoseconds

`Static` `Readonly` NS_PER_HOUR

`Static` `Readonly` NS_PER_MIN

`Static` `Readonly` NS_PER_MS

`Static` `Readonly` NS_PER_SEC

`Static` `Readonly` NS_PER_US

`Static` [$DeserializeForTable]

`Static` builder