DatetimeOperations

Namespace for operations on datetimes, dates, and times.

This class cannot be instantiated directly. It can only be accessed using the dt attribute of a cell.

Examples:

pipeline example {
    val column = Column("a", [Date(2022, 1, 9), Date(2024, 6, 12)]);
    out column.transform((cell) -> cell.dt.year());
}

Stub code in DatetimeOperations.sdsstub

class DatetimeOperations {
    /**
     * Extract the century from a datetime or date.
     *
     * Note that since our calendar begins with year 1 the first century lasts from year 1 to year 100. Subsequent
     * centuries begin with years ending in "01" and end with years ending in "00".
     *
     * @result cell The century.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(1999, 12, 31, 0, 0, 0),
     *         Datetime(2000,  1,  1, 0, 0, 0),
     *         Datetime(2001,  1,  1, 0, 0, 0),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.century());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2001, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.century());
     * }
     */
    @Pure
    fun century() -> cell: Cell<Int?>

    /**
     * Extract the date from a datetime.
     *
     * @result cell The date.
     *
     * @example
     * pipeline example {
     *     val column = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
     *     out column.transform((cell) -> cell.dt.date());
     * }
     */
    @Pure
    fun date() -> cell: Cell<Date?>

    /**
     * Extract the day from a datetime or date.
     *
     * @result cell The day.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.day());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.day());
     * }
     */
    @Pure
    fun day() -> cell: Cell<Int?>

    /**
     * Extract the day of the week from a datetime or date as defined by ISO 8601.
     *
     * The day of the week is a number between 1 (Monday) and 7 (Sunday).
     *
     * @result cell The day of the week.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 2, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.dayOfWeek());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(2000, 1, 1), Date(2000, 1, 2), null]);
     *     out column2.transform((cell) -> cell.dt.dayOfWeek());
     * }
     */
    @Pure
    @PythonName("day_of_week")
    fun dayOfWeek() -> cell: Cell<Int?>

    /**
     * Extract the day of the year from a datetime or date.
     *
     * The day of the year is a number between 1 and 366. A 366th day only occurs in leap years.
     *
     * @result cell The day of the year.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(1999, 12, 31, 0, 0, 0),
     *         Datetime(2000,  1,  1, 0, 0, 0),
     *         Datetime(2000, 12, 31, 0, 0, 0),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.dayOfYear());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2000, 12, 31), null]);
     *     out column2.transform((cell) -> cell.dt.dayOfYear());
     * }
     */
    @Pure
    @PythonName("day_of_year")
    fun dayOfYear() -> cell: Cell<Int?>

    /**
     * Extract the hour from a datetime or time.
     *
     * @result cell The hour.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 12, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.hour());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Time(0, 0, 0), Time(12, 0, 0), null]);
     *     out column2.transform((cell) -> cell.dt.hour());
     * }
     */
    @Pure
    fun hour() -> cell: Cell<Int?>

    /**
     * Extract the microsecond from a datetime or time.
     *
     * @result cell The microsecond.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(2000, 1, 1, 0, 0, 0, microsecond = 0),
     *         Datetime(2000, 1, 1, 0, 0, 0, microsecond = 500),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.microsecond());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Time(0, 0, 0, microsecond = 0), Time(0, 0, 0, microsecond = 500), null]);
     *     out column2.transform((cell) -> cell.dt.microsecond());
     * }
     */
    @Pure
    fun microsecond() -> cell: Cell<Int?>

    /**
     * Extract the millennium from a datetime or date.
     *
     * Note that since our calendar begins with year 1 the first millennium lasts from year 1 to year 1000. Subsequent
     * centuries begin with years ending in "001" and end with years ending in "000".
     *
     * @result cell The millennium.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(1999, 12, 31, 0, 0, 0),
     *         Datetime(2000,  1,  1, 0, 0, 0),
     *         Datetime(2001,  1,  1, 0, 0, 0),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.millennium());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2001, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.millennium());
     * }
     */
    @Pure
    fun millennium() -> cell: Cell<Int?>

    /**
     * Extract the millisecond from a datetime or time.
     *
     * @result cell The millisecond.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(2000, 1, 1, 0, 0, 0, microsecond = 0),
     *         Datetime(2000, 1, 1, 0, 0, 0, microsecond = 500000),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.millisecond());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Time(0, 0, 0, microsecond = 0), Time(0, 0, 0, microsecond = 500000), null]);
     *     out column2.transform((cell) -> cell.dt.millisecond());
     * }
     */
    @Pure
    fun millisecond() -> cell: Cell<Int?>

    /**
     * Extract the minute from a datetime or time.
     *
     * @result cell The minute.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 30, 0), null]);
     *     out column1.transform((cell) -> cell.dt.minute());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Time(0, 0, 0), Time(0, 30, 0), null]);
     *     out column2.transform((cell) -> cell.dt.minute());
     * }
     */
    @Pure
    fun minute() -> cell: Cell<Int?>

    /**
     * Extract the month from a datetime or date.
     *
     * @result cell The month.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.month());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.month());
     * }
     */
    @Pure
    fun month() -> cell: Cell<Int?>

    /**
     * Extract the quarter from a datetime or date.
     *
     * The quarter is a number between 1 and 4:
     *
     * - 1: January to March
     * - 2: April to June
     * - 3: July to September
     * - 4: October to December
     *
     * @result cell The quarter.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(1999, 12, 31, 0, 0, 0),
     *         Datetime(2000,  1,  1, 0, 0, 0),
     *         Datetime(2000,  4,  1, 0, 0, 0),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.quarter());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2000, 4, 1), null]);
     *     out column2.transform((cell) -> cell.dt.quarter());
     * }
     */
    @Pure
    fun quarter() -> cell: Cell<Int?>

    /**
     * Extract the second from a datetime or time.
     *
     * @result cell The second.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 30), null]);
     *     out column1.transform((cell) -> cell.dt.second());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Time(0, 0, 0), Time(0, 0, 30), null]);
     *     out column2.transform((cell) -> cell.dt.second());
     * }
     */
    @Pure
    fun second() -> cell: Cell<Int?>

    /**
     * Extract the time from a datetime.
     *
     * @result cell The time.
     *
     * @example
     * pipeline example {
     *     val column = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
     *     out column.transform((cell) -> cell.dt.time());
     * }
     */
    @Pure
    fun time() -> cell: Cell<Time?>

    /**
     * Extract the ISO 8601 week number from a datetime or date.
     *
     * The week is a number between 1 and 53. The first week of a year is the week that contains the first Thursday of
     * the year. The last week of a year is the week that contains the last Thursday of the year. In other words, a
     * week is associated with a year if it contains the majority of its days.
     *
     * @result cell The week.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [
     *         Datetime(1999, 12, 31, 0, 0, 0),
     *         Datetime(2000, 1, 2, 0, 0, 0),
     *         Datetime(2001, 12, 31, 0, 0, 0),
     *         null
     *     ]);
     *     out column1.transform((cell) -> cell.dt.week());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 2), Date(2001, 12, 31), null]);
     *     out column2.transform((cell) -> cell.dt.week());
     * }
     */
    @Pure
    fun week() -> cell: Cell<Int?>

    /**
     * Extract the year from a datetime or date.
     *
     * @result cell The year.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.year());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.year());
     * }
     */
    @Pure
    fun year() -> cell: Cell<Int?>

    /**
     * Check a datetime or date is in a leap year.
     *
     * @result cell Whether the year is a leap year.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(1900, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.isInLeapYear());
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1900, 1, 1), Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.isInLeapYear());
     * }
     */
    @Pure
    @PythonName("is_in_leap_year")
    fun isInLeapYear() -> cell: Cell<Boolean?>

    /**
     * Replace components of a datetime or date.
     *
     * If a component is not provided, it is not changed. Components that are not applicable to the object are ignored,
     * e.g. setting the hour of a date. Invalid results are converted to missing values (`None`).
     *
     * @param year The new year.
     * @param month The new month. Must be between 1 and 12.
     * @param day The new day. Must be between 1 and 31.
     * @param hour The new hour. Must be between 0 and 23.
     * @param minute The new minute. Must be between 0 and 59.
     * @param second The new second. Must be between 0 and 59.
     * @param microsecond The new microsecond. Must be between 0 and 999999.
     *
     * @result cell The new datetime or date.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), null]);
     *     out column1.transform((cell) -> cell.dt.replace(month = 2, day = 2, hour = 2));
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.replace(month = 2, day = 2, hour = 2));
     * }
     */
    @Pure
    fun replace(
        year: ConvertibleToIntCell = null,
        month: ConvertibleToIntCell = null,
        day: ConvertibleToIntCell = null,
        hour: ConvertibleToIntCell = null,
        minute: ConvertibleToIntCell = null,
        second: ConvertibleToIntCell = null,
        microsecond: ConvertibleToIntCell = null
    ) -> cell: Cell<Any>

    /**
     * Convert a datetime, date, or time to a string.
     *
     * The `format` parameter controls the presentation. It can be `"iso"` to target ISO 8601 or a custom string. The
     * custom string can contain fixed specifiers (see below), which are replaced with the corresponding values. The
     * specifiers are case-sensitive and always enclosed in curly braces. Other text is included in the output
     * verbatim. To include a literal opening curly brace, use `\{`, and to include a literal backslash, use `\\`.
     *
     * The following specifiers for _date components_ are available for **datetime** and **date**:
     *
     * - `{Y}`, `{_Y}`, `{^Y}`: Year (zero-padded to four digits, space-padded to four digits, no padding).
     * - `{Y99}`, `{_Y99}`, `{^Y99}`: Year modulo 100 (zero-padded to two digits, space-padded to two digits, no
     *   padding).
     * - `{M}`, `{_M}`, `{^M}`: Month (zero-padded to two digits, space-padded to two digits, no padding).
     * - `{M-full}`: Full name of the month (e.g. "January").
     * - `{M-short}`: Abbreviated name of the month with three letters (e.g. "Jan").
     * - `{W}`, `{_W}`, `{^W}`: Week number as defined by ISO 8601 (zero-padded to two digits, space-padded to two
     *   digits, no padding).
     * - `{D}`, `{_D}`, `{^D}`: Day of the month (zero-padded to two digits, space-padded to two digits, no padding).
     * - `{DOW}`: Day of the week as defined by ISO 8601 (1 = Monday, 7 = Sunday).
     * - `{DOW-full}`: Full name of the day of the week (e.g. "Monday").
     * - `{DOW-short}`: Abbreviated name of the day of the week with three letters (e.g. "Mon").
     * - `{DOY}`, `{_DOY}`, `{^DOY}`: Day of the year, ranging from 1 to 366 (zero-padded to three digits, space-padded
     *   to three digits, no padding).
     *
     * The following specifiers for _time components_ are available for **datetime** and **time**:
     *
     * - `{h}`, `{_h}`, `{^h}`: Hour (zero-padded to two digits, space-padded to two digits, no padding).
     * - `{h12}`, `{_h12}`, `{^h12}`: Hour in 12-hour format (zero-padded to two digits, space-padded to two digits, no
     *   padding).
     * - `{m}`, `{_m}`, `{^m}`: Minute (zero-padded to two digits, space-padded to two digits, no padding).
     * - `{s}`, `{_s}`, `{^s}`: Second (zero-padded to two digits, space-padded to two digits, no padding).
     * - `{.f}`: Fractional seconds with a leading decimal point.
     * - `{ms}`: Millisecond (zero-padded to three digits).
     * - `{us}`: Microsecond (zero-padded to six digits).
     * - `{ns}`: Nanosecond (zero-padded to nine digits).
     * - `{AM/PM}`: AM or PM (uppercase).
     * - `{am/pm}`: am or pm (lowercase).
     *
     * The following specifiers are available for **datetime** only:
     *
     * - `{z}`: Offset of the timezone from UTC without a colon (e.g. "+0000").
     * - `{:z}`: Offset of the timezone from UTC with a colon (e.g. "+00:00").
     * - `{u}`: The UNIX timestamp in seconds.
     *
     * The specifiers follow certain conventions:
     *
     * - Generally, date components use uppercase letters and time components use lowercase letters.
     * - If a component may be formatted in multiple ways, we use shorter specifiers for ISO 8601. Specifiers for
     *   other formats have a prefix (same value with different padding, see below) or suffix (other differences).
     * - By default, value are zero-padded, where applicable.
     * - A leading underscore (`_`) means the value is space-padded.
     * - A leading caret (`^`) means the value has no padding (think of the caret in regular expressions).
     *
     * @param format The format to use.
     *
     * @result cell The string representation.
     *
     * @example
     * pipeline example {
     *     val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
     *     out column1.transform((cell) -> cell.dt.toString());
     *     out column1.transform((cell) -> cell.dt.toString(
     *         format="{DOW-short} {D}-{M-short}-{Y} {h12}:{m}:{s} {AM/PM}"
     *     ));
     * }
     *
     * @example
     * pipeline example {
     *     val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
     *     out column2.transform((cell) -> cell.dt.toString());
     *     out column2.transform((cell) -> cell.dt.toString(
     *         format="{M}/{D}/{Y}"
     *     ));
     * }
     */
    @Pure
    @PythonName("to_string")
    fun toString(
        format: String = "iso"
    ) -> cell: Cell<String?>

    /**
     * Get the Unix timestamp from a datetime.
     *
     * A Unix timestamp is the elapsed time since 00:00:00 UTC on 1 January 1970. By default, this method returns the
     * value in seconds, but that can be changed with the `unit` parameter.
     *
     * @param unit The unit of the timestamp. Can be "s" (seconds), "ms" (milliseconds), or "us" (microseconds).
     *
     * @result cell The Unix timestamp.
     *
     * @example
     * pipeline example {
     *     val column = Column("a", [Datetime(1970, 1, 1, 0, 0, 0), Datetime(1970, 1, 2, 0, 0, 0), null]);
     *     out column.transform((cell) -> cell.dt.unixTimestamp());
     *     out column.transform((cell) -> cell.dt.unixTimestamp(unit="ms"));
     * }
     */
    @Pure
    @PythonName("unix_timestamp")
    fun unixTimestamp(
        unit: literal<"s", "ms", "us"> = "s"
    ) -> cell: Cell<Int?>
}

century

Extract the century from a datetime or date.

Note that since our calendar begins with year 1 the first century lasts from year 1 to year 100. Subsequent centuries begin with years ending in "01" and end with years ending in "00".

Results:

Name	Type	Description
cell	Cell<Int?>	The century.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(1999, 12, 31, 0, 0, 0),
        Datetime(2000,  1,  1, 0, 0, 0),
        Datetime(2001,  1,  1, 0, 0, 0),
        null
    ]);
    out column1.transform((cell) -> cell.dt.century());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2001, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.century());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun century() -> cell: Cell<Int?>

date

Extract the date from a datetime.

Results:

Name	Type	Description
cell	Cell<Date?>	The date.

Examples:

pipeline example {
    val column = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
    out column.transform((cell) -> cell.dt.date());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun date() -> cell: Cell<Date?>

day

Extract the day from a datetime or date.

Results:

Name	Type	Description
cell	Cell<Int?>	The day.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.day());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.day());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun day() -> cell: Cell<Int?>

dayOfWeek

Extract the day of the week from a datetime or date as defined by ISO 8601.

The day of the week is a number between 1 (Monday) and 7 (Sunday).

Results:

Name	Type	Description
cell	Cell<Int?>	The day of the week.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 2, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.dayOfWeek());
}

pipeline example {
    val column2 = Column("a", [Date(2000, 1, 1), Date(2000, 1, 2), null]);
    out column2.transform((cell) -> cell.dt.dayOfWeek());
}

Stub code in DatetimeOperations.sdsstub

@Pure
@PythonName("day_of_week")
fun dayOfWeek() -> cell: Cell<Int?>

dayOfYear

Extract the day of the year from a datetime or date.

The day of the year is a number between 1 and 366. A 366th day only occurs in leap years.

Results:

Name	Type	Description
cell	Cell<Int?>	The day of the year.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(1999, 12, 31, 0, 0, 0),
        Datetime(2000,  1,  1, 0, 0, 0),
        Datetime(2000, 12, 31, 0, 0, 0),
        null
    ]);
    out column1.transform((cell) -> cell.dt.dayOfYear());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2000, 12, 31), null]);
    out column2.transform((cell) -> cell.dt.dayOfYear());
}

Stub code in DatetimeOperations.sdsstub

@Pure
@PythonName("day_of_year")
fun dayOfYear() -> cell: Cell<Int?>

hour

Extract the hour from a datetime or time.

Results:

Name	Type	Description
cell	Cell<Int?>	The hour.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 12, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.hour());
}

pipeline example {
    val column2 = Column("a", [Time(0, 0, 0), Time(12, 0, 0), null]);
    out column2.transform((cell) -> cell.dt.hour());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun hour() -> cell: Cell<Int?>

isInLeapYear

Check a datetime or date is in a leap year.

Results:

Name	Type	Description
cell	Cell<Boolean?>	Whether the year is a leap year.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(1900, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.isInLeapYear());
}

pipeline example {
    val column2 = Column("a", [Date(1900, 1, 1), Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.isInLeapYear());
}

Stub code in DatetimeOperations.sdsstub

@Pure
@PythonName("is_in_leap_year")
fun isInLeapYear() -> cell: Cell<Boolean?>

microsecond

Extract the microsecond from a datetime or time.

Results:

Name	Type	Description
cell	Cell<Int?>	The microsecond.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(2000, 1, 1, 0, 0, 0, microsecond = 0),
        Datetime(2000, 1, 1, 0, 0, 0, microsecond = 500),
        null
    ]);
    out column1.transform((cell) -> cell.dt.microsecond());
}

pipeline example {
    val column2 = Column("a", [Time(0, 0, 0, microsecond = 0), Time(0, 0, 0, microsecond = 500), null]);
    out column2.transform((cell) -> cell.dt.microsecond());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun microsecond() -> cell: Cell<Int?>

millennium

Extract the millennium from a datetime or date.

Note that since our calendar begins with year 1 the first millennium lasts from year 1 to year 1000. Subsequent centuries begin with years ending in "001" and end with years ending in "000".

Results:

Name	Type	Description
cell	Cell<Int?>	The millennium.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(1999, 12, 31, 0, 0, 0),
        Datetime(2000,  1,  1, 0, 0, 0),
        Datetime(2001,  1,  1, 0, 0, 0),
        null
    ]);
    out column1.transform((cell) -> cell.dt.millennium());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2001, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.millennium());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun millennium() -> cell: Cell<Int?>

millisecond

Extract the millisecond from a datetime or time.

Results:

Name	Type	Description
cell	Cell<Int?>	The millisecond.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(2000, 1, 1, 0, 0, 0, microsecond = 0),
        Datetime(2000, 1, 1, 0, 0, 0, microsecond = 500000),
        null
    ]);
    out column1.transform((cell) -> cell.dt.millisecond());
}

pipeline example {
    val column2 = Column("a", [Time(0, 0, 0, microsecond = 0), Time(0, 0, 0, microsecond = 500000), null]);
    out column2.transform((cell) -> cell.dt.millisecond());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun millisecond() -> cell: Cell<Int?>

minute

Extract the minute from a datetime or time.

Results:

Name	Type	Description
cell	Cell<Int?>	The minute.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 30, 0), null]);
    out column1.transform((cell) -> cell.dt.minute());
}

pipeline example {
    val column2 = Column("a", [Time(0, 0, 0), Time(0, 30, 0), null]);
    out column2.transform((cell) -> cell.dt.minute());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun minute() -> cell: Cell<Int?>

month

Extract the month from a datetime or date.

Results:

Name	Type	Description
cell	Cell<Int?>	The month.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.month());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.month());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun month() -> cell: Cell<Int?>

quarter

Extract the quarter from a datetime or date.

The quarter is a number between 1 and 4:

• 1: January to March
• 2: April to June
• 3: July to September
• 4: October to December

Results:

Name	Type	Description
cell	Cell<Int?>	The quarter.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(1999, 12, 31, 0, 0, 0),
        Datetime(2000,  1,  1, 0, 0, 0),
        Datetime(2000,  4,  1, 0, 0, 0),
        null
    ]);
    out column1.transform((cell) -> cell.dt.quarter());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), Date(2000, 4, 1), null]);
    out column2.transform((cell) -> cell.dt.quarter());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun quarter() -> cell: Cell<Int?>

replace

Replace components of a datetime or date.

If a component is not provided, it is not changed. Components that are not applicable to the object are ignored, e.g. setting the hour of a date. Invalid results are converted to missing values (None).

