In-Reply-To: <7c7bb85c51cd427a82fbb5dcdcdfa7b1@git.apache.org> References: <7c7bb85c51cd427a82fbb5dcdcdfa7b1@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [26/50] incubator-freemarker-site git commit: 2.3.26-nightly docs preview archived-at: Mon, 13 Mar 2017 10:58:05 -0000 http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/ref_builtins_node.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/ref_builtins_node.html b/builds/2.3.26-nightly/ref_builtins_node.html new file mode 100644 index 0000000..f615ae0 --- /dev/null +++ b/builds/2.3.26-nightly/ref_builtins_node.html @@ -0,0 +1,287 @@ + + + + + +Built-ins for nodes (for XML) - Apache FreeMarker Manual + + + + + + + + + + + + + + + + + +

+ + + +

Built-ins for nodes (for XML)

Note that the variables returned by these built-ins are + generated by the node variable implementation it is used with. This + means that the returned variables can have extra features in + additional to what it stated here, for example, with the XML DOM nodes the sequence retuned by + the children built-in also can be used as hash and + maybe as string, as it is described in the part + about XML processing.

+ + + + +

ancestors

+ + + + +

A sequence that contains all the node's ancestors, starting + with the immediate parent and ending with the root node. The result + of this built-in is also a method, by which you can filter the + result with the full-qualified name of the + node. For example as node?ancestors("section") to + get the sequence of all ancestors with name + section.

+ + + + + +

children

+ + + + +

A sequence that contains all of this node's child nodes (i.e. + immediate descendant nodes).

+ +

XML: This is almost the same as special hash key + *, except that it returns all nodes, not only + elements. So the possible children are element nodes, text nodes, + comment nodes, processing instruction nodes, etc. but + not attribute nodes. Attribute nodes are + excluded from the sequence.

+ + + + + +

node_name

+ + + + +

Returns the string that is used to determine what user-defined + directive to invoke to handle this node when it is + "visited". See: the visit and recurse directives.

+ +

XML: If the node is an element or attribute, then the string + will be the local (prefix free) name of the element or attribute. + Otherwise the name usually starts with @ followed + by the node type. See this + table. Note that this node name is not the same as the node + name returned in the DOM API; the goal of FreeMarker node names is + to give the name of the used-defined directive that will process the + node.

+ + + + + +

next_sibling

+ + + + +

+ Note: + +

This built-in is only available since 2.3.26

+ + +

Returns the following sibling node of the node. (Two nodes in + a tree are said to be siblings if they are on the same level and are + directly next to each other.) If there's no such node, the + expression + node?next_sibling?? + evaluates to false.

+ +

XML: Note that the value returned by this built-in is also a + sequence of length 1 (same as the result of some XPath expressions), + however if there's no next sibling, the result is a missing value + (null) instead of an empty sequence. Also note that for XML element + nodes you can also use + node.@@next_sibling_element, + which is practical if you want to ignore the whitespace that + separates two apparently sibling elements; see more here...

+ +

+ Note: + +

For custom node implementations this built-in is only + supported if that implements the + freemarker.template.TemplateNodeModelEx + interface.

+ + + + + + +

node_namespace

+ + + + +

Returns the namespace string of the node. FreeMarker does not + define the exact meaning of node namespace; it depends on what your + node variables are modeling. It's possible that a node doesn't have + any node namespace defined. In this case, the built-in should + evaluate to undefined variable (i.e. + node?node_namespace?? + is false), so you can't use the returned + value.

+ +

XML: In the case of XML, it's the XML namespace URI (such as + "http://www.w3.org/1999/xhtml"). If an element or + attribute node does not use XML namespace, then this built-in + evaluates to an empty string. For other XML nodes this built-in + always return undefined variable.

+ + + + + +

node_type

+ + + + +

A string that describes the type of the node. FreeMarker does + not define the exact meaning of node type; it depends on what your + variables are modeling. It's possible that a node doesn't support + node type at all. In this case, the built-in evaluates to an + undefined value, so you can't use the returned value. (You can still + check if a node supports the type property with + node?node_type??.)

