`lst(X)`

Returns a single, indexed list-value when given one or more values.

Function type

Scalar only

Syntax

lst(X)

Input

Argument	Type	Description
`X`	any	A space- or comma-separated list of scalar values

Return Value

Returns a single list-value that contains a list of values as specified in the X parameter.

If X is N/A, the result is N/A.

Sample Usage

As an example, the following function call:

list="lst('a' 'b' 'c')"

returns a value called list, which itself contains three text values: a, b, and c. The values are indexed in order starting at 1.

List-values can also be created with an implicit syntax, as follows:

list="{1,2,3}"

A more complex example that creates a nested list, incorporating the implicit syntax, is as follows:

list="{{1,2,3} 'foo' {'a',1,'b',2}}"

The values contained in the list-value created above may be accessed as follows:

<let list="{{1,2,3} 'foo' {'a',1,'b',2}}">
    <willbe name="listtest" value="'{@list.2}'"/>
</let>

The value of listtest will be: foo. The same value can be accessed with the alternate syntax of:

<let list="{{1,2,3} 'foo' {'a',1,'b',2}}">
    <willbe name="listtest" value="'{@list[2]}'"/>
</let>

The third element of the list-value contains a list of mixed types. Therefore, the fourth value in the third element of list may be accessed as follows:

<let list="{{1,2,3} 'foo' {'a',1,'b',2}}">
    <willbe name="listtest" value="{@list[3][4]}"/>
</let>

The value of listtest will be: 2.

However, to access the text values contained in the third element, the curly braces must be enclosed in single quotes, as follows:

<let list="{{1,2,3} 'foo' {'a',1,'b',2}}">
    <willbe name="listtest" value="'{@list[3][1]}'"/>
</let>

The value of listtest will be: a.

Note: To ensure errors do not occur when referencing elements of lists with different types, promote all values to text by enclosing the curly braces in single quotes.

Examples

The behavior of how values are treated when accessed from a list-value changes depending on the context of the access. The examples below demonstrate how list-values are initialized and modified.

Note: Since these examples use the <let> clause, they will work on any table.

Most Basic

<let list="{lst(1 2 3)}">
  <willbe name="list_test" value="{@list.1}"/>
</let>

The <willbe> operation in the above <let> clause will be a column with the value 1.

List of Different Types and Nested Lists

This version creates a list that holds values of different types. In addition to text, decimal, and integer values, lists can also hold other lists. Lists can be nested to an arbitrary depth, and values at each depth are accessed with dot-notation corresponding to the depth's value.

For example, below, the list variable is assigned a list with the following values: a, 2, 3.14159, and another list, with values: To be or not to be, 10, and 1.41421. Values in the second list are accessed by first accessing the list-value in the top-level list, at index position 4, and then the index position for the desired value in the nested list:

<let list="{lst('a' 2 3.14159 lst('To be or not to be' 10 1.41421))}">
    <willbe name="nest" value="{@list.4.3}"/>
</let>

The code above will produce a column whose value is 1.41421.

Alternatively, the syntactical shorthand to access the same value can be expressed as:

<let list="{lst('a' 2 3.14159 lst('To be or not to be' 10 1.41421))}">
    <willbe name="nest" value="{@list[4][3]}"/>
</let>

Iterating Over Lists

Since lists are indexed, <foreach> and <for> loops can be used to iterate over all the values, or some of the values, in a list and generate outputs automatically. The following code includes a <foreach> loop that creates a new column for each value in the list using only a single <willbe> operation:

<let list="{lst('you,say,yes' 'i,say,no')}">
    <foreach x="{@list}" tally="@i">
        <willbe name="x{@i}" value="'{@x}'"/>
    </foreach>
</let>

This results in two columns with the following values:

Notice that the <foreach> statement is given a two-element list to iterate over. The first value is: you,say,yes, and the second is, i,say,no. Notice also that lists provide a distinctive advantage over csl_ functions: commas can be inserted in string values without the need to escape them.

Lists for Text Substitution

Lists can also be referenced to insert values during string concatenation and building. However, something interesting happens when doing so. Take the data provided to the list in the last example, but this time, insert text values around the value of x in the <foreach> declaration:

<let list="{lst('you,say,yes' 'i,say,no')}">
    <foreach x="paul: {@list} john" tally="@i">
        <willbe name="x{@i}" value="'{@x}'"/>
    </foreach>
</let>

The code above will create the following results:

Notice in the example above that when text values are placed around the scalar reference to the list variable, the values are actually expanded to comma separated lists and the <foreach> loop iterates over each comma-separated value at its own index position. To give paul and john their own columns in the example above, simply add one comma to the beginning of the first string and another comma to the end of the second string value, as follows:

<let list="{lst(',you,say,yes' 'i,say,no,')}">
    <foreach x="paul: {@list} john" tally_="@i">
        <willbe name="x{@i}" value="'{@x}'"/>
    </foreach>
</let>

The above code now produces the following columns: