List Element Operator (FPScript)
Takes an element or several elements from a list or selects a list element to which a new value is to be assigned. The operator can also be used to access a component of an aggregate data structure.
Syntax
Expression.[Index]
or
Expression.[from, to]
or
Expression.ElementName
The syntax of the list element operator consists of the following elements:
Element |
Description |
|---|---|
Expression |
An expression, which describes a variable, formula or data set, calls a function or selects an element from a list, or any expression in brackets. |
Index |
The null-based index of the list element or a string with the name of the list element. Negative indices are allowed and count starting from the end of the list. If Index is specified as a scalar value, the relevant list element is passed. If Index is specified as a data series or as a scalar string with the wildcard character ? or *, a partial list is created. |
From |
Specifies the index of the first list element of a range to index. This must be a real integral scalar value or of the Empty data type. |
to |
Specifies the index of the last list element of a range to index. This must be a real integral scalar value or of the Empty data type. |
ElementName |
The name of the list element. |
Remarks
With a scalar index, the operator also allowed on the left side of an assignment operation and then selects the list element to which the assignment is to take place.
You can concatenate the operator to access elements from nested lists.
When accessing a list element using the element name, it first searches in the element names of the list itself. If no element names are assigned, it searches in the header information assigned to the individual list elements.
If you access a formula that contains a list, thus using the format Formula.ElementName of the operator, then note that the formula's properties that can be accessed in the same way take precedence over list elements with the same name. Use the syntax Formula.["ElementName"] of the operator.
When accessing a component of an aggregate data structure, the numeric index indexes COMPONENT_Y = 0 the Y component, the index COMPONENT_X = 1 indexes the X component and the index COMPONENT_Z = 2 indexes the Z component. Alternatively, you can also use the strings "Y", "X" and "Z". It does not matter if the string is upper or lower case. You should use this form of access only if you are able to determine the component to be accessed first at runtime. Otherwise, use the Component Operator.
The indices are counted starting from zero. Negative indices count starting from the end, i.e. Index -1 corresponds to the last element, -2 for the second to last element, and so forth.
If a floating point value is specified for one of the arguments Index, from or to its fractional digits will be ignored. A void floating point value is interpreted as 0. If you set from or to as a value with the Empty data type, it corresponds to the first or last element in the list.
If Index is specified as a scalar string and it contains the wildcard * and/or ? character, the patterns are compared. The * character in this case stands for any string of characters and can also be empty. ? stands for any character. All list elements with element names that fit the pattern are copied to the results list without changing their order in the list. Processing is not case sensitive.
If Index is a quantity, then it has to have the SI dimension 1 and it will be transformed to the unit 1 before indexing.
Available in
FlexPro View, Basic, Professional, Developer Suite
Examples
For the following examples, it is assumed that a List formula exists which contains the following list: [<Element1> 1, <Name> "2nd Element", 3 m, 4 cm].
List.[1n] |
Returns "2nd Element". |
List.[-2n] |
Returns 3 m. |
List.Element1 |
Returns 1. |
List.Name |
Returns "List" and not "2nd Element", since Name is an object property of the formula. |
List.["Name"] |
Returns "2nd Element". |
Var = List Var.[2n] = [1, 2] |
Assigns a list with two elements to the third element of the list in Var. |
Var.[2n].[1n] |
Returns 2. |
signal.["y"] or signal.[0n] or signal.[COMPONENT_Y] |
Returns the Y component of the signal. |
List.[1 Pi] |
Returns 4 cm, since the unit Pi has the SI dimension 1 and 1 Pi transformed to the unit 1 results in the value 3.1415927. |
List.[1, 2] |
Returns a partial list with the 2nd and 3rd element. |
List.[{-1, 0}] |
Returns the last and first list element. |
List.["Current*"] |
Returns all list elements whose names start with "Current". |