+ +

XML: The possible values are: "attribute", + "text", "comment", + "document_fragment", + "document", "document_type", + "element", "entity", + "entity_reference", + "notation", "pi". Note that a + there is no "cdata" type, because CDATA is + considered as plain text node.

+ + + + + +

parent

+ + + + +

Returns the node that is this node's immediate parent in the + node tree. The root node has no parent node, so for the root node, + the expression + node?parent?? + evaluates to false.

+ +

XML: Note that the value returned by this built-in is also a + sequence (same as the result of XPath expression + .., when you write + someNode[".."]), however if there's no parent, + the result is a missing value (null) instead of an empty sequence. + Also note that for attribute nodes, it returns the element the + attribute belongs to, despite that attribute nodes are not counted + as children of the element.

+ + + + + +

previous_sibling

+ + + + +

+ Note: + +

This built-in is only available since 2.3.26

+ + +

Returns the previous sibling node of the node. Apart from the + direction, this is the same as next_sibling, so + see more details there...

+ +

+ Note: + +

For custom node implementations this built-in is only + supported if that implements the + freemarker.template.TemplateNodeModelEx + interface.

+ + + + + + +

root

+ + + + +

The node that is the root of the tree of nodes to which this + node belongs.

+ +

XML: According to W3C, the root of an XML document is not the + topmost element node, but the document itself, which is the parent + of the topmost element. For example, if you want to get the topmost + element of the XML (the so called + "document element"; do not mix it with the + "document"), which is called foo, + then you have to write someNode?root.foo. If you + write just someNode?root, then you get the + document itself, and not the document element.

Previous Next

+ http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/ref_builtins_number.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/ref_builtins_number.html b/builds/2.3.26-nightly/ref_builtins_number.html new file mode 100644 index 0000000..4c99464 --- /dev/null +++ b/builds/2.3.26-nightly/ref_builtins_number.html @@ -0,0 +1,797 @@ + + + + + +Built-ins for numbers - Apache FreeMarker Manual + + + + + + + + + + + + + + + + + +

+ + + +

Previous Next

Built-ins for numbers

Related FAQs: Do you have things like 1,000,000 or 1 000 000 + instead of 1000000, or something like 3.14 instead of 3,14 or vice + versa? See this and this FAQ entry, also note + the c built-in above.

+ + + + +

abs

+ + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.20.

+ + +

Gives the absolute value of a number. For example + x?abs , if x is -5, will + evaluate to 5.

+ + + + + +

c (when used with numerical value)

+ + + + + + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.3.

+ + +

This built-in converts a number to string for a + "computer language" as opposed to for human audience. + That is, it formats with the rules that programming languages used + to use, which is independent of all the locale and number format + settings of FreeMarker. It always uses dot as decimal separator, and + it never uses grouping separators (like 3,000,000), nor exponential + form (like 5E20), nor superfluous leading or trailing 0-s (like 03 + or 1.0), nor + sign (like +1). It will print at most 16 digits after + the decimal dot, and thus numbers whose absolute value is less than + 1E-16 will be shown as 0. This built-in is crucial because be + default (like with ${x}) numbers are converted to + strings with the locale (language, country) specific number + formatting, which is for human readers (like 3000000 is possibly + printed as 3,000,000). When the number is printed not for human + audience (e.g., for a database record ID used as the part of an URL, + or as invisible field value in a HTML form, or for printing + CSS/JavaScript numerical literals) this built-in must be used to + print the number (i.e., use ${x?c} instead of + ${x}), or else the output will be possibly broken + depending on the current number formatting settings and locale (like + the decimal point is not dot, but comma in many countries) and the + value of the number (like big numbers are possibly + "damaged" by grouping separators).

+ +

