Class DataAPITime

Overview

Represents a time column for Data API tables.

Format

times consist of an hour, a minute, and optional second and nanosecond components.

The hour is a number from 0 to 23, and must be positive.
The minute is a number from 0 to 59.
The second is a number from 0 to 59, and will default to 0 if not provided.
The nanosecond is a fractional component of the second, and will default to 0 if not provided.
- It is a number up to 9 digits long.
- If any digits are omitted, they are assumed to be 0.
- e.g. 12:34:56.789 is equivalent to 12:34:56.789000000.
- Seconds must be provided if nanoseconds are provided.

Together, the format would be as such: HH:MM[:SS[.NNNNNNNNN]].

Creation

There are a number of different ways to initialize a DataAPITime:

Example

// Convert a native JS `Date` to a `DataAPITime` (extracting only the local time)
new DataAPITIme(new Date('2004-09-14T12:00:00.000')) // '12:00:00.000000000'

// Parse a time given the above time-string format
new DataAPITime('12:34:56.78') // '12:34:56.780000000'

// Create a `DataAPIDate` from an hour, a minute, and optional second and nanosecond components
new DataAPITime(12, 34, 56, 78) // '12:34:56.000000078'

// Get the current time (using the local timezone)
DataAPITime.now()

// Get the current time (using UTC)
DataAPITime.utcnow()

// Create a `DataAPITime` from the number of nanoseconds since the start of the day
DataAPITime.ofNanoOfDay(12_345_678_912_345) // '03:25:45.678912345'

// Create a `DataAPITime` from the number of seconds since the start of the day
DataAPITime.ofSecondOfDay(12_345) // '03:25:45.000000000'

The `time` shorthand

You may use the time shorthand function-object anywhere when creating new DataAPITimes.

Example

// equiv. to `new DataAPITime('12:34:56')`
time('12:34:56')

// equiv. to `new DataAPITime(12, 34, 56)`
time(12, 34, 56)

// equiv. to `DataAPITime.now()`
time.now()

See the official DataStax documentation for more information.

See

time

Implements

TableCodec<typeof DataAPITime>

Index

Constructors

constructor

new DataAPITime(time): DataAPITime
Overview
Converts a native JS Date to a DataAPITime (extracting only the local time).
Parameters
- time: Date
  The Date object to convert
Returns DataAPITime
Example
```
new DataAPITime(new Date('2004-09-14T12:00:00.000')) // '12:00:00.000000000'

time(new Date('12:34:56.78')) // '12:34:56.780000000'
```
- Defined in src/documents/datatypes/time.ts:245
new DataAPITime(time): DataAPITime
Overview
Parses a DataAPITime from a string in the format HH:MM[:SS[.NNNNNNNNN]].

See DataAPITime for more info about the exact format.
Parameters
- time: string
  The time string to parse
Returns DataAPITime
Example
```
new DataAPITime('12:00') // '12:00:00.000000000'

time('12:34:56.78') // '12:34:56.780000000'
```
- Defined in src/documents/datatypes/time.ts:263
new DataAPITime(time, strict): DataAPITime
Internal
Should not be called by user directly.
Parameters
- time: string
- strict: boolean
Returns DataAPITime
- Defined in src/documents/datatypes/time.ts:270
new DataAPITime(hours, minutes, seconds?, nanoseconds?): DataAPITime
Overview
Creates a DataAPITime from an hour, a minute, and optional second and nanosecond components.

All components must be zero-indexed positive integers within the following ranges:
- hour: [0, 23]
- minute: [0, 59]
- second: [0, 59]
- nanosecond: [0, 999,999,999]
Parameters
- hours: number
  The hour to use
- minutes: number
  The minute to use
- Optional seconds: number
  The second to use (defaults to 0)
- Optional nanoseconds: number
  The nanosecond to use (defaults to 0)
Returns DataAPITime
Example
```
new DataAPIDate(20, 15) // '20:15:00.000000000'

date(12, 12, 12, 12) // '12:12:12.000000012'
```
- Defined in src/documents/datatypes/time.ts:295

Properties

`Readonly` hours

hours: number

The hour component of this DataAPITime.

