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)).

PreviousDatafields NextLanguages

Last updated 27 days ago