Class DataAPIDate

Overview

Represents a date column for Data API tables,

Format

dates consist simply of a year, a month, and a date.

The year may be either positive or negative, and must be at least four digits long (with leading padding zeros if necessary).
The month must be between 1-12 (not zero-indexed like JS dates), and must be two digits long.
The day must be a valid day for the given month, and starts at 1. It must also be two digits long. Feb 29th is allowed on leap years

Together, the hypothetical pseudo-regex would be as such: [+-]?YYY(Y+)-MM-DD.

Note that the DataAPIDate's parser is lenient on if the leading + is included or not. For example, +2000-01-01 is accepted, even if it is not technically valid; same with 10000-01-01. A plus will be prepended in DataAPIDate.toString as necessary.

Creation

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

Example

// Convert a native JS `Date` to a `DataAPIDate` (extracting only the local date)
new DataAPIDate(new Date('2004-09-14T12:00:00.000')) // '2004-09-14'

// Parse a date given the above date-string format
new DataAPIDate('+2004-09-14')

// Create a `DataAPIDate` from a year, a month, and a date
new DataAPIDate(2004, 9, 14)

// Get the current date (using the local timezone)
DataAPIDate.now()

// Get the current date (using UTC)
DataAPIDate.utcnow()

// Create a `DataAPIDate` from a year and a valid day of the year
DataAPIDate.ofYearDay(2004, 258) // '2004-09-14'

// Create a `DataAPIDate` given the number of days since the epoch (may be negative)
DataAPIDate.ofEpochDay(12675) // '2004-09-14'

The `date` shorthand

You may use the date shorthand function-object anywhere when creating new DataAPIDates.

Example

// equiv. to `new DataAPIDate('2004-09-14')`
date('2004-09-14')

// equiv. to `new DataAPIDate(2004, 9, 14)`
date(2004, 9, 14)

// equiv. to `DataAPIDate.now()`
date.now()

See the official DataStax documentation for more information.

See

date

Implements

TableCodec<typeof DataAPIDate>

Index

Constructors

constructor

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

date(new Date('-200004-09-14')) // '200004-09-14'
```
- Defined in src/documents/datatypes/date.ts:233
new DataAPIDate(date): DataAPIDate
Overview
Parses a DataAPIDate from a string in the format [+-]?YYY(Y+)-MM-DD.

See DataAPIDate for more info about the exact format.
Parameters
- date: string
  The date to parse
Returns DataAPIDate
Example
```
new DataAPIDate('2004-09-14') // '2004-09-14'

date('-2004-09-14') // '-2004-09-14'

date('+123456-09-14') // '123456-09-14'
```
- Defined in src/documents/datatypes/date.ts:253
new DataAPIDate(time, strict): DataAPIDate
Internal
Should not be called by user directly.
Parameters
- time: string
- strict: boolean
Returns DataAPIDate
- Defined in src/documents/datatypes/date.ts:260
new DataAPIDate(year, month, date): DataAPIDate
Overview
Creates a DataAPIDate from a year, a month, and a date.

The year may be negative. The month and day are both 1-indexed.

The date must be valid for the given month, otherwise an exception will be thrown.
Parameters
- year: number
  The year to use
- month: number
  The month to use (1-indexed)
- date: number
  The date to use (1-indexed)
Returns DataAPIDate
Example
```
new DataAPIDate(2004, 9, 14) // '2004-09-14'

date(-200004, 9, 14) // '-200004-09-14'
```
- Defined in src/documents/datatypes/date.ts:282

Properties

`Readonly` date

date: number

The date component of this DataAPIDate.

Must be a valid day for the given month.

`Readonly` month

month: number

The month component of this DataAPIDate.

Must be between 1-12.

`Readonly` year

year: number

The year component of this DataAPIDate.

May be negative.

Methods

[$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/date.ts:117

compare

compare(other): -1 | 0 | 1
Overview
Compares this DataAPIDate to another DataAPIDate
Parameters
- other: DataAPIDate
  The other DataAPIDate to compare to
Returns -1 | 0 | 1
0 if the dates are equal, -1 if this date is before the other, and 1 if this date is after the other
Example
```
date('2004-09-14').compare(date(2004, 9, 14)) // 0

date('2004-09-14').compare(date(2004, 9, 15)) // -1

date('2004-09-15').compare(date(2004, 9, 14)) // 1
```
Implementation of TableCodec.compare
- Defined in src/documents/datatypes/date.ts:494

equals

equals(other): boolean
Overview
Checks if this DataAPIDate is equal to another DataAPIDate
Parameters
- other: DataAPIDate
  The other DataAPIDate to compare to
Returns boolean
true if the dates are equal, and false otherwise
Example
```
date('2004-09-14').equals(date(2004, 9, 14)) // true

date('2004-09-14').equals(date(2004, 9, 15)) // false

date('2004-09-15').equals(date(2004, 9, 14)) // false
```
Implementation of TableCodec.equals
- Defined in src/documents/datatypes/date.ts:528

plus

plus(duration): DataAPIDate
Overview
Adds a DataAPIDuration or a duration string to this DataAPIDate.

Duration strings will be parsed into a DataAPIDuration before being added.

Durations may be negative, in which case the duration will be subtracted from this date.
Parameters
- duration: string | DataAPIDuration
  The duration to add to this DataAPIDate
Returns DataAPIDate
A new DataAPIDate representing the result of adding the duration to this date
Example
```
date('2000-01-01').plus('1y47h59m') // '2001-01-02'

date('2000-01-01').plus('365d') // '2000-12-31'

date('2000-01-01').plus('366d') // '2001-01-01'
```
Implementation of TableCodec.plus
- Defined in src/documents/datatypes/date.ts:435

toDate

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

If no base date/time is provided, the time component defaults to 00:00:00 (local time).

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

See DataAPIDate.toDateUTC for a UTC-based alternative to this method.
Parameters
- Optional base: Date | DataAPITime
  The base date/time to use for the time component. If omitted, defaults to 00:00:00 (local time).
Returns Date
The Date object representing this DataAPIDate 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'
date('2000-01-01').toDate(new Date('1970-01-01T12:00:00'));

// Local Time: '2000-01-01T06:00:00'
// UTC Time:   '2000-01-01T12:00:00Z'
date('2000-01-01').toDate(new Date('1970-01-01T12:00:00Z'));

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

// Local Time: '2000-01-01T00:00:00'
// UTC Time:   '2000-01-01T06:00:00Z'
date('2000-01-01').toDate();
```
See
DataAPIDate.toDateUTC
Implementation of TableCodec.toDate
- Defined in src/documents/datatypes/date.ts:361

toDateUTC

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

If no base date/time is provided, the time component defaults to 00:00:00 (UTC).

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

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

// Local Time: '2000-01-01T12:00:00'
// UTC Time:   '2000-01-01T18:00:00Z'
date('2000-01-01').toDateUTC(new Date('1970-01-01T12:00:00'));

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

// Local Time: '2000-01-01T12:00:00'
// UTC Time:   '2000-01-01T18:00:00Z'
date('2000-01-01').toDateUTC(new DataAPITime('12:00:00'));

// Local Time: '1999-12-31T18:00:00'
// UTC Time:   '2000-01-01T00:00:00Z'
date('2000-01-01').toDateUTC();
```
See
DataAPIDate.toDate
Implementation of TableCodec.toDateUTC
- Defined in src/documents/datatypes/date.ts:406

toString

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

Note that a + is prepended to the year if it is greater than or equal to 10000.

Returns string
The string representation of this DataAPIDate
Example
```
date('2004-09-14').toString() // '2004-09-14'

date(-2004, 9, 14).toString() // '-2004-09-14'

date('123456-01-01').toString() // '+123456-01-01'
```
Implementation of TableCodec.toString
- Defined in src/documents/datatypes/date.ts:471

`Static` [$DeserializeForTable]

[$DeserializeForTable](value, ctx): readonly [0, undefined | DataAPIDate]
Implementation of $DeserializeForTable for TableCodec
Parameters
- value: string
- ctx: TableDesCtx
Returns readonly [0, undefined | DataAPIDate]
- Defined in src/documents/datatypes/date.ts:124

`Static` now

now(this): DataAPIDate
Overview
Returns the current date in the local timezone.

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

`Static` ofEpochDay

ofEpochDay(this, epochDays): DataAPIDate
Overview
Creates a DataAPIDate from the number of days since the epoch.

The number may be negative, but must be an integer within the range [-100_000_000, 100_000_000].
Parameters
- this: void
- epochDays: number
  The number of days since the epoch (may be negative)
Returns DataAPIDate
The date representing the given number of days since the epoch
Example
```
DataAPIDate.ofEpochDay(0) // '1970-01-01'

date.ofEpochDay(12675) // '2004-09-14'

date.ofEpochDay(-1) // '1969-12-31'
```
- Defined in src/documents/datatypes/date.ts:188

`Static` ofYearDay

ofYearDay(this, year, dayOfYear): DataAPIDate
Overview
Creates a DataAPIDate from a year and a valid day of the year.

The year may be negative.

The day-of-year must be valid for the year, otherwise an exception will be thrown.
Parameters
- this: void
- year: number
  The year to use
- dayOfYear: number
  The day of the year to use (1-indexed)
Returns DataAPIDate
The date representing the given year and day of the year
Example
```
DataAPIDate.ofYearDay(2004, 258) // 2004-09-14

date.ofYearDay(2004, 1) // 2004-01-01

date.ofYearDay(2004, 366) // 2004-12-31 (ok b/c 2004 is a leap year)
```
- Defined in src/documents/datatypes/date.ts:215

`Static` utcnow

utcnow(this): DataAPIDate
Overview
Returns the current date in UTC.

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

Class DataAPIDate

Example

Example

See

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DataAPIDate

Example

Parameters

Returns DataAPIDate

Example

Parameters

Returns DataAPIDate

Parameters

Returns DataAPIDate

Example

Properties

Readonly date

Readonly month

Readonly year

Methods

[$SerializeForTable]

Parameters

Returns readonly [0, undefined | string]

compare

Parameters

Returns -1 | 0 | 1

Example

equals

Parameters

Returns boolean

Example

plus

Parameters

Returns DataAPIDate

Example

toDate

Parameters

Returns Date

Example

See

toDateUTC

Parameters

Returns Date

Example

See

toString

Returns string

Example

Static [$DeserializeForTable]

Parameters

Returns readonly [0, undefined | DataAPIDate]

Static now

Parameters

Returns DataAPIDate

Example

Static ofEpochDay

Parameters

Returns DataAPIDate

Example

Static ofYearDay

Parameters

Returns DataAPIDate

Example

Static utcnow

Parameters

Returns DataAPIDate

Example

Settings

Member Visibility

Theme

On This Page

`Readonly` date

`Readonly` month

`Readonly` year

`Static` [$DeserializeForTable]

`Static` now

`Static` ofEpochDay

`Static` ofYearDay

`Static` utcnow