Dates & durations

@calendar-days

• parameter: either a duration or a number

• returns text

Returns a piece of text saying “… calendar days”, in the current language and (if specified in the styling) with … being a number and/or words between parentheses. If the duration would happen to be currently specified in another time-unit than days, then a conversion to days will occur (similar to a using @days-in).

For example, if the styling for English specifies to use both numbers and words between parentheses, @calendar-days(5) will return “five (5) calendar days”, while @calendar-days(1) will return “one (1) calendar day” (notice the singular word “day”).

@construct-date

• first parameter: the year (e.g., 2020)

• second parameter: the month (e.g. 11 for November)

• third parameter: the day (e.g., 23)

• returns a date value constructed of the passed parametesr

For example, @construct-date(2020, 12, 23) will return the date of 23rd December 2020.

@construct-duration

• first parameter: an amount (e.g., 5)

• second parameter: “year”, “month”, “day”, “week” or “quarter” (or any of them in plural)

Returns a duration value that consists of the specified amount and unit.

Example: @construct-duration(5, "days")

@day-of

• parameter: a date

• returns a whole number between 1 – 31

• see also: @month-of and @year-of

Returns the day number (1 – 31) for the specified date.

@days-between

• parameters: two dates

• returns a whole number

• see also: @months-between, @weeks-between, @years-between

Returns the number of full days between the two dates.

Examples:

• @days-between(2019_2_5, 2019_2_6) will result in 1

• @days-between(2019_2_5, 2019_3_5) will result in 28

• @days-between(2019_2_5, 2019_8_23) will result in 199

@days-in-month

• parameter: a date

• returns a whole number

Returns the date of the last day of the month in the specified date.

For example, @days-in-month(2020_2_1) returns 29, because February has 29 days in the leap year 2020.

@days-in

• parameter: a duration value

• returns a whole number

• see also: @months-in, @quarters-in, @weeks-in, @years-in

Returns the number of days in the duration value.

Note that rounding errors can occur, because averages will be used, and no specific dates, leap years, etc. will be taken into account! For example, @days-in(1 month) will result in 30.

@duration-unit

• single parameter: a duration

• returns the time-unit of the duration — either “year”, “month”, “day”, “week” or “quarter”.

For example @duration-unit(23 years) will return “year”, while @duration-unit(1 month) will return “month”.

This function can be very useful to differentiate between different types of durations that may have been entered by the end-user. For example, in a Q&A, combined with expression conditions, you could show certain questions only when a previous duration-related question was answered in weeks.

@duration-apostrophe

• single parameter: a duration

• returns the duration, as text, with an apostrophe and -s where necessary

Converts the specified duration into the possessive word-version, adding an apostrophe and -s where necessary in English. For example, @duration-apostrophe(1 month) is converted into 1 month's, while @duration-apostrophe(2 years) is converted into 2 years'.

In any other language besides English, the duration is simply expanded into words, without any apostrophe or -s added.

@earliest

• parameter: two dates

• returns: a date

• see also: @latest

Returns the earliest of the two dates.

For example, @earliest(2018_01_05, 2010_01_01) returns 1st January 2010.

@first-day-of-month

• parameter: a date

• returns a date

• see also: @last-day-of-month

Returns the date of the first day of the month in the specified date.

For example, @first-day-of-month(2019_02_05) returns 1st February 2019.

@format-date

• parameters:

  • a date

  • a text describing the formatting for the date

• results in a text containing the formatted date

This special function allows you to specify a custom date format. The second parameter should consist of a combination (separated by hyphens) of the following parts:

• d for the day of the month in numbers (e.g., 9 or 24)

• dd for the day of the month, with two digits (e.g., 09 or 24)

• m for the number of the month (e.g., 2 for February, 11 for March)

• mm for the number of the month, with two digits (e.g., 02 for February, 11 for March)

• yy for the year, with two digits (e.g., 23 for 2023)

• yyyy for the year, with four digits (e.g., 2023)

• mmmm for the month, expressed as a full word (e.g., “février” in French)

• wwww for the day of the week, expressed as a full word (e.g., “Monday”)

• comma to literally insert a comma

• separator options, to be inserted as the very first part

  • slashed to specify that slashes should be used as separators

  • spaced to specify that spaces should be used as separators

  • dotted to specify that dots (.) should be used as separators

  • concat to specify that nothing should be used as separators

When mmmm is included, then spaces will be used as separators between the various parts. Else, hyphens are used, except if the first part of the formatting text starts with slashed/spaced/dotted/concat.

Examples using 29 April 2023 (in English):

• d-m-yyyy becomes 29-4-2023

• dd-mm-yyyy becomes 29-04-2023

• slashed-d-m-yyyy becomes 29/4/2023

• dotted-d-m-yyyy becomes 29.4.2023

• concat-d-m-yyyy becomes 2942023

• mm-dd-yyyy becomes 04-29-2023

• wwww-comma-d-mmmm-yyyy becomes Saturday, 29 April 2023

@fullmonth

• parameter: a number between 1 and 12

• returns the month as text, in the current language

For example, @fullmonth(8) will return “août” in French, “August” in English or “augustus” in Dutch.

@is-days

• parameter: a duration datafield

• returns true or false

• see also: @is-months, @is-quarters, @is-weeks, @is-years

Returns true if the duration is currently specified in days.

Tip: you can easily invert the behaviour of this special function: not(@is-days(#concept^datafield)) will return true if the specified datafield is not specified in days.

@is-months

• parameter: a duration datafield

• returns true or false

• see also: @is-days, @is-quarters, @is-weeks, @is-years

Returns true if the duration is currently specified in months.

Tip: you can easily invert the behaviour of this special function: not(@is-months(#concept^datafield)) will return true if the datafield is not currently specified in months.

@is-quarters

• parameter: a duration datafield

• returns true or false

• see also: @is-days, @is-months, @is-weeks, @is-years

Returns true if the duration is currently specified in quarters.

Tip: you can easily invert the behaviour of this special function: not(@is-quarters(#concept^datafield)) will return true if the datafield is not currently specified in quarters.

@is-valid-date

• parameters: a number for the year, a number of the month and a number for the day of the month

• returns true or false

• see also: @construct-date

Returns true if the duration is valid. For example, @is-valid-date(2021, 2, 24) would be valid (because 24th February, 2021 is a valid) date, while @is-valid-date(2021, 2, 31), because 31st of February is invalid.

Tip: you can easily invert the behaviour of this special function. For example, {@not(@is-valid-date(#concept^year, #concept^month, #concept^day)): !! invalid date specified !! | else: @construct-date(#concept^year, #concept^month, #concept^day) } would print an error message if the date is invalid, while it would print that date if it is effectively valid.

@is-weeks

• parameter: a duration datafield

• returns true or false

• see also: @is-days, @is-months, @is-quarters, @is-years

Returns true if the duration is currently specified in weeks.

Tip: you can easily invert the behaviour of this special function: not(@is-weeks(#concept^datafield)) will return true if the datafield is not currently specified in weeks.

@is-years

• parameter: a duration datafield

• returns true or false

• see also: @is-days, @is-months, @is-quarters, @is-weeks

Returns true if the duration is currently specified in years.

Tip: you can easily invert the behaviour of this special function: not(@is-years(#concept^datafield)) will return true if the datafield is not currently specified in years.

@last-day-of-month

• parameter: a date

• returns a date

• see also: @first-day-of-month

Returns the date of the last day of the month in the specified date.

For example, @last-day-of-month(2019_02_05) returns 28th February 2019.

@latest

• parameter: two dates

• returns: a date

• see also: @earliest

Returns the latest of the two dates.

For example, @latest(2018_01_05, 2010_01_01) returns 5th January 2018.

@minutes-in-timings

• parameters: pairs of texts that designate the start and end timing (either formatted as “1000” or “10:00”)

• returns: the number of minutes between the start and end timing

• see also: @minutes-in-timing-lists and @minutes-to-timing

Calculates the aggregate duration, in minutes, of all pairs of timings. Each timing should be a piece text, formatted as either “900” or with a colon in between (9:00); the initial zero is optional (i.e., “9:35”, “935”, “09:35” and “935” are all considered equal).

For example, @minutes-in-timings("09:00", "1200", "1400", "16:30") calculates the duration of 09:00-12:00 (= 180 minutes) and 14:00-16:30 (= 150 minutes), so for a total of 330 minutes.

If an uneven number of parameters would be passed, then last parameter will simply be ignored. Similarly, parameters that cannot be treated as proper timings, will be ignored, and result in a duration of 0 minutes for that pair. For example, @minutes-in-timings("09:00", "1000", "alpha", "beta") will result in 60.

This function is particularly handy for creating timing tables, like working schedules.

@minutes-in-timing-lists

• parameters: pairs of lists of texts that designate the start and end timing

• returns: the aggregate total number of minutes between the start and end timings

• see also: @minutes-in-timings and @minutes-to-timing

This function calculates the aggregate durations between the passed pairs of lists of texts. This is particularly useful for calculating the total duration of timing tables, such as working schedules.

For example, @minutes-in-timing-lists(@list("900", "1100", "13:00"), @list("12:00", "11:30", "13:45")) would calculate the total duration of:

• 09:00 to 12:00 — 3 hours or 180 minutes

• 11:00 to 11:30 — 30 minutes

• 13:00 to 13:45 — 45 minutes

• for a total of 255 minutes

The conversion of the texts is similar to what is described in @minutes-in-timings.

@minutes-to-timing

• parameter: a number (which designates a number of minutes)

• returns: text, consisting of the number of hours and minutes, with a colon (:) in between

• see also: @minutes-to-timing

This function converts the specified number to a a text formatted as hours:minutes. For example, @minutes-to-timing(135) will result in the text “2:15”.

@month-of

• parameter: a date

• returns a whole number

• see also: @day-of and @year-of

Returns the month number (1 – 12) of the specified date.

For example, @month-of(2018_4_2) returns 4.

@months-between

• parameters: two dates

• returns a whole number

• see also: @days-between, @weeks-between, @years-between

Returns the number of full months between two dates.

Examples:

• @months-between(2019_2_5, 2019_2_6) will result in 0

• @months-between(2019_2_5, 2019_3_5) will result in 1

• @months-between(2019_2_5, 2019_8_23) will result in 6

@months-in

• parameter: a duration value

• returns a whole number

• see also: @days-in, @quarters-in, @weeks-in, @years-in

Returns the number of months in the duration value.

@quarters-in

• parameter: a duration value

• returns a whole number

• see also: @days-in, @months-in, @weeks-in, @years-in

Returns the number of full quarters in the duration value.

For example, @quarters-in(2 years) will result in 8.

@today

• no parameters

• returns a date

For example, @today — no parentheses or parameters necessary — will insert today’s date.

Note that this will cause a document to have a different output depending on the day it is exported to PDF or .DOCX.

@weeks-in

• parameter: a duration value

• returns a whole number

• see also: @days-in, @months-in, @quarters-in, @years-in

Returns the number of weeks in the duration value.

For example, @weeks-in(1 year) results in 52.

@weeks-between

• parameters: two dates

• returns a whole number

• see also: @days-between, @months-between, @years-between

Returns the number of full weeks between two dates.

Examples:

• @weeks-between(2019_2_5, 2019_2_6) will result in 0 (only one day difference)

• @weeks-between(2019_2_5, 2019_3_5) will result in 4

@week-nr

• parameter: a date

• returns a whole number

Returns the number (1 – 52) of the week within the year.

For example, @week-nr(2018_4_5) returns 14.

@weekday-nr

• parameter: a date

• returns a whole number

• see also: @weekday

Returns the number of the day (1 = Monday, 7 = Sunday) for the specified date.

@weekday

• parameter: a date

• returns the day of the week

• see also: @weekday-nr

Returns the name of the week day (e.g., “Monday” in English, or “lundi” in French) for the specified date.

@years-in

• parameter: a duration value

• returns a whole number

• see also: @days-in, @months-in, @quarters-in, @weeks-in

Returns the number of years in the duration value.

For example, @years-in(4 year) results in 4, while @years-in(36 months) results in 3.

@year-of

• parameter: a date

• returns a whole number

• see also: @day-of and @month-of

Returns the year of the specified date.

For example, @year-of(2018_4_2) returns the number 2018.

If the result of this function is directly inserted into the text, then you probably want to use @format-plain-nr to prevent thousands grouping symbols. For example, @year-of(2018_4_2) will result in “2.018” under continental European formatting, which is probably not what you want. To remove the period from the output, use @format-plain-nr(@year-of(2018_4_2)).