Lists

FISH supports one-dimensional dynamic sized value based lists.

Lists are one-dimensional arrays of general FISH values. They differ from matrices in that each index can hold any valid FISH type (including another list). They differ from arrays in that they are passed by value, and they can only be of one dimension. They differ from maps in that they can be indexed only by consecutive integers starting at 1, but such indexing is more efficient.

While any iterable type can be the argument of a splitting operation (see Splitting), the return value of a split call will always be a list.

You can iterate through all the elements of a list using the loop foreach statement.

Lists are a handy way to pass and return multiple values using one symbol. Arbitrarily complex data structures can be created by embedding lists within lists.

Components of a list can be accessed using parentheses (). A single index can be used to get or set a single element of the list. As a special case, the string arguments ‘start’ and ‘end’ can be used (single argument only) to prepend or append to a list. The abbreviations ‘s’ and ‘e’ can be used as well.

Two indices can be used to get a sub-range of the list, or to update or resize a sub-range of a list on assignment. The return value is always a list (although it may be an empty list), and values assigned must be a list. The list assigned to a sub-range does not have to be the same length, the previous elements are replaced with the new elements and this may make the list longer or shorter. Using a two argument range for assignment, and assigning an empty list, removes that range from the list.

List can also be indexed using another list as a single argument – this is only available on get, it cannot currently be used for assignment. In this case, the list used as the argument must be composed entirely of positive integers (indices) or boolean values. In the case of boolean values, the return value is a list composed only of those elements that had true in the argument list. In the case of index values, the return value is a list of the elements in the original list at those indices.

The following example illustrates accessing list components using parentheses:

Binary and unary operators function differently on list types. Instead of operating on the lists themselves, the operators apply automatically to each element in the respective lists. If a list and a non-list type are involved in a binary operation, then the non-list type and operator is applied to each element of the list separately, and the result is a new list. If both sides are lists, then the operator is applied to each element of both lists separately in order, and the result is a third list. These operations may happen on multiple threads, if possible.

The access operator -> also behaves differently when applied to lists. The retrieval/assignment is done on each element individually, and the result is returned as another list. If any element in the list does not support that accessor, then an error will occur. This applies to any type that is compatible with accessors - which at this time includes vectors, tensors, and structures. The following is a brief example of that syntax:

List types are created using the list or list.create library functions. A sequence of values can be created using the list.sequence function. A sequential range of numbers (from a start to an end using a given interval) can be created using the list.range function.

A number of additional methods, detailed in the List Utilities section, are available for lists.

Lists are an iterable type. This means you can use it as the target of a loop foreach statement (see Loop ForEach and can be split (see Splitting). Each entry of the list is iterated through in order.

As with most aggregate types, when the value is listed it will simply indicate that it is of type List and the the list size. To see the contents of the list use the fish list contents command.

Appending to a list

There are four different methods of appending to a list.

The first is to use the fish.append function, which returns a list with one or more values added to the end of the old one.

Note that if the value appended is itself another list, the new list returned will have one new value that is a list.

You can also append a single value to a list by using the string ‘end’ or ‘e’ argument on assignment. This method has a performance advantage in that a copy of the list is not (necessarily) made.

You can append the contents of another list (or any iterable type) to the end of a list by using the list.extend function.

This can also be done using two ‘e’ arguments to indicate a ranged insertion at the end:

Prepending to a list

Similarly, you can prepend a single value to a list using the list.prepend function.

You can also use the ‘s’ argument to prepend a value:

Lastly you can use two ‘s’ arguments to prepend a range of values:

Inserting into a list

You can insert one or more values into a list using the list.insert function.

You can also use two arguments to do a ranged insert. If the second argument is less than the first then the values appear inserted before the first. This is inserting into a null range.

One way to think of ranged (two argument) assignments to a list is the the values assigned fall from the start of the first argument to the end of the second.

Finally you can insert all elements in another list (or any iterable type) by using the list.insert.list function: