Date Functions¶

Functions for parsing dates, retrieving the current date/time, extracting date components, detecting period boundaries, converting between formats, and performing date arithmetic.

from everysk.sdk.engines import Expression
expression_engine = Expression()

Date strings use the YYYYMMDD format (e.g. '20230731'). DateTime strings include time as 'YYYYMMDD HH:MM:SS'. Functions return dates in YYYYMMDD string format unless noted otherwise.

Shared Parameters¶

Many boundary and period functions accept two optional parameters:

Parameter	Type	Default	Description
`bdays`	`bool`	`False`	When `True`, only business days are considered.
`calendar`	`str \\| None`	`None`	Named holiday calendar (e.g. `'ANBIMA'`, `'BR'`). `None` means no holidays are excluded.

Casting¶

cast_date¶

cast_date(value, default=None, only_date=False)

Vectorized. Parses value into a date string. Returns default if parsing fails. When only_date=True, strips any time component from the result.

expression_engine.solve('cast_date("20230101")', {})
# '20230101'

expression_engine.solve('cast_date("20230731 14:30:00")', {})
# '20230731 14:30:00'

expression_engine.solve('cast_date("invalid")', {})
# None

import numpy as np
expression_engine.solve('cast_date(dates)', {
    'dates': np.array(['20230101', '20231231', None])
})
# ['20230101', '20231231', None]

Current Date & Time¶

now¶

now(tzinfo=None)

Returns the current date and time as a DateTime. Pass a timezone string (e.g. 'America/New_York') to get local time.

expression_engine.solve('now()', {})
# '20260519 12:00:00'  (example — output varies)

today¶

today()

Returns the current local date.

expression_engine.solve('today()', {})
# '20260519'  (example — output varies)

time¶

time(tzinfo=None)

Returns the current time without the date component.

expression_engine.solve('time()', {})
# datetime.time(12, 0, 0)  (example — output varies)

Component Extraction¶

get_year¶

get_year(string_date)

Vectorized. Returns the year as an integer. Returns None for invalid dates.

expression_engine.solve('get_year("20240204")', {})
# 2024

get_quarter¶

get_quarter(string_date)

Vectorized. Returns the quarter of the year (1–4). Returns None for invalid dates.

expression_engine.solve('get_quarter("20230731")', {})
# 3

get_month¶

get_month(string_date)

Vectorized. Returns the month number (1–12). Returns None for invalid dates.

expression_engine.solve('get_month("20230101")', {})
# 1

get_month_name¶

get_month_name(string_date)

Vectorized. Returns the full English month name. Returns None for invalid dates.

expression_engine.solve('get_month_name("20230731")', {})
# 'July'

get_week_of_year¶

get_week_of_year(string_date)

Vectorized. Returns the week number within the year (1–53). Returns None for invalid dates.

expression_engine.solve('get_week_of_year("20230731")', {})
# 31

get_week_of_month¶

get_week_of_month(string_date)

Vectorized. Returns the week number within the month (1–5). Returns None for invalid dates.

expression_engine.solve('get_week_of_month("20230731")', {})
# 5

get_day¶

get_day(string_date)

Vectorized. Returns the day of the month (1–31). Returns None for invalid dates.

expression_engine.solve('get_day("20230731")', {})
# 31

get_day_name¶

get_day_name(string_date)

Vectorized. Returns the full English day name. Returns None for invalid dates.

expression_engine.solve('get_day_name("20230731")', {})
# 'Monday'

get_day_of_week¶

get_day_of_week(string_date)

Vectorized. Returns the day-of-week index: 0 = Monday, 6 = Sunday. Returns None for invalid dates.

expression_engine.solve('get_day_of_week("20240521")', {})
# 1  (Tuesday)

get_day_of_year¶

get_day_of_year(string_date)

Vectorized. Returns the day number within the year (1–365/366). Returns None for invalid dates.

expression_engine.solve('get_day_of_year("20240521")', {})
# 142

get_hour¶

get_hour(string_date)

Vectorized. Returns the hour (0–23) from a DateTime string. Returns None for date-only values.

expression_engine.solve('get_hour("20240521 14:54:23")', {})
# 14

get_minute¶

get_minute(string_date)

Vectorized. Returns the minute (0–59) from a DateTime string. Returns None for date-only values.

expression_engine.solve('get_minute("20240521 14:54:23")', {})
# 54

get_second¶

get_second(string_date)

Vectorized. Returns the second (0–59) from a DateTime string. Returns None for date-only values.

expression_engine.solve('get_second("20240521 14:54:23")', {})
# 23

Period Boundaries — Last Day¶

get_last_day_of_week¶

get_last_day_of_week(string_date, bdays=False, calendar=None)

Vectorized. Returns the last day of the week containing string_date.

expression_engine.solve('get_last_day_of_week("20230702")', {})
# '20230708'

get_last_day_of_month¶

get_last_day_of_month(string_date, bdays=False, calendar=None)

Vectorized. Returns the last day of the month.

expression_engine.solve('get_last_day_of_month("20230614")', {})
# '20230630'

expression_engine.solve('get_last_day_of_month("20230614", True, "ANBIMA")', {})
# last business day of June 2023 per ANBIMA calendar

get_last_day_of_quarter¶

get_last_day_of_quarter(string_date, bdays=False, calendar=None)

Vectorized. Returns the last day of the quarter.

expression_engine.solve('get_last_day_of_quarter("20230202")', {})
# '20230331'

get_last_day_of_year¶

get_last_day_of_year(string_date, bdays=False, calendar=None)

Vectorized. Returns the last day of the year.

expression_engine.solve('get_last_day_of_year("20230202")', {})
# '20231231'

is_last_day_of_week¶

is_last_day_of_week(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the last day of its week.

expression_engine.solve('is_last_day_of_week("20230610")', {})
# True

expression_engine.solve('is_last_day_of_week("20230609")', {})
# False

is_last_day_of_month¶

is_last_day_of_month(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the last day of its month.

expression_engine.solve('is_last_day_of_month("20230930")', {})
# True

expression_engine.solve('is_last_day_of_month("20230929")', {})
# False

is_last_day_of_quarter¶

is_last_day_of_quarter(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the last day of its quarter.

expression_engine.solve('is_last_day_of_quarter("20210331")', {})
# True

is_last_day_of_year¶

is_last_day_of_year(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the last day of its year.

expression_engine.solve('is_last_day_of_year("20211231")', {})
# True

Period Boundaries — First Day¶

get_first_day_of_week¶

get_first_day_of_week(string_date, bdays=False, calendar=None)

Vectorized. Returns the first day of the week containing string_date.

expression_engine.solve('get_first_day_of_week("20230614")', {})
# '20230611'

get_first_day_of_month¶

get_first_day_of_month(string_date, bdays=False, calendar=None)

Vectorized. Returns the first day of the month.

expression_engine.solve('get_first_day_of_month("20230114")', {})
# '20230101'

get_first_day_of_quarter¶

get_first_day_of_quarter(string_date, bdays=False, calendar=None)

Vectorized. Returns the first day of the quarter.

expression_engine.solve('get_first_day_of_quarter("20230214")', {})
# '20230101'

get_first_day_of_year¶

get_first_day_of_year(string_date, bdays=False, calendar=None)

Vectorized. Returns the first day of the year.

expression_engine.solve('get_first_day_of_year("20230214")', {})
# '20230101'

is_first_day_of_week¶

is_first_day_of_week(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the first day of its week.

expression_engine.solve('is_first_day_of_week("20230611")', {})
# True

is_first_day_of_month¶

is_first_day_of_month(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the first day of its month.

expression_engine.solve('is_first_day_of_month("20230601")', {})
# True

is_first_day_of_quarter¶

is_first_day_of_quarter(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the first day of its quarter. With bdays=True, checks for the first business day of the quarter.

expression_engine.solve('is_first_day_of_quarter("20230101")', {})
# True

expression_engine.solve('is_first_day_of_quarter("20230403", True)', {})
# True  (first business day of Q2 2023; April 1 and 2 were weekend)

is_first_day_of_year¶

is_first_day_of_year(string_date, bdays=False, calendar=None)

Vectorized. Returns True if string_date is the first day of its year.

expression_engine.solve('is_first_day_of_year("20230101")', {})
# True

expression_engine.solve('is_first_day_of_year("20230102")', {})
# False

Format Conversion¶

from_iso_format¶

from_iso_format(input_date, with_time=False)

Vectorized. Parses an ISO 8601 string ('YYYY-MM-DDTHH:MM:SS') into a date string. Returns None on failure.

expression_engine.solve('from_iso_format("2023-06-30T00:00:00")', {})
# '20230630'

expression_engine.solve('from_iso_format("2023-06-30T12:30:45", True)', {})
# '20230630 12:30:45'

to_iso_format¶

to_iso_format(input_date)

Vectorized. Converts a YYYYMMDD date string to ISO format 'YYYY-MM-DD'. Returns None on failure.

expression_engine.solve('to_iso_format("20230630")', {})
# '2023-06-30'

from_timestamp¶

from_timestamp(input_date, with_time=False)

Vectorized. Converts a Unix timestamp (seconds since epoch) to a date string.

expression_engine.solve('from_timestamp(1677776000)', {})
# '20230302'

expression_engine.solve('from_timestamp(1677776015, True)', {})
# '20230302 16:53:35'

to_timestamp¶

to_timestamp(input_date)

Vectorized. Converts a YYYYMMDD date string to a Unix timestamp.

expression_engine.solve('to_timestamp("20230630")', {})
# 1688083200

from_ordinal_days¶

from_ordinal_days(input_date)

Vectorized. Converts an ordinal day number (days since 0001-01-01) to a YYYYMMDD string.

expression_engine.solve('from_ordinal_days(738701)', {})
# '20230630'

to_ordinal_days¶

to_ordinal_days(input_date)

Vectorized. Converts a YYYYMMDD date string to an ordinal day number.

expression_engine.solve('to_ordinal_days("00010101")', {})
# 1

from_date_format¶

from_date_format(input_date, input_format, with_time=False)

Vectorized. Parses a date string using a custom strptime-style format.

expression_engine.solve('from_date_format("2023-06-30", "%Y-%m-%d")', {})
# '20230630'

expression_engine.solve('from_date_format("2023/06/30 12:30:45", "%Y/%m/%d %H:%M:%S", True)', {})
# '20230630 12:30:45'

to_date_format¶

to_date_format(input_date, output_format='%Y%m%d')

Vectorized. Formats a date using a custom strftime-style format. Returns None on failure.

expression_engine.solve('to_date_format("20230630", "%Y/%m/%d")', {})
# '2023/06/30'

expression_engine.solve('to_date_format("20230630", "%B %d, %Y")', {})
# 'June 30, 2023'

Date Arithmetic¶

date_delta¶

date_delta(string_date, period, periodicity='D', calendar=None)

Shifts string_date by period units of periodicity. Supports scalar and array inputs for both arguments.

`periodicity`	Unit
`'D'`	Calendar days
`'B'`	Business days
`'M'`	Months
`'Y'`	Years

expression_engine.solve('date_delta("20230630", 5)', {})
# '20230705'

expression_engine.solve('date_delta("20230630", -1, "M")', {})
# '20230530'

import numpy as np
expression_engine.solve('date_delta("20230101", periods, "M")', {
    'periods': np.array([1, 2, 3])
})
# ['20230201', '20230301', '20230401']

dates_diff¶

dates_diff(start_date, end_date, periodicity='D', calendar=None)

Returns the difference between start_date and end_date measured in periodicity units. Supports arrays for both arguments.

expression_engine.solve('dates_diff("20230614", "20230618")', {})
# 4

expression_engine.solve('dates_diff("20230101", "20231231", "M")', {})
# 11

is_bday¶

is_bday(string_date, calendar=None)

Vectorized. Returns True if string_date is a business day. Returns None for invalid dates.

expression_engine.solve('is_bday("20241111")', {})
# True  (Monday)

expression_engine.solve('is_bday("20241109")', {})
# False  (Saturday)

previous_bizday¶

previous_bizday(date, calendar=None)

Vectorized. Returns the business day immediately before date.

expression_engine.solve('previous_bizday("20241111")', {})
# '20241108'  (Friday before Monday Nov 11)

next_bizday¶

next_bizday(date, calendar=None)

Vectorized. Returns the business day immediately after date.

expression_engine.solve('next_bizday("20241111")', {})
# '20241112'

nth_bizday¶

nth_bizday(day, month, year, calendar=None)

Vectorized. Returns the nth business day of the given month and year. day is an ordinal string such as '1st', '3rd', '15th'.

expression_engine.solve('nth_bizday("15th", 11, 2024)', {})
# '20241121'

expression_engine.solve('nth_bizday("15th", 11, 2024, "ANBIMA")', {})
# '20241125'  (adjusted for ANBIMA holidays)

nth_normal_day¶

nth_normal_day(day, month, year, calendar=None)

Vectorized. Returns the nth calendar day of the given month and year.

expression_engine.solve('nth_normal_day("15th", 11, 2024)', {})
# '20241115'

bizday_after_specific_day¶

bizday_after_specific_day(bizday_position, date, calendar=None)

Vectorized. Returns the nth business day after the calendar day of the month given by date. bizday_position is 'first', 'second', or 'third'.

expression_engine.solve('bizday_after_specific_day("first", "20241101")', {})
# '20241104'  (first bday after day 1 of Nov 2024)

expression_engine.solve('bizday_after_specific_day("first", "20241110")', {})
# '20241111'  (first bday after day 10 of Nov 2024)

bizday_before_specific_day¶

bizday_before_specific_day(bizday_position, date, calendar=None)

Vectorized. Returns the nth business day before the calendar day of the month given by date.

expression_engine.solve('bizday_before_specific_day("first", "20241120")', {})
# '20241119'  (first bday before day 20 of Nov 2024)

bizday_after_specific_weekday¶

bizday_after_specific_weekday(bizday_position, weekday, date, calendar=None)

Vectorized. Returns the nth occurrence of a specific business weekday after the day given by date. weekday is a 3-letter abbreviation: 'Mon', 'Tue', 'Wed', 'Thu', 'Fri'.

expression_engine.solve('bizday_after_specific_weekday("first", "Wed", "20241101")', {})
# '20241106'  (first Wednesday after day 1 of Nov 2024)

bizday_before_specific_weekday¶

bizday_before_specific_weekday(bizday_position, weekday, date, calendar=None)

Vectorized. Returns the nth occurrence of a specific business weekday before the day given by date.

expression_engine.solve('bizday_before_specific_weekday("first", "Wed", "20241125")', {})
# '20241120'  (first Wednesday before day 25 of Nov 2024)