Parameters:

Name	Type	Description	Default
year	union<Int, Cell<Any?>?>	The new year.	null
month	union<Int, Cell<Any?>?>	The new month. Must be between 1 and 12.	null
day	union<Int, Cell<Any?>?>	The new day. Must be between 1 and 31.	null
hour	union<Int, Cell<Any?>?>	The new hour. Must be between 0 and 23.	null
minute	union<Int, Cell<Any?>?>	The new minute. Must be between 0 and 59.	null
second	union<Int, Cell<Any?>?>	The new second. Must be between 0 and 59.	null
microsecond	union<Int, Cell<Any?>?>	The new microsecond. Must be between 0 and 999999.	null

Results:

Name	Type	Description
cell	Cell<Any>	The new datetime or date.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.replace(month = 2, day = 2, hour = 2));
}

pipeline example {
    val column2 = Column("a", [Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.replace(month = 2, day = 2, hour = 2));
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun replace(
    year: ConvertibleToIntCell = null,
    month: ConvertibleToIntCell = null,
    day: ConvertibleToIntCell = null,
    hour: ConvertibleToIntCell = null,
    minute: ConvertibleToIntCell = null,
    second: ConvertibleToIntCell = null,
    microsecond: ConvertibleToIntCell = null
) -> cell: Cell<Any>

second

Extract the second from a datetime or time.

Results:

Name	Type	Description
cell	Cell<Int?>	The second.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(2000, 1, 1, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 30), null]);
    out column1.transform((cell) -> cell.dt.second());
}

pipeline example {
    val column2 = Column("a", [Time(0, 0, 0), Time(0, 0, 30), null]);
    out column2.transform((cell) -> cell.dt.second());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun second() -> cell: Cell<Int?>

time

Extract the time from a datetime.

Results:

Name	Type	Description
cell	Cell<Time?>	The time.

Examples:

pipeline example {
    val column = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
    out column.transform((cell) -> cell.dt.time());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun time() -> cell: Cell<Time?>

toString

Convert a datetime, date, or time to a string.

The format parameter controls the presentation. It can be "iso" to target ISO 8601 or a custom string. The custom string can contain fixed specifiers (see below), which are replaced with the corresponding values. The specifiers are case-sensitive and always enclosed in curly braces. Other text is included in the output verbatim. To include a literal opening curly brace, use \{, and to include a literal backslash, use \\.

The following specifiers for date components are available for datetime and date:

• {Y}, {_Y}, {^Y}: Year (zero-padded to four digits, space-padded to four digits, no padding).
• {Y99}, {_Y99}, {^Y99}: Year modulo 100 (zero-padded to two digits, space-padded to two digits, no padding).
• {M}, {_M}, {^M}: Month (zero-padded to two digits, space-padded to two digits, no padding).
• {M-full}: Full name of the month (e.g. "January").
• {M-short}: Abbreviated name of the month with three letters (e.g. "Jan").
• {W}, {_W}, {^W}: Week number as defined by ISO 8601 (zero-padded to two digits, space-padded to two digits, no padding).
• {D}, {_D}, {^D}: Day of the month (zero-padded to two digits, space-padded to two digits, no padding).
• {DOW}: Day of the week as defined by ISO 8601 (1 = Monday, 7 = Sunday).
• {DOW-full}: Full name of the day of the week (e.g. "Monday").
• {DOW-short}: Abbreviated name of the day of the week with three letters (e.g. "Mon").
• {DOY}, {_DOY}, {^DOY}: Day of the year, ranging from 1 to 366 (zero-padded to three digits, space-padded to three digits, no padding).

The following specifiers for time components are available for datetime and time:

• {h}, {_h}, {^h}: Hour (zero-padded to two digits, space-padded to two digits, no padding).
• {h12}, {_h12}, {^h12}: Hour in 12-hour format (zero-padded to two digits, space-padded to two digits, no padding).
• {m}, {_m}, {^m}: Minute (zero-padded to two digits, space-padded to two digits, no padding).
• {s}, {_s}, {^s}: Second (zero-padded to two digits, space-padded to two digits, no padding).
• {.f}: Fractional seconds with a leading decimal point.
• {ms}: Millisecond (zero-padded to three digits).
• {us}: Microsecond (zero-padded to six digits).
• {ns}: Nanosecond (zero-padded to nine digits).
• {AM/PM}: AM or PM (uppercase).
• {am/pm}: am or pm (lowercase).

The following specifiers are available for datetime only:

• {z}: Offset of the timezone from UTC without a colon (e.g. "+0000").
• {:z}: Offset of the timezone from UTC with a colon (e.g. "+00:00").
• {u}: The UNIX timestamp in seconds.

The specifiers follow certain conventions:

• Generally, date components use uppercase letters and time components use lowercase letters.
• If a component may be formatted in multiple ways, we use shorter specifiers for ISO 8601. Specifiers for other formats have a prefix (same value with different padding, see below) or suffix (other differences).
• By default, value are zero-padded, where applicable.
• A leading underscore (_) means the value is space-padded.
• A leading caret (^) means the value has no padding (think of the caret in regular expressions).

Parameters:

Name	Type	Description	Default
format	String	The format to use.	"iso"

Results:

Name	Type	Description
cell	Cell<String?>	The string representation.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 12, 30, 0), null]);
    out column1.transform((cell) -> cell.dt.toString());
    out column1.transform((cell) -> cell.dt.toString(
        format="{DOW-short} {D}-{M-short}-{Y} {h12}:{m}:{s} {AM/PM}"
    ));
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.toString());
    out column2.transform((cell) -> cell.dt.toString(
        format="{M}/{D}/{Y}"
    ));
}

Stub code in DatetimeOperations.sdsstub

@Pure
@PythonName("to_string")
fun toString(
    format: String = "iso"
) -> cell: Cell<String?>

unixTimestamp

Get the Unix timestamp from a datetime.

A Unix timestamp is the elapsed time since 00:00:00 UTC on 1 January 1970. By default, this method returns the value in seconds, but that can be changed with the unit parameter.

Parameters:

Name	Type	Description	Default
unit	literal<"s", "ms", "us">	The unit of the timestamp. Can be "s" (seconds), "ms" (milliseconds), or "us" (microseconds).	"s"

Results:

Name	Type	Description
cell	Cell<Int?>	The Unix timestamp.

Examples:

pipeline example {
    val column = Column("a", [Datetime(1970, 1, 1, 0, 0, 0), Datetime(1970, 1, 2, 0, 0, 0), null]);
    out column.transform((cell) -> cell.dt.unixTimestamp());
    out column.transform((cell) -> cell.dt.unixTimestamp(unit="ms"));
}

Stub code in DatetimeOperations.sdsstub

@Pure
@PythonName("unix_timestamp")
fun unixTimestamp(
    unit: literal<"s", "ms", "us"> = "s"
) -> cell: Cell<Int?>

week

Extract the ISO 8601 week number from a datetime or date.

The week is a number between 1 and 53. The first week of a year is the week that contains the first Thursday of the year. The last week of a year is the week that contains the last Thursday of the year. In other words, a week is associated with a year if it contains the majority of its days.

Results:

Name	Type	Description
cell	Cell<Int?>	The week.

Examples:

pipeline example {
    val column1 = Column("a", [
        Datetime(1999, 12, 31, 0, 0, 0),
        Datetime(2000, 1, 2, 0, 0, 0),
        Datetime(2001, 12, 31, 0, 0, 0),
        null
    ]);
    out column1.transform((cell) -> cell.dt.week());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 2), Date(2001, 12, 31), null]);
    out column2.transform((cell) -> cell.dt.week());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun week() -> cell: Cell<Int?>

year

Extract the year from a datetime or date.

Results:

Name	Type	Description
cell	Cell<Int?>	The year.

Examples:

pipeline example {
    val column1 = Column("a", [Datetime(1999, 12, 31, 0, 0, 0), Datetime(2000, 1, 1, 0, 0, 0), null]);
    out column1.transform((cell) -> cell.dt.year());
}

pipeline example {
    val column2 = Column("a", [Date(1999, 12, 31), Date(2000, 1, 1), null]);
    out column2.transform((cell) -> cell.dt.year());
}

Stub code in DatetimeOperations.sdsstub

@Pure
fun year() -> cell: Cell<Int?>