Sass - List Functions
The Sass list functions allow you to interrogate, manipulate and combine lists in expected ways. The lists can be specified using any of the options described in the SassScript chapter, but you'll need to surround them with parentheses to make it clear that the list is a single argument.
Sass lists are immutable (they cannot be changed). So all of the list functions that return a list, join() for example, return a new list. They do not alter the original list.
Like the string functions, the only tricky thing about Sass lists are that they are one-based rather than zero-based. (See the nth() function in the table for an example).
| Function | Description | Examples | Result |
|---|---|---|---|
| length($list) | Returns the number of elements in a list | length(1 2 3) | 3 |
| nth($list, $n) | Returns the nth element in a list | nth(1 2 3, 2) | 2 |
| set-nth($list, $n, $value) | Sets the nth element in a list to the value supplied | set-nth(1 2 3, 2, 5) | (1 5 3) |
| join($list1, $list2, [$separator]) | Appends $list2 to the end of $list1. The $separator argument can contain the values comma, space or auto. The auto value, which is the default, will use the separator in the first list. | join(1 2 3, 4 5 6) | (1 2 3 4 5 6) |
| join((1, 2, 3), (4 5 6), auto) | (1, 2, 3, 4, 5, 6) | ||
| join((1, 2, 3), (4 5 6), space) | (1 2 3 4 5 6) | ||
| append($list1, $val, [$separator]) | Appends a single value to the end of a list. If a $separator argument is provided (the default is auto), the entire list the function returns will use that separator | append((1, 2, 3), 4) | (1, 2, 3, 4) |
| append((1, 2, 3), 4, space) | (1 2 3 4) | ||
| zip($lists) | Interleaves the values of the lists provided into a single multi-dimensional list | zip((red, green, blue), (10px, 15px, 5px)) | ((#ff0000 10px), (#00ff00 15px), (#0000ff 5px)) |
| index($list, $value) | Returns the element at the index position specified by $value | index((1 2 3), 2) | 2 |
| list-separator($list) | Returns the name of the separator used in a list as a string | list-separator((1, 2, 3)) | "comma" |
| list-separator((1 2 3)) | "space |
