<range></range>

Provided by module: Tags: RXML tags

Extract a range of an array. The part to extract can be specified using positions or by searching for matching elements. Some examples:

Given a variable var.x containing an array like this:

<set variable="var.x" split=",">a,b,c,d,e,f</set>
&var.x;

Array result: ({"a", "b", "c", "d", "e", "f"})

To pick out ranges based on positions:

<range variable="var.x" from="2"/>

Array result: ({"b", "c", "d", "e", "f"})

<range variable="var.x" from="-2"/>

Array result: ({"e", "f"})

<range variable="var.x" from="2" to="-2"/>

Array result: ({"b", "c", "d", "e"})

Given a variable var.x containing an array like this:

<set variable="var.x" type="array">
  <substring separator-whites="">
    From the past to the future via the present.
  </substring>
</set>
&var.x;

Array result: ({"From", "the", "past", "to", "the", "future", "via", "the", "present."})

To pick out ranges based on matching elements:

<range variable="var.x" after="the"/>

Array result: ({"past", "to", "the", "future", "via", "the", "present."})

<range variable="var.x" after="the" from="2"/>

Array result: ({"future", "via", "the", "present."})

<range variable="var.x" after="the" from="-1"/>

Array result: ({"present."})

<range variable="var.x" after="to" before="the" to="3"/>

Array result: ({"the", "future", "via"})

The "from" and "to" attributes specifies positions in the input array. What is considered a position depends on other attributes:

If the "after" attribute is given then "from" counts the occurrences of that element.

Similarly, if the "before" attribute is given then "to" counts the occurrences of that element.

If neither of the above apply then positions are counted directly by index.

Positive positions count from the start of the input array, beginning with 1. Negative positions count from the end.

It is not an error if a position count goes past the array limit (in either direction). The position gets capped by the start or end if that happens. E.g. if a "from" position counts from the beginning and goes past the end then the result is an empty array, and if it counts from the end and goes past the beginning then the result starts at the beginning of the input array.

It is also not an error if the start position ends up after the end position. In that case the result is simply an empty array.

If neither "from", nor "after" is specified then the returned range starts at the beginning of the input array. If neither "to" nor "before" is specified then the returned range ends at the end of the input array.

If "join" is given then the result is returned as a string, otherwise it is an array.

Attributes

variable: The variable to get the input array from. If this is left out then the array is taken from the content, which is evaluated in an array context.
from="integer": The position of the start of the range to return.
to="integer": The position of the end of the range to return.
after: The range to return begins after the first occurrence of this element. Together with the "from" attribute, it specifies the nth occurrence.
before: The range to return ends before the first occurrence of this element. Together with the "to" attribute, it specifies the nth occurrence.
join="string": Join together the elements of the range to a string, using the value of this attribute as delimiter between the elements.