If the incompatible_imporvements FreeMarker + configuration setting is set to 2.3.24 or higher (also if it's set + to 2.3.20 or higher and you are outside a string literal), this + built-in will return "INF", + "-INF" and "NaN" for + positive/negative infinity and IEEE floating point Not-a-Number, + respectively. These are the XML Schema compatible representations of + these special values. (Earlier it has returned what + java.text.DecimalFormat did with US locale, none + of which is understood by any (common) computer language.)

+ +

Note that this built-in also works on + booleans.

+ + + + + +

is_infinite

+ + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.20.

+ + +

Tells if a number is floating point infinite (according to + IEEE 754). For example, someNumber?is_infinite + evaluates to true or false + depending on if the value of someNumber is + infinite or not. Of course, if the underlying number is not of + floating point type, this will always return + false.

+ + + + + +

is_nan

+ + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.20.

+ + +

Tells if a number is floating point NaN (according to IEEE + 754). For example, someNumber?is_nan evaluates to + true or false depending on if + the value of someNumber is NaN or not. Of course, + if the underlying number is not of floating point type, this will + always return false.

+ + + + + +

lower_abc

+ + + + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.22.

+ + +

Converts 1, 2, + 3, etc., to the string "a", + "b", "c", etc. When reaching + "z", it continues like "aa", + "ab", etc. This is the same logic that you can + see in column labels in spreadsheet applications (like Excel or + Calc). The lowest allowed number is 1. There's no + upper limit. If the number is 0 or less or it + isn't an integer number then the template processing will be aborted + with error.

+ +

Example:

+ + + +

<#list 1..30 as n>${n?lower_abc} </#list>

+ +

Prints:

+ + + +

a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad

+ +

round, floor, ceiling

+ + + + + + + + + + +

+ Note: + +

The rounding built-ins exist since FreeMarker 2.3.13.

+ + +

Converts a number to a whole number using the specified + rounding rule:

+ +

+
round: Rounds to the nearest whole + number. If the number ends with .5, then it rounds upwards + (i.e., towards positive infinity)
+
+
floor: Rounds the number downwards + (i.e., towards neagative infinity)
+
+
ceiling: Rounds the number upwards + (i.e., towards positive infinity)
+

+ +

Example:

+ + + +

<#assign testlist=[
+  0, 1, -1, 0.5, 1.5, -0.5,
+  -1.5, 0.25, -0.25, 1.75, -1.75]>
+<#list testlist as result>
+    ${result} ?floor=${result?floor} ?ceiling=${result?ceiling} ?round=${result?round}
+</#list>

+ +

Prints:

+ + + +

    0 ?floor=0 ?ceiling=0 ?round=0
+    1 ?floor=1 ?ceiling=1 ?round=1
+    -1 ?floor=-1 ?ceiling=-1 ?round=-1
+    0.5 ?floor=0 ?ceiling=1 ?round=1
+    1.5 ?floor=1 ?ceiling=2 ?round=2
+    -0.5 ?floor=-1 ?ceiling=0 ?round=0
+    -1.5 ?floor=-2 ?ceiling=-1 ?round=-1
+    0.25 ?floor=0 ?ceiling=1 ?round=0
+    -0.25 ?floor=-1 ?ceiling=0 ?round=0
+    1.75 ?floor=1 ?ceiling=2 ?round=2
+    -1.75 ?floor=-2 ?ceiling=-1 ?round=-2

+ +

These built-ins may be useful in pagination operations and + like. If you just want to display numbers in + rounded form, then you should rather use the string + built-in or the number_format + setting.

+ + + + + +

string (when used with a numerical value)

+ + + + + + + + + + +

Converts a number to a string. In its simplest form + (expression?string) it + uses the default format that the programmer has specified via the + number_format and the locale + configuration settings. You can also specify a number format + explicitly with this built-in, as it will be shown later.

+ +

There are four predefined number formats: + computer, currency, + number, and percent. The exact + meaning of these is locale (nationality) specific, and is controlled + by the Java platform installation, not by FreeMarker, except for + computer, which uses the same formatting as the c built-in. + There can also be programmer-defined formats, whose name starts with + @ (programmers see more here...). You + can use these predefined formats like this:

+ + + +

<#assign x=42>
+${x}
+${x?string}  <#-- the same as ${x} -->
+${x?string.number}
+${x?string.currency}
+${x?string.percent}
+${x?string.computer}

+ +

If your locale is US English, this will print:

+ + + +

42
+42
+42
+$42.00
+4,200%
+42

+ +

The output of first three expressions is identical because the + first two expressions use the default format, which is + "number" here. You can change this default using a + setting:

+ + + +

<#setting number_format="currency">
+<#assign x=42>
+${x}
+${x?string}  <#-- the same as ${x} -->
+${x?string.number}
+${x?string.currency}
+${x?string.percent}

+ +

Will now output:

+ + + +

$42.00
+$42.00
+42
+$42.00
+4,200%

+ +

since the default number format was set to + "currency".

+ +

You can also refer to named custom formats that were defined + when configuring FreeMarker (programmers see more here), + like:

+ + + +

${x?string.@price}
+${x?string.@weight}

+ +

where the custom format names were "price" and + "weight". This way the templates can just refer to the + application-domain meaning, and the exact format can be specified + outside the templates, on a single central place. (Programmers can + read about defining such + named formats here...)

+ +

Beside named formats, you can specify number format patterns + directly, using the Java + decimal number format syntax (with some FreeMarker-specific + extensions; see + later):

+ + + +

<#assign x = 1.234>
+${x?string["0"]}
+${x?string["0.#"]}
+${x?string["0.##"]}
+${x?string["0.###"]}
+${x?string["0.####"]}
+
+${1?string["000.00"]}
+${12.1?string["000.00"]}
+${123.456?string["000.00"]}
+
+${1.2?string["0"]}
+${1.8?string["0"]}
+${1.5?string["0"]} <-- 1.5, rounded towards even neighbor
+${2.5?string["0"]} <-- 2.5, rounded towards even neighbor
+
+${12345?string["0.##E0"]}

+ + + +

1
+1.2
+1.23
+1.234
+1.234
+
+001.00
+012.10
+123.46
+
+1
+2
+2 <-- 1.5, rounded towards even neighbor
+2 <-- 2.5, rounded towards even neighbor
+
+1.23E4

+ +

Note that as in FreeMarker foo.bar is + equivalent with foo["bar"], you could also write + x?string.currency as + x?string["currency"], but of course that wouldn't + be practical. But in the above examples we have to use the square + bracket syntax, because the characters involved (numbers, dot, + #) aren't allowed syntactically after the dot + operator.

+ +

For historical reasons, you could also write things like + x?string("0.#"), which does exactly the same as + x?string["0.#"].

+ +

Following the financial and statistics practice, by default + the rounding goes according the so called half-even rule, which + means rounding towards the nearest "neighbor", unless + both neighbors are equidistant, in which case, it rounds towards the + even neighbor. This was visible in the above example if you look at + the rounding of 1.5 and of 2.5, as both were rounded to 2, since 2 + is even, but 1 and 3 are odds. The other popular rounding rule, + where we always round up when the neighbors are equidistant (and so + 2.5 is rounded to 3) is called the half-up rule, and it can be + activated as described + later.

+ +

As it was shown for the predefined formats earlier, the + default formatting of the numbers can be set in the template:

+ + + +

<#setting number_format="0.##">
+${1.234}

+ + + +

1.23

+ +

The default number format also can be specified outside the + templates with the FreeMarker API (like with + Configuration.setNumberFormat(String)).

+ +

Note that as number formatting is locale sensitive, the locale + setting also plays role in the formatting:

+ + + +

<#setting number_format=",##0.00">
+<#setting locale="en_US">
+US people write:     ${12345678}
+<#setting locale="hu">
+German people write: ${12345678}

+ + + +

US people write:     12,345,678.00
+German people write: 12.345.678,00

+ + + + + + +

