Compute Day

Files
file	datetime.hpp
	DateTime column APIs.

Enumerations
enum class	cudf::datetime::rounding_frequency : int32_t {   DAY , HOUR , MINUTE , SECOND ,   MILLISECOND , MICROSECOND , NANOSECOND }
	Fixed frequencies supported by datetime rounding functions ceil, floor, round.

Functions
std::unique_ptr< cudf::column >	cudf::datetime::last_day_of_month (cudf::column_view const &column, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Computes the last day of the month in datetime type and returns a TIMESTAMP_DAYS cudf::column. More...
std::unique_ptr< cudf::column >	cudf::datetime::day_of_year (cudf::column_view const &column, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Computes the day number since the start of the year from the datetime and returns an int16_t cudf::column. The value is between [1, {365-366}]. More...
std::unique_ptr< cudf::column >	cudf::datetime::add_calendrical_months (cudf::column_view const &timestamps, cudf::column_view const &months, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Adds or subtracts a number of months from the datetime type and returns a timestamp column that is of the same type as the input timestamps column. More...
std::unique_ptr< cudf::column >	cudf::datetime::add_calendrical_months (cudf::column_view const &timestamps, cudf::scalar const &months, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Adds or subtracts a number of months from the datetime type and returns a timestamp column that is of the same type as the input timestamps column. More...
std::unique_ptr< cudf::column >	cudf::datetime::is_leap_year (cudf::column_view const &column, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Check if the year of the given date is a leap year. More...
std::unique_ptr< cudf::column >	cudf::datetime::days_in_month (cudf::column_view const &column, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Extract the number of days in the month. More...
std::unique_ptr< cudf::column >	cudf::datetime::extract_quarter (cudf::column_view const &column, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Returns the quarter of the date. More...
std::unique_ptr< cudf::column >	cudf::datetime::ceil_datetimes (cudf::column_view const &column, rounding_frequency freq, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Round datetimes up to the nearest multiple of the given frequency. More...
std::unique_ptr< cudf::column >	cudf::datetime::floor_datetimes (cudf::column_view const &column, rounding_frequency freq, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Round datetimes down to the nearest multiple of the given frequency. More...
std::unique_ptr< cudf::column >	cudf::datetime::round_datetimes (cudf::column_view const &column, rounding_frequency freq, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Round datetimes to the nearest multiple of the given frequency. More...

Detailed Description

Function Documentation

add_calendrical_months() [1/2]

std::unique_ptr<cudf::column> cudf::datetime::add_calendrical_months	(	cudf::column_view const &	timestamps,
		cudf::column_view const &	months,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Adds or subtracts a number of months from the datetime type and returns a timestamp column that is of the same type as the input timestamps column.

For a given row, if the timestamps or the months column value is null, the output for that row is null. This method preserves the input time and the day where applicable. The date is rounded down to the last day of the month for that year, if the new day is invalid for that month.

Example:
timestamps = [5/31/20 08:00:00, 5/31/20 00:00:00, 5/31/20 13:00:00, 5/31/20 23:00:00,
              6/30/20 00:00:01, 6/30/20 14:12:13]
months     = [1               , -1              , -3              , -15             ,
              -1              , 1]
r = add_calendrical_months(timestamp_column, months_column)
r is [6/30/20 08:00:00, 4/30/20 00:00:00, 2/29/20 13:00:00, 2/28/19 23:00:00,
      5/30/20 00:00:01, 7/30/20 14:12:13]

Exceptions

cudf::logic_error	if timestamps datatype is not a TIMESTAMP or if months datatype is not INT16 or INT32.
cudf::logic_error	if timestamps column size is not equal to months column size.

Parameters

timestamps	cudf::column_view of timestamp type
months	cudf::column_view of integer type containing the number of months to add
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column of timestamp type containing the computed timestamps

add_calendrical_months() [2/2]

std::unique_ptr<cudf::column> cudf::datetime::add_calendrical_months	(	cudf::column_view const &	timestamps,
		cudf::scalar const &	months,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Adds or subtracts a number of months from the datetime type and returns a timestamp column that is of the same type as the input timestamps column.

For a given row, if the timestamps value is null, the output for that row is null. A null months scalar would result in an all null column. This method preserves the input time and the day where applicable. The date is rounded down to the last day of the month for that year, if the new day is invalid for that month.

Example:
timestamps = [5/31/20 08:00:00, 6/30/20 00:00:00, 7/31/20 13:00:00]
months     = -3
output is [2/29/20 08:00:00, 3/30/20 00:00:00, 4/30/20 13:00:00]
 
timestamps = [4/28/20 04:00:00, 5/30/20 01:00:00, 6/30/20 21:00:00]
months     = 1
output is [5/28/20 04:00:00, 6/30/20 01:00:00, 7/30/20 21:00:00]

Exceptions

cudf::logic_error	if timestamps datatype is not a TIMESTAMP or if months datatype is not INT16 or INT32.
cudf::logic_error	if timestamps column size is not equal to months column size.

Parameters

timestamps	cudf::column_view of timestamp type
months	cudf::scalar of integer type containing the number of months to add
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column of timestamp type containing the computed timestamps

ceil_datetimes()

std::unique_ptr<cudf::column> cudf::datetime::ceil_datetimes	(	cudf::column_view const &	column,
		rounding_frequency	freq,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Round datetimes up to the nearest multiple of the given frequency.

Parameters

column	cudf::column_view of the input datetime values
freq	rounding_frequency indicating the frequency to round up to
mr	Device memory resource used to allocate device memory of the returned column

Exceptions

cudf::logic_error

if input column datatype is not TIMESTAMP.

Returns

cudf::column of the same datetime resolution as the input column

day_of_year()

std::unique_ptr<cudf::column> cudf::datetime::day_of_year	(	cudf::column_view const &	column,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Computes the day number since the start of the year from the datetime and returns an int16_t cudf::column. The value is between [1, {365-366}].

Parameters

column	cudf::column_view of the input datetime values
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column of datatype INT16 containing the day number since the start of the year

Exceptions

cudf::logic_error

if input column datatype is not a TIMESTAMP

days_in_month()

std::unique_ptr<cudf::column> cudf::datetime::days_in_month	(	cudf::column_view const &	column,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Extract the number of days in the month.

output[i] contains the number of days in the month of date column[i] output[i] is null if column[i] is null

Exceptions

cudf::logic_error

if input column datatype is not a TIMESTAMP

Parameters

column	cudf::column_view of the input datetime values
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column of datatype INT16 of days in month of the corresponding date

extract_quarter()

std::unique_ptr<cudf::column> cudf::datetime::extract_quarter	(	cudf::column_view const &	column,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Returns the quarter of the date.

output[i] will be a value from {1, 2, 3, 4} corresponding to the quarter of month given by column[i]. It will be null if the input row at column[i] is null.

Exceptions

cudf::logic_error

if input column datatype is not a TIMESTAMP

Parameters

column	The input column containing datetime values
mr	Device memory resource used to allocate device memory of the returned column

Returns

A column of INT16 type indicating which quarter the date is in

floor_datetimes()

std::unique_ptr<cudf::column> cudf::datetime::floor_datetimes	(	cudf::column_view const &	column,
		rounding_frequency	freq,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Round datetimes down to the nearest multiple of the given frequency.

Parameters

column	cudf::column_view of the input datetime values
freq	rounding_frequency indicating the frequency to round down to
mr	Device memory resource used to allocate device memory of the returned column

Exceptions

cudf::logic_error

if input column datatype is not TIMESTAMP.

Returns

cudf::column of the same datetime resolution as the input column

is_leap_year()

std::unique_ptr<cudf::column> cudf::datetime::is_leap_year	(	cudf::column_view const &	column,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Check if the year of the given date is a leap year.

output[i] == true if year of column[i] is a leap year output[i] == false if year of column[i] is not a leap year output[i] is null if column[i] is null

Parameters

column	cudf::column_view of the input datetime values
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column of datatype BOOL8 truth value of the corresponding date

Exceptions

cudf::logic_error

if input column datatype is not a TIMESTAMP

last_day_of_month()

std::unique_ptr<cudf::column> cudf::datetime::last_day_of_month	(	cudf::column_view const &	column,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Computes the last day of the month in datetime type and returns a TIMESTAMP_DAYS cudf::column.

Parameters

column	cudf::column_view of the input datetime values
mr	Device memory resource used to allocate device memory of the returned column

Returns

cudf::column containing last day of the month as TIMESTAMP_DAYS

Exceptions

cudf::logic_error

if input column datatype is not TIMESTAMP

round_datetimes()

std::unique_ptr<cudf::column> cudf::datetime::round_datetimes	(	cudf::column_view const &	column,
		rounding_frequency	freq,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource()
	)

Round datetimes to the nearest multiple of the given frequency.

Parameters

column	cudf::column_view of the input datetime values
freq	rounding_frequency indicating the frequency to round to
mr	Device memory resource used to allocate device memory of the returned column

Exceptions

cudf::logic_error

if input column datatype is not TIMESTAMP.

Returns

cudf::column of the same datetime resolution as the input column