Must be between 0-23.

`Readonly` minutes

minutes: number

The minute component of this DataAPITime.

Must be between 0-59.

`Readonly` nanoseconds

nanoseconds: number

The nanosecond component of this DataAPITime.

Must be between 0-999,999,999.

`Readonly` seconds

seconds: number

The second component of this DataAPITime.

Must be between 0-59.

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/time.ts:126

[$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/time.ts:136

compare

compare(other): -1 | 0 | 1
Overview
Compares this DataAPITime to another DataAPITime
Parameters
- other: DataAPITime
  The other DataAPITime to compare to
Returns -1 | 0 | 1
0 if the times are equal, -1 if this time is before the other, and 1 if this time is after the other
Example
```
time('12:00').compare(time(12, 0)) // 0

time('12:00').compare(time(12, 1)) // -1

time('12:01').compare(time(12, 0)) // 1
```
Implementation of TableCodec.compare
- Defined in src/documents/datatypes/time.ts:477

equals

equals(other): boolean
Overview
Checks if this DataAPITime is equal to another DataAPITime
Parameters
- other: string | DataAPITime
  The other DataAPITime to compare to
Returns boolean
true if the times are equal, and false otherwise
Example
```
time('12:00').equals(time(12, 0)) // true

time('12:00').equals(time(12, 1)) // false

time('12:00').equals('12:00:00.000000000') // true
```
Implementation of TableCodec.equals
- Defined in src/documents/datatypes/time.ts:515

toDate

toDate(base?): Date
Overview
Converts this DataAPITime to a Date object in the local timezone.

If no base date is provided, the time component defaults to the current local date.

If the base parameter is a DataAPIDate, it is interpreted as being in the local timezone, not UTC.

See DataAPITime.toDateUTC for a UTC-based alternative to this method.
Parameters
- Optional base: Date | DataAPIDate
  The base date to use for the date component. If omitted, defaults to the current local date.
Returns Date
The Date object representing this DataAPITime in the local timezone.
Example
```
// Assuming the local timezone is UTC-6 (CST) //

// Local Time: '2000-01-01T12:00:00'
// UTC Time:   '2000-01-01T18:00:00Z'
time('12:00:00').toDate(new Date('2000-01-01T00:00:00'));

// Local Time: '1999-12-31T12:00:00'
// UTC Time:   '1999-12-31T18:00:00Z'
time('12:00:00').toDate(new Date('2000-01-01T00:00:00Z'));

// Local Time: '2000-01-01T12:00:00'
// UTC Time:   '2000-01-01T18:00:00Z'
time('12:00:00').toDate(new DataAPIDate('2000-01-01'));

// Local Time: '2025-01-22T12:00:00'
// UTC Time:   '2025-01-22T18:00:00Z'
time('12:00:00').toDate();
```
See
DataAPITime.toDateUTC
Implementation of TableCodec.toDate
- Defined in src/documents/datatypes/time.ts:381

toDateUTC

toDateUTC(base?): Date
Overview
Converts this DataAPITime to a Date object in UTC.

If no base date is provided, the time component defaults to the current date in UTC.

If the base parameter is a DataAPIDate, it is interpreted as being in the UTC timezone.

See DataAPITime.toDate for a local-date-based alternative to this method.
Parameters
- Optional base: Date | DataAPIDate
  The base date to use for the date component. If omitted, defaults to the current date in UTC.
Returns Date
The Date object representing this DataAPITime in UTC.
Example
```
// Assuming the local timezone is UTC-6 (CST) //

// Local Time: '2000-01-01T06:00:00'
// UTC Time:   '2000-01-01T12:00:00Z'
time('12:00:00').toDateUTC(new Date('2000-01-01T00:00:00'));

// Local Time: '2000-01-01T06:00:00Z'
// UTC Time:   '2000-01-01T12:00:00Z'
time('12:00:00').toDateUTC(new Date('2000-01-01T00:00:00Z'));

// Local Time: '2000-01-01T06:00:00'
// UTC Time:   '2000-01-01T12:00:00Z'
time('12:00:00').toDateUTC(new DataAPIDate('2000-01-01'));

// Local Time: '2025-01-22T06:00:00'
// UTC Time:   '2025-01-22T12:00:00Z'
time('12:00:00').toDateUTC();
```
See
DataAPITime.toDate
Implementation of TableCodec.toDateUTC
- Defined in src/documents/datatypes/time.ts:429

toString

toString(): string
Overview
Returns the string representation of this DataAPITime

Note that it'll contain the second & nanosecond components, even if they weren't provided.

Returns string
The string representation of this DataAPITime
Example
```
time('12:00').toString() // '12:00:00.000000000'

time(12, 34, 56, 78).toString() // '12:34:56.000000078'
```
Implementation of TableCodec.toString
- Defined in src/documents/datatypes/time.ts:455

`Static` [$DeserializeForTable]

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

`Static` now

now(this): DataAPITime
Overview
Returns the current time in the local timezone.

Equivalent to new DataAPITime(new Date()).
Parameters
- this: void
Returns DataAPITime
The current time in the local timezone
Example
```
const now = time.now();
// or
const now = DataAPITime.now()
```
- Defined in src/documents/datatypes/time.ts:163

`Static` ofNanoOfDay

ofNanoOfDay(this, nanoOfDay): DataAPITime
Overview
Creates a DataAPITime from the number of nanoseconds since the start of the day .

The number must be a positive integer in the range [0, 86,399,999,999,999].
Parameters
- this: void
- nanoOfDay: number
  The number of nanoseconds since the start of the day
Returns DataAPITime
The DataAPITime representing the given number of nanoseconds
Example
```
DataAPITime.ofNanoOfDay(0) // '00:00:00.000000000'

date.ofNanoOfDay(12_345_678_912_345) // '03:25:45.678912345'
```
- Defined in src/documents/datatypes/time.ts:205

`Static` ofSecondOfDay

ofSecondOfDay(this, secondOfDay): DataAPITime
Overview
Creates a DataAPITime from the number of seconds since the start of the day.

The number must be a positive integer in the range [0, 86,399].
Parameters
- this: void
- secondOfDay: number
  The number of seconds since the start of the day
Returns DataAPITime
The DataAPITime representing the given number of seconds
Example
```
DataAPITime.ofSecondOfDay(0) // '00:00:00.000000000'

DataAPITime.ofSecondOfDay(12_345) // '03:25:45.000000000'
```
- Defined in src/documents/datatypes/time.ts:227

`Static` utcnow

utcnow(this): DataAPITime
Overview
Returns the current time in UTC.

Uses Date.now() under the hood.
Parameters
- this: void
Returns DataAPITime
The current time in UTC
Example
```
const now = time.utcnow();
// or
const now = DataAPITime.utcnow()
```
- Defined in src/documents/datatypes/time.ts:183

Class DataAPITime

Example

Example

See

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DataAPITime

Example

Parameters

Returns DataAPITime

Example

Parameters

Returns DataAPITime

Parameters

Returns DataAPITime

Example

Properties

Readonly hours

Readonly minutes

Readonly nanoseconds

Readonly seconds

Methods

[$SerializeForCollection]

Returns void

[$SerializeForTable]

Parameters

Returns readonly [0, undefined | string]

compare

Parameters

Returns -1 | 0 | 1

Example

equals

Parameters

Returns boolean

Example

toDate

Parameters

Returns Date

Example

See

toDateUTC

Parameters

Returns Date

Example

See

toString

Returns string

Example

Static [$DeserializeForTable]

Parameters

Returns readonly [0, undefined | DataAPITime]

Static now

Parameters

Returns DataAPITime

Example

Static ofNanoOfDay

Parameters

Returns DataAPITime

Example

Static ofSecondOfDay

Parameters

Returns DataAPITime

Example

Static utcnow

Parameters

Returns DataAPITime

Example

Settings

Member Visibility

Theme

On This Page

`Readonly` hours

`Readonly` minutes

`Readonly` nanoseconds

`Readonly` seconds

`Static` [$DeserializeForTable]

`Static` now

`Static` ofNanoOfDay

`Static` ofSecondOfDay

`Static` utcnow