Extended Java decimal format

+ + + + +

FreeMarker extends the Java decimal format patterns with + extra options. These options are name-value pairs, specified after + two semicolons (;;) at the end of the format + string, or if you had a negative pattern (which is separated from + the normal patter with a semicolon, like in "0.0;minus + 0.0"), the after only one semicolon. For example:

+ + + +

Standard decimal format: ${10002.5?string[",000"]}
+Extended decimal format: ${10002.5?string[",000;; roundingMode=halfUp groupingSeparator=_"]}

+ + + +

Standard decimal format: 10,002
+Extended decimal format: 10_003

+ +

Above, in the extended decimal format, we have specified + half-up rounding mode and group separator "_". + The table of all options follows (note that these are defined by + java.text.DecimalFormat and + java.text.DecimalFormatSymbols, not by + FreeMarker):

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name	Meaning / value
`roundingMode`	The value is one of `up`, + `down`, `ceiling`, + `floor`, `halfUp`, + `halfDown`, `halfEven`, + and `unnecessary`. The behavior that most + people learns in school is `halfUp`, but + the Java default is `halfEven` (also called + bankers' rounding). (See the + `java.math.RoundingMode` API for + explanations.)
`multipier`	The number will be shown after multiplied with this + integer number.
`decimalSeparator`	The character separating the integer part from the + fraction part (like `"."` in + `3.14`).
`monetaryDecimalSeparator`	This is used instead of + `decimalSeparator` when the pattern + contains parts that make it a monetary format. (See the + Java + decimal number format documentation for more.)
`groupingSeparator`	The single character used for grouping the integer part + (like `","` in + `1,000,000`) Note that grouping is turned + on by using `","` in the pattern, as shown + in the earlier example. If it's not turned on, this option + won't have visible effect.
`exponentSeparator`	This string (of arbitrary length) is used to separate + the exponent from the part before it. (like + `"E"` in `1.23E6`). Only + has visible effect if the pattern specifies exponential + (also known as scientific) format, like + `"0.##E0"`.
`minusSign`	The single character used as minus sign (like + `"-"` in `-1`).
`infinity`	The string (of arbitrary length) used to show + infinity.
`nan`	The string (of arbitrary length) used to show + not-a-number (NaN).
`percent`	The single character used as the percent symbol (like + `"%"` in `50%`). Only has + visible effect if the pattern contains + `%`.
`perMill`	The single character used as the per-mill symbol (like + `"‰"` in `50021‰`). Only + has visible effect if the pattern contains + `‰`.
`zeroDigit`	The first character in the 10 character range (of + character codes) that contains the digits to be used. For + example, if this is `A`, then 1 will + `B`, 2 will be `C`, and so + on.
`currencyCode`	Currency ISO 4217 code. Only has effect when the pattern + contains parts that make it a monetary format. It's an error + to specify a code that's not a known ISO 4217 code in the + Java installation.
`currencySymbol`	Currency symbol; shown where the localized currency name + is present in the pattern. Overrides the symbol determined + based on the `currencyCode`.

+ + +

Regarding the syntax of the options:

+ +

+
The option name and value are separated by equals + character (=).
+
+
Options are separated by whitespace and/or optional + comma (,)
+
+
The option value can be quoted with apostrophe + (') or normal quotation mark + (") , like + exponentSeparator='*10^' or + exponentSeparator="*10^". If the value + itself has to contain the character used for quotation, then + it has to be entered twice (like infinity='It''s + infinite', but you could also write + infinity="It's infinite"). Backslash has no + special meaning.
+
+
Non-string values must not be quoted. Strings only has + to be quoted if they contain punctuation or whitespace, or any + other non-letter non-digit non-"_" + non-"$" characters. Thus, for example, both + roundingMode=down and + roundingMode="down" are legal.
+

+ + + + + + +

upper_abc

+ + + + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.22.

+ + +

Same as lower_abc, + but converts to upper case letters, like "A", + "B", "C", …, + "AA", "AB", etc.

Previous Next

+ http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/ref_builtins_sequence.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/ref_builtins_sequence.html b/builds/2.3.26-nightly/ref_builtins_sequence.html new file mode 100644 index 0000000..a3fe4ba --- /dev/null +++ b/builds/2.3.26-nightly/ref_builtins_sequence.html @@ -0,0 +1,577 @@ + + + + + +Built-ins for sequences - Apache FreeMarker Manual + + + + + + + + + + + + + + + + + +

+ + + +

Previous Next

Built-ins for sequences

+ + + + +

chunk

+ + + + + + + + +

+ Note: + +

This built-in exists since FreeMarker 2.3.3.

+ + +

This built-in splits a sequence into multiple sequences of the + size given with the 1st parameter to the built-in (like + mySeq?chunk(3)). The result is the sequence of + these sequences. The last sequence is possibly shorter than the + given size, unless the 2nd parameter is given (like + mySeq?chunk(3, '-')), that is the item used to + make up the size of the last sequence to the given size. + Example:

+ + + +

<#assign seq = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']>
+
+<#list seq?chunk(4) as row>
+  <#list row as cell>${cell} </#list>
+</#list>
+
+<#list seq?chunk(4, '-') as row>
+  <#list row as cell>${cell} </#list>
+</#list>

+ +

The output will be:

+ + + +

+  a b c d
+  e f g h
+  i j
+
+  a b c d
+  e f g h
+  i j - -
+

+ +

This built in is mostly for outputting sequnces in + tabular/columnar format. When used with HTML tables, the 2nd + parameter is often "\xA0" (that is the code of + the no-break space character, also known as "nbsp"), so + the border of the empty TD-s will not be missing.

+ +

The 1st parameter must be a number that is at least 1. If the + number is not integer, it will be silently rounded down to integer + (i.e. both 3.1 and 3.9 will be rounded to 3). The 2nd parameter can + be of any type and value.

+ + + + + +

first

+ + + + +

Returns the first item of the sequence. Thus + value?first is the + same as value[0], + except that, since FreeMarker 2.3.26, + value?first also works + if value doesn't + support getting items with numerical index, but still supports to be + listed (i.e., with FTL collection values).

+ +

If the sequence or collection is empty, the result will be a + missing value (as in + empty?first!'No item was + found').

+ + + + + +

join

+ + + + +

Concatenates the items of a sequence to a single string, with + the given separator. For example:

+ + + +

<#assign colors = ["red", "green", "blue"]>
+${colors?join(", ")}

+ +

will output:

+ + + +

red, green, blue

+ +

Sequence items that are not strings will be converted to + string with the same conversion rules as of + ${...} (except, of + course, no automatic escaping is applied at this stage).

+ +

?join(...) can + have up to 3 parameters:

+ +

+
Separator, required: The string that is inserted between + items
+
+
Empty value, defaults to "" (empty + string): The value used if the sequence contains no + items.
+
+
List ending, defaults to "" (empty + string): The value printed after the last value, if the list + sequence wasn't empty.
+

+ +

So this (where [] means an empty + sequence):

+ + + +

${colors?join(", ", "-")}
+${[]?join(", ", "-")}
+
+${colors?join(", ", "-", ".")}
+${[]?join(", ", "-", ".")}

+ +

will output:

+ + + +

red, green, blue
+-
+
+red, green, blue.
+-

+ +

Sequences coming from Java might contain + null values. Those values will be ignored by this + built-in, exactly like if they were removed from the list.

+ + + + + +

last

+ + + + +

The last subvariable of the sequence. Template processing will + die with error if the sequence is empty.

+ + + + + +

reverse

+ + + + +

The sequence with reversed order.

+ + + + + +

seq_contains

+ + + + +

+ Note: + +

This built-in is available since FreeMarker 2.3.1. It + doesn't exist in 2.3.

+ + +

+ Note: + +

The seq_ prefix is required in the + built-in name to differentiate it from the contains + built-in that searches a substring in a string (since a + variable can be both string and sequence on the same time).

+ + +

Tells if the sequence contains the specified value. It has 1 + parameter, the value to find. Example:

+ + + +

<#assign x = ["red", 16, "blue", "cyan"]>
+"blue": ${x?seq_contains("blue")?string("yes", "no")}
+"yellow": ${x?seq_contains("yellow")?string("yes", "no")}
+16: ${x?seq_contains(16)?string("yes", "no")}
+"16": ${x?seq_contains("16")?string("yes", "no")}

+ +

The output will be:

+ + + +

"blue": yes
+"yellow": no
+16: yes
+"16": no

+ +

To find the value the built-in uses FreeMarker's comparison + rules (as if you was using == + operator), except that comparing two values of different + types or of types for which FreeMarker doesn't support comparison + will not cause error, just will be evaluated as the two values are + not equal. Thus, you can use it only to find scalar values (i.e. + string, number, boolean or date/time values). For other types the + result will be always false.

+ +

For fault tolerance, this built-in also works with + collections.

+ + + + + +

seq_index_of

+ + + + +

+ Note: + +

This built-in is available since FreeMarker 2.3.1. It + doesn't exist in 2.3.

+ + +

+ Note: + +

The seq_ prefix is required in the + built-in name to differentiate it from the index_of + built-in that searches a substring in a string (since a + variable can be both string and sequence on the same time).

+ + +

Returns the index of the first occurrence of a value in the + sequence, or -1 if the sequence doesn't contain + the specified value. The value to find is specified as the first + parameter. For example this template:

+ + + +

<#assign colors = ["red", "green", "blue"]>
+${colors?seq_index_of("blue")}
+${colors?seq_index_of("red")}
+${colors?seq_index_of("purple")}

+ +

will output this:

+ + + +

2
+0
+-1

+ +

The index where the searching is started can be optionally + given as the 2nd parameter. This may be useful if the same item can + occur for multiple times in the same sequence. There is no + restriction on the numerical value of the second parameter: if it is + negative, it has the same effect as if it were zero, and if it is + greater than the length of the sequence, it has the same effect as + if it were equal to the length of the sequence. Decimal values will + be truncated to integers. For example:

+ + + +

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
+No 2nd param: ${names?seq_index_of("Joe")}
+-2: ${names?seq_index_of("Joe", -2)}
+-1: ${names?seq_index_of("Joe", -1)}
+ 0: ${names?seq_index_of("Joe", 0)}
+ 1: ${names?seq_index_of("Joe", 1)}
+ 2: ${names?seq_index_of("Joe", 2)}
+ 3: ${names?seq_index_of("Joe", 3)}
+ 4: ${names?seq_index_of("Joe", 4)}

+ +

will output this:

+ + + +

No 2nd param: 0
+-2: 0
+-1: 0
+ 0: 0
+ 1: 2
+ 2: 2
+ 3: -1
+ 4: -1

+ + + + + +

seq_last_index_of

+ + + + +

+ Note: + +

This built-in is available since FreeMarker 2.3.1. It + doesn't exist in 2.3.

+ + +

+ Note: + +

The seq_ prefix is required in the + built-in name to differentiate it from the last_index_of + built-in that searches a substring in a string (since a + variable can be both string and sequence on the same time).

+ + +

Returns the index of the last occurrence of a value in the + sequence, or -1 if the sequence doesn't contain + the specified value. That is, it is the same as seq_index_of, + just it searches backward starting from the last item of the + sequence. It also supports the optional 2nd parameter that specifies + the index where the searching is started. For example:

+ + + +

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
+No 2nd param: ${names?seq_last_index_of("Joe")}
+-2: ${names?seq_last_index_of("Joe", -2)}
+-1: ${names?seq_last_index_of("Joe", -1)}
+ 0: ${names?seq_last_index_of("Joe", 0)}
+ 1: ${names?seq_last_index_of("Joe", 1)}
+ 2: ${names?seq_last_index_of("Joe", 2)}
+ 3: ${names?seq_last_index_of("Joe", 3)}
+ 4: ${names?seq_last_index_of("Joe", 4)}

+ +

will output this:

+ + + +

No 2nd param: 2
+-2: -1
+-1: -1
+ 0: 0
+ 1: 0
+ 2: 2
+ 3: 2
+ 4: 2

+ + + + + +

size

+ + + + +

The number of sub variables in sequence (as a numerical + value). The highest possible index in sequence s + is s?size - 1 (since the index of the first + subvariable is 0) assuming that the sequence has at least one + subvariable.

+ + + + + +

sort

+ + + + + + +

Returns the sequence sorted in ascending order. (For + descending order use this and then the reverse built + in.) This will work only if all sub variables are strings, or + if all sub variables are numbers, or if all sub variables are date + values (date, time, or date+time), or if all sub variables are + booleans (since 2.3.17). If the sub variables are strings, it uses + locale (language) specific lexical sorting (which is usually not + case sensitive). For example:

+ + + +

<#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort>
+<#list ls as i>${i} </#list>

+ +

will print (with US locale at least):

+ + + +

aardvark Barbara beetroot whale zeppelin

+ + + + + +

sort_by

+ + + + + + +

Returns the sequence of hashes sorted by the given hash + subvariable in ascending order. (For descending order use this and + then the reverse built + in.) The rules are the same as with the sort built-in, + except that the sub variables of the sequence must be hashes, and + you have to give the name of a hash subvariable that will decide the + order. For example:

+ + + +

<#assign ls = [
+  {"name":"whale", "weight":2000},
+  {"name":"Barbara", "weight":53},
+  {"name":"zeppelin", "weight":-200},
+  {"name":"aardvark", "weight":30},
+  {"name":"beetroot", "weight":0.3}
+]>
+Order by name:
+<#list ls?sort_by("name") as i>
+- ${i.name}: ${i.weight}
+</#list>
+
+Order by weight:
+<#list ls?sort_by("weight") as i>
+- ${i.name}: ${i.weight}
+</#list>

+ +

will print (with US locale at least):

+ + + +

Order by name:
+- aardvark: 30
+- Barbara: 53
+- beetroot: 0.3
+- whale: 2000
+- zeppelin: -200
+
+Order by weight:
+- zeppelin: -200
+- beetroot: 0.3
+- aardvark: 30
+- Barbara: 53
+- whale: 2000

+ +

If the subvariable that you want to use for the sorting is on + a deeper level (that is, if it is a subvariable of a subvariable and + so on), then you can use a sequence as parameter, that specifies the + names of the sub variables that lead down to the desired + subvariable. For example:

+ + + +

<#assign members = [
+    {"name": {"first": "Joe", "last": "Smith"}, "age": 40},
+    {"name": {"first": "Fred", "last": "Crooger"}, "age": 35},
+    {"name": {"first": "Amanda", "last": "Fox"}, "age": 25}]>
+Sorted by name.last:
+<#list members?sort_by(['name', 'last']) as m>
+- ${m.name.last}, ${m.name.first}: ${m.age} years old
+</#list>

+ +

will print (with US locale at least):

+ + + +

Sorted by name.last:
+- Crooger, Fred: 35 years old
+- Fox, Amanda: 25 years old
+- Smith, Joe: 40 years old

Previous Next

Built-ins for nodes (for XML)

ancestors

children

node_name

next_sibling

node_namespace

node_type

parent

previous_sibling

root

Overview

Handy stuff

Community

Built-ins for numbers

abs

c (when used with numerical value)

is_infinite

is_nan

lower_abc

round, floor, ceiling

string (when used with a numerical value)

Extended Java decimal format

upper_abc

Overview

Handy stuff

Community

Built-ins for sequences

chunk

first

join

last

reverse

seq_contains

seq_index_of

seq_last_index_of

size

sort

sort_by

Overview

Handy stuff

Community