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:
dfor the day of the month in numbers (e.g., 9 or 24)ddfor the day of the month, with two digits (e.g., 09 or 24)mfor the number of the month (e.g., 2 for February, 11 for March)mmfor the number of the month, with two digits (e.g., 02 for February, 11 for March)yyfor the year, with two digits (e.g., 23 for 2023)yyyyfor the year, with four digits (e.g., 2023)mmmmfor the month, expressed as a full word (e.g., “février” in French)wwwwfor the day of the week, expressed as a full word (e.g., “Monday”)commato literally insert a commaseparator options, to be inserted as the very first part
slashedto specify that slashes should be used as separatorsspacedto specify that spaces should be used as separatorsdottedto specify that dots (.) should be used as separatorsconcatto 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-yyyybecomes29-4-2023dd-mm-yyyybecomes29-04-2023slashed-d-m-yyyybecomes29/4/2023dotted-d-m-yyyybecomes29.4.2023concat-d-m-yyyybecomes2942023mm-dd-yyyybecomes04-29-2023wwww-comma-d-mmmm-yyyybecomesSaturday, 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)).
Last updated