Temporal Objects Manipulation

To get a part of a temporal variable:

year(2016.02.14);
// output: 2016

monthOfYear(2016.02.14);
// output: 2

dayOfMonth(2016.02.14);
// output: 14

x=01:02:03.456;
hour(x);
// output: 1

minuteOfHour(x);
// output: 2

secondOfMinute(x);
// output: 3

x mod 1000;
// output: 456

To adjust the value of a temporal variable with an amount in the same time unit, we can use operators '+' or '-':

2016.02M-13;
// output: 2015.01M

2018.02.17+100;
// output: 2018.05.28

01:20:15+200;
// output: 01:23:35

For temporal objects of data type minute, second, time, and nanotime, the internal integers representing these objects have a lower limit of zero and an upper limit of 1440-1, 86400-1, 86400000-1, and 86400000000000-1 respectively. If the internal integer representing one of these objects after adjustment is below 0 or above the corresponding upper limit, the final result corresponds to the remainder of dividing the internal integer by the corresponding upper limit.

23:59m+10;
// output: 00:09m

00:00:01-2;
// output: 23:59:59

23:59:59.900+200;
// output: 00:00:00.100

To adjust the value of a temporal variable with an amount in the same or a different time unit, we can use function temporalAdd.

temporalAdd(2017.01.16,1,"w");
// output: 2017.01.23

temporalAdd(2016.12M,2,"M");
// output: 2017.02M

temporalAdd(13:30m,-15,"m");
// output: 13:15m

DolphinDB provides a set of functions for temporal object manipulation that adjust dates to specific calendar boundaries (such as month-start, month-end, business days, etc.), supporting natural calendar, business calendar, and fiscal calendar semantics.

Natural Calendar Functions

• monthBegin: Returns the first day of the current month.

• monthEnd: Returns the last day of the current month.

• semiMonthBegin: Returns the start date of the current semi-monthly period (the 1st or the 15th).

• semiMonthEnd: Returns the end date of the current semi-monthly period (the 15th or the last day of the month).

• quarterBegin: Returns the first day of the current quarter.

• quarterEnd: Returns the last day of the current quarter.

• weekEnd: Returns the end date of the current week (the end-of-week day is configurable; defaults to Sunday).

• weekBegin: Returns the start date of the current week (the start-of-week day is configurable; defaults to Monday).

• lastWeekOfMonth: Returns the date of the last specified weekday in the current or previous month (the target weekday is configurable; defaults to Monday).

• weekOfMonth: Returns the date of a specified weekday in a specified week of the current or previous month (defaults to Monday of the first week).

• yearBegin: Returns the first day of the current year.

• yearEnd: Returns the last day of the current year.

Calculation Rules

In DolphinDB, these functions determine the time period (month / quarter / semi-month / week / year) to which the input date belongs and directly return the start or end date of that period. They do not evaluate whether a date is a business day; they calculate results entirely according to calendar rules. For example, monthBegin returns the 1st day of the month containing the input date, and quarterEnd returns the last day of the corresponding quarter. The semantics are generally consistent with the corresponding period-boundary functions in pandas.

monthBegin(2016.12.06);
// output: 2016.12.01
monthEnd(2016.12.06);
// output: 2016.12.31
semiMonthBegin(2016.12.26);
// output: 2016.12.15
semiMonthEnd(2016.12.06, 15);
// output: 2016.11.30
quarterBegin(2012.06.12);
// output: 2012.04.01
quarterEnd(2012.06.12);
// output: 2012.06.30
weekEnd(2019.11.24);
// output: 2019.11.24
weekBegin(2019.11.24);
// output: 2019.11.18
lastWeekOfMonth(2019.11.01);
// output: 2019.10.28
weekOfMonth(2019.11.01);
// output: 2019.10.07
yearBegin(2011.06.02);
// output: 2011.01.01
yearEnd(2011.06.02);
// output:2011.12.31

Business Date Functions

Business date functions handle non-natural-calendar scenarios, such as business days (Monday through Friday).

• businessDay: Returns the current date if it is a business day; otherwise returns the most recent preceding business day.

• businessMonthBegin: Returns the first business day of the current month.

• businessMonthEnd: Returns the last business day of the current month.

• businessQuarterBegin: Returns the first business day of the current quarter.

• businessQuarterEnd: Returns the last business day of the current quarter.

• businessYearBegin: Returns the first business day of the current year.

• businessYearEnd: Returns the last business day of the current year.

Calculation Rules

These functions first determine the time period (month / quarter / year) to which the input date belongs, then locate the first or last business day (Monday–Friday) within that period. For businessDay, if the input falls on a non-business day, the most recent preceding business day is returned. For Begin/End functions: Begin functions use rollback semantics, returning the first business day of the input date's period (or the previous period); End functions use rollforward semantics, returning the last business day of the input date's period (or the next period).

For example:

• businessMonthBegin(2026.02.02) (Monday) returns 2026.02.02 (the first business day of the month happens to be the input date itself), while businessMonthBegin(2026.01.31) (Saturday) returns 2026.01.01 (rolls back to the first business day of the current month). This is semantically equivalent to pandas BMonthBegin().rollback(ts).

• businessMonthEnd(2026.02.02) (Monday) returns 2026.02.27 (the last business day of the month), while businessMonthEnd(2026.01.31) (Saturday) returns 2026.02.27 (the date has passed the last business day of the current month, so it rolls forward to the last business day of the next month). This is semantically equivalent to pandas BMonthEnd().rollforward(ts).

Additionally, DolphinDB offers an extended capability: when both the offset and n parameters are specified, the system constructs a contiguous sequence of business periods (e.g., day, month, quarter, or year), where offset determines the alignment anchor and n defines the grouping interval (in period units). In this mode, the calculation is no longer confined to boundary positioning within a single period; instead, the business-period sequence is first grouped, and then Begin/End semantics are applied within each group interval.

businessDay(2026.02.01) 
// output: 2026.01.30
businessMonthBegin(2016.10.06); 
// output: 2016.10.03
businessMonthEnd(2016.07.06);
// output: 2016.07.29
businessQuarterBegin(2012.06.12); 
// output: 2012.04.02
businessQuarterEnd(2012.06.12); 
// output: 2012.06.29
businessYearBegin(2011.06.02); 
// output: 2011.01.03
businessYearEnd(2011.06.12);
// output: 2011.12.30

Temporal Property Extraction Functions

• isMonthStart: Returns whether the input date is the first day of its month.

• isMonthEnd: Returns whether the input date is the last day of its month.

• daysInMonth: Returns the number of days in the month of the input date.

• isQuarterStart: Returns whether the input date is the first day of its quarter.

• isQuarterEnd: Returns whether the input date is the last day of its quarter.

• isYearStart: Returns whether the input date is the first day of its year.

• isYearEnd: Returns whether the input date is the last day of its year.

• isLeapYear: Returns whether the year of the input date is a leap year.

Calculation Rules

These functions directly evaluate a calendar property of the input date and return a Boolean value or integer. They do not involve time offsets or period calculations. For example, isMonthEnd checks whether the date equals the last day of its month, and daysInMonth computes the number of days based on the year and month (returning 29 for February in a leap year). The semantics are generally consistent with pandas.

isMonthStart(2011.01.01); 
// output: true 
isMonthEnd(2011.12.31);
// output: true 
daysInMonth(2012.12.02);
// output: 31 
isQuarterStart(2011.01.01);
// output: true 
isQuarterEnd(2011.12.31);
// output: true 
isYearStart(2011.01.01);
// output: true 
isYearEnd(2011.12.31);
// output: true 
isLeapYear(2012.06.25);
// output: true

Fiscal Calendar

Fiscal calendar functions handle time partitioning based on fiscal-year rules, such as the 52/53-week fiscal year model (FY5253). These functions rely on fiscal-year parameters including the fiscal year-end month, the week-ending day, the nearest/last strategy, and the 53rd-week insertion policy.

• fy5253: Returns the first day of the current fiscal year.

• fy5253Quarter: Returns the first day of the current fiscal quarter.

Calculation Rules

Based on the FY5253 fiscal year model, these functions determine the fiscal year or fiscal quarter to which the input date belongs according to the configuration parameters (fiscal year-end month, week-ending day, nearest/last strategy), and return the start date of that fiscal year or quarter.

Calculation process:

1. Determine the fiscal year-end anchor (e.g., the last or nearest Friday in December).

2. Divide the fiscal year into 52 or 53 weekly intervals based on this anchor.

3. Identify which interval the input date falls into and return the start date of that interval.

Semantically equivalent to pandas FY5253().rollback(ts) and FY5253Quarter().rollback(ts).

fy5253(2016.11.01); 
// output: 2016.02.01
fy5253Quarter(2016.11.01);
// output: 2016.10.31

Time Interval Type

The duration function parses a string into a time-interval type (e.g., "5M" indicates 5 months; "3XNYS" indicates 3 NYSE trading days). Unlike calendar-boundary functions, it represents a time span rather than a point in time and does not support comparison or arithmetic operations.

duration("5M") 
// output: 5M 
duration("3XNYS")
// output: 3XNYS