Numbers
@abs
parameter: a number or currency
returns: the absolute value of that number or currency
For example, @abs(-5 EUR) will return 5 EUR, while @abs(-789) will return 789 and @abs(123.45) will return 123.45.
@average
parameters: a list of numbers or currency values
returns: the average of those numbers/values
This function returns the average of the list of values. For example:
@average(@list(2, 4, 6))returns 4@average(@list(2.1, 3.2, 4.4))returns 3.233@average(@list(2100 EUR, 3200 EUR, 4405 EUR))returns 3235 EUR
Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).
@count
parameter: some list
returns a whole number
see also: @list and @length (for calculating the length of text)
Returns the number of elements present in the list.
For example, @count(@empty-list) results in 0, while @count(@list(‘alpha’, ‘beta’)) results in 2.
@dynamic-fullnr
parameter: some whole number
returns text
see also: @fullnr
Returns the specified number either as-is (e.g., “30”), or in letters (e.g., “thirty”), or in letters with parenthesized numbers (e.g., “30 (thirty”)), depending on the styling settings.
@extract-currency
parameter: a currency value
returns the currency (“USD”, “EUR”, “GBP” or “JPY”) as a text value
see also: @extract-number and @construct-currency
Extracts the currency from the currency-value.
For example, @extract-currency(5 EUR) would extract the value “EUR”.
@extract-number
parameter: a currency value or a duration value
returns (i) in the case of a currency value, the amount of the currency as a floating point value; or (ii) in the case of a duration value, the number of days/weeks/months/years entered.
see also @extract-currency and @construct-currency
Extracts the amount from the currency-value/number of the duration.
For example, @extract-number(5 EUR) would extract the value 5 and extract-number(2 months) would extract the value 2.
@fullnr
parameter: number or currency
returns text
see also: @dynamic-fullnr en @fullcurrency
Converts the amount into text, according to the current language. If a floating point number is passed, then the part after the decimal point is also included. If a currency is passed, then currency is also added. Examples:
@fullnr(365)will result in three hundred and sixty-five in English@fullnr(365)will result in three hundred and sixty-five in English@fullnr(12.340 EUR)will result indouze virgule trente-quatre EURin French@fullnr(1234.56)will result in duizend tweehonderdvierendertig komma zesenvijftig in Dutch
The maximum number you can use in Clause9, is 99.999.999.999 (99 billion etc).
@fullcurrency
parameter: currency
returns text
see also: @fullnr and @dynamic-fullnr and @fullduration
Converts the currency-number into text, according to the current language. Unlike @fullnr, the @fullcurrency:
also converts the currency itself into words, depending on the language
will convert the fractional part into cents, penny or whatever the fractional part is called in that currency
For example, in English, @fullcurrency(123.45 USD) will be converted into “one hundred and twenty-three United States dollars and forty-five cents“, while @fullcurrency(23.4 NOK) will be converted into “twenty-three Norwegian kroner and forty øre“.
For most currencies, this function will even dynamically switch between the singular and plural word used for the currency and its fractional part. For example, @fullcurrency(1.30 EUR) will be converted into “one euro and thirty cents“, while @fullcurrency(2.01 EUR) will be converted into “two euros and zero one cent”.
@fullduration
parameter: duration
returns text
see also: @fullnr and @dynamic-fullnr
Converts the duration into text, according to the current language. For example, @fullduration(5 months) will be converted into five months in English.
@floor
parameter: a (whole or fractional) number
returns: a whole number
see also: @round
Rounds the given number to the lowest integer — i.e., the decimal numbers are simply cut off. This function is typically used to avoid the rounding (to the nearest number) that will occur with automatic conversions.
Examples:
@floor(123.6)will result in 123@floor(45)will result in 45{100 / 6.0} will result in 16.6667, while {
@floor(100 / 6.0)}will result in 16
@format-plain-nr
parameter: a (whole or fractional) number
returns text
see also: @format-nr
Formats the given number as a plain number, without any decimals or thousands grouping.
Examples:
@format-plain-nr(100 / 3.0)results in “33”. Note that{100 / 3.0}would result in “33.3333” or “33,3333”, depending on the locale settings@year-of(2019_01_16)will result in “2.019” or “2,019”, depending on the locale settings. However,@format-plain-nr(@year-of(2019_01_16))will result in a plain “2019”
Note in the examples above that rounding to the nearest number will occur.
@format-nr
first parameter: a number with currency, or a (whole or fractional) number
second parameter: either a text containing a sample, or a whole number
returns text
see also: @format-plain-nr
If the second parameter is a text, then Clause9 will format the first parameter in accordance with the sample given in the second parameter. Clause9 will analyse the way the sample is constructed, and try to mimic this when formatting the given number, taking into account the following features:
whether or not a decimals-symbol (comma or dot) is used, and — if a decimals-symbol is indeed used — the amount of decimal numbers
for currencies: the position of the currency (before or after the numbers) and whether to use a word (EUR, USD, …) or a symbol instead (€, $, …)
Examples (assuming continental European styling for numbers):
@format-nr(4567.89 EUR, "EUR 123")will result in “EUR 4.568”@format-nr(4567.89 EUR, "123€“) will result in “4.568€”@format-nr(4567.89 EUR, "€123")will result in “€4.568”@format-nr(4567, "123.4567")will result in “4.567,0000”@format-nr(4567, "123.4")will result in “4.567,0”@format-nr(4567.89, "123")will result in “4.568”
If the second parameter is a whole number instead, then the number will be formatted in accordance with the default styling, with the specified amount of decimals numbers. Examples (assuming continental European styling for numbers):
@format-nr(4567.89 EUR, 0)will result in “4.568 EUR”@format-nr(4567.89 EUR, 1)will result in “4.567,9 EUR”@format-nr(4567 EUR, 2)will result in “4.567,00 EUR”@format-nr(4567, 4)will result in “4.567,0000”@format-nr(4567.789, 4)will result in “4.567,7890”
Note in the examples above that rounding to the nearest number will occur.
@marginal
no parameters
inserts a marginal (in Dutch: “randnummer”) number, i.e. a number that is always increased within the document upon each use, followed by a period
see also @seq
For example, @marginal — no parentheses or parameters necessary — will ensure that a number will get inserted.
Note that the marginal is printed as a green “#nr” in the preview, so is not shown as a real number within the preview. Upon export to Word or PDF, it will be converted into a real number that increases with every paragraph in which you use it.
Tip: If you do not want to have a period inserted automatically, or you want to use different sequentially numbered lists, check out @seq.
@max
parameters: a list of numbers of currency values
returns: the highest of those values
see also: @min
Returns the highest of a list of values. For example, @max(@list(3, 6, 2)) returns 6, while @max(@list(-8 EUR, 3 EUR, 5 EUR)) returns 5 EUR.
Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).
@min
parameters: a list of numbers of currency values
returns: the lowest of those values
see also: @max
Returns the lowest of a list of values. For example, @min(@list(3, 6, 2)) returns 3, while @min(@list(-5 EUR, 3 EUR, 8 EUR)) returns -5 EUR.
Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).
@ord
single parameter should be a number
returns a text contain the ordinal of the specified number
see also @short-ord
Returns the ordinal of the specified number, in the current language. Up to 20, this function returns the number in full — for example, @ord(15) returns fifteenth in English or quinzième in French. Above 20, the short version is used — for example, @ord(156) returns 156th in English or 156e in French.
@pagecount
no parameters
inserts a special Word-field that contains the total number of pages in the entire Word-document
For example, @pagecount — no parameters or parentheses necessary — would return “15” if that happens to be the total number of pages.
Note that the @pagecount cannot be calculated in the browser (i.e., will only export in Word or PDF). Within MS Word, the number of pages is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)
@pagenr
no parameters
inserts a special Word-field that contains the current page number in the entire Word-document
For example, @pagenr — no parameters or parentheses necessary — would return “15” if that happens to be the current page.
Note that @pagenr cannot be calculated in the browser (i.e., will only export in Word or PDF). Within MS Word, the page number is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)
@percent-divide
parameters: two numbers
returns a number
Divides the first number by the second number, multiplies the result by 100, and returns the final result. Typically used to calculate a percentage.
For example, @percent-divide(5, 20) returns 25,00 — because 5 is 25% of 20.
@range
parameters: two numbers
returns a list of numbers
Returns a list with numbers between the two passed numbers (including those numbers themselves).
For example, @range(1, 5)results in a list with elements 1, 2, 3, 4 and 5.
If the second number is smaller than the first number — e.g., @list(5, 3) — the resulting list will be empty.
@round
parameter: a (whole or fractional) number
returns: a whole number
see also: @floor
Rounds the given number to the nearest integer. This function is similar to the automatic conversions applied by Clause9 when converting between value types.
Examples:
@round(123.6)and@round(123.5)will both result in 124@round(123.49)will result in 123
@seq
parameter: the name of the list
inserts a number field, i.e. a number that is always increased within the document upon each use with the same list-name
When using this function a “seq” field will be inserted in MS Word. Such field allows you to use different sequentially numbered lists in the same document. You may want to, for example, use such lists to number a list of images, or a list of parties, or a list of attachments, etc. Each time you invoke this function with the same list name as the parameter, the number will be increased.
Note that the number is printed as a green “#nr” in the preview, so is not shown as a real number within the preview. Upon export to Word or PDF, it will be converted into a real number that increases with every paragraph in which you use it.
Tip: A simpler function is the @marginal (no parameters required). It is always followed by a period, which may or may not be what you want.
@short-ord
single parameter should be a number
returns a text contain the short ordinal of the specified number
see also @ord
Returns the ordinal of the specified number, in the current language. This function always returns the “short” number — for example, @short-ord(15) returns 15th in English or 15e in French.
@tracked-seq
parameters: list-name, item-name and formatting (all texts)
returns a new version of the formatting-text, with the number replaced
see also @tracked-seq-list and @seq
This special function and its sibling @tracked-list-seq offer a solution to authors who want to keep track of a collection of items, in the order they are inserted. Every time this special function is called, it will check in its inventory whether the combination of the specified list-name and item-name was previously called:
If this combination was not yet called before, then the software will check how many other items were are already stored in the specified list, and increase this number by one. This new number will then be assigned to the specified item-name, and that number will be used to replace the {1} in the formatting instruction. The software will then store the result in its memory.
if this combination was indeed already called before, then the previously calculated result will be returned.
The @tracked-seq-list will return a list of all the previously generated results, in the order they were initially called.
For example, assume you are creating a Binder and you need to add appendices for which the title depends on the order in which these appendices happened to be mentioned within the body of the main document. The following calls are potentially used, depending on various conditions attached to clauses in the body:
Clause 3.2:
@tracked-seq("alpha", "pricing appendix", "Appendix {1}")Clause 5:
@tracked-seq("alpha", "ordered items appendix", "Appendix {1}")Clause 7:
@tracked-seq("alpha", "legal claims appendix", "Appendix {1}")Clause 8:
@tracked-seq("alpha", "ordered items appendix", "Appendix {1}")Clause 9:
@tracked-seq("alpha", "pricing appendix", "Appendix {1}")
Those calls will then result in Appendix 1, Appendix 2, Appendix 3, Appendix 2, Appendix 1 respectively. Notice that when the ordered items appendix was again requested, the software noticed that that item had been previously requested, and therefore returns the previously stored result.
You can then create a list of appendices through @tracked-seq-list, which would result in a list-of-text containing Appendix 1, Appendix 2 and Appendix 3. You can then feed that result to other functions, e.g. @enumerate-and.
@tracked-seq-list
parameter: list-name
returns a list of all the previously generated texts for the specified list
see also @tracked-seq
See the companion special function @tracked-seq for a detailed explanation.
Last updated