mirror of
https://github.com/danog/sass-site.git
synced 2024-11-27 04:24:50 +01:00
Add documentation for list functions
This commit is contained in:
Natalie Weizenbaum
parent
6dc51b92e7
commit
2207a6042e
220
source/documentation/functions/lists.html.md.erb
Normal file
220
source/documentation/functions/lists.html.md.erb
Normal file
@ -0,0 +1,220 @@
|
||||
---
|
||||
title: List Functions
|
||||
---
|
||||
|
||||
<% fun_fact do %>
|
||||
In Sass, every [map][] counts as a list that contains a two-element list for
|
||||
each key/value pair. For example, `(1: 2, 3: 4)` counts as `(1 2, 3 4)`. So all
|
||||
these functions work for maps as well!
|
||||
|
||||
[map]: ../values/maps
|
||||
|
||||
Individual values also count as lists. All these functions treat `1px` as a list
|
||||
that contains the value `1px`.
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'append($list, $val, $separator: auto)', returns: 'list' do %>
|
||||
Returns a copy of `$list` with `$val` added to the end.
|
||||
|
||||
If `$separator` is `comma`, the returned list is comma-separted. If it's
|
||||
`space`, the returned list is space-separated. If it's `auto` (the default), the
|
||||
returned list will use the same separator as `$list` (or `space` if `$list`
|
||||
doesn't have a separator). Other values aren't allowed.
|
||||
|
||||
[separator]: ../values/lists
|
||||
|
||||
Note that unlike [`join()`](#join), if `$val` is a list it's nested within the
|
||||
returned list rather than having all its elements added to the returned list.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug append(10px 20px, 30px); // 10px 20px 30px
|
||||
@debug append((blue, red), green); // blue, red, green
|
||||
@debug append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
|
||||
@debug append(10px, 20px, $separator: comma); // 10px, 20px
|
||||
@debug append((blue, red), green, $separator: space); // blue red green
|
||||
===
|
||||
@debug append(10px 20px, 30px) // 10px 20px 30px
|
||||
@debug append((blue, red), green) // blue, red, green
|
||||
@debug append(10px 20px, 30px 40px) // 10px 20px (30px 40px)
|
||||
@debug append(10px, 20px, $separator: comma) // 10px, 20px
|
||||
@debug append((blue, red), green, $separator: space) // blue red green
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'index($list, $value)', returns: 'number | null' do %>
|
||||
Returns the [index][] of `$value` in `$list`.
|
||||
|
||||
[index]: ../values/lists#indexes
|
||||
|
||||
If `$value` doesn't appear in `$list`, this returns [`null`][]. If `$value`
|
||||
appears multiple times in `$list`, this returns the index of its first
|
||||
appearance.
|
||||
|
||||
[index]: ../values/null
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug index(1px solid red, 1px); // 1
|
||||
@debug index(1px solid red, solid); // 2
|
||||
@debug index(1px solid red, dashed); // null
|
||||
===
|
||||
@debug index(1px solid red, 1px) // 1
|
||||
@debug index(1px solid red, solid) // 2
|
||||
@debug index(1px solid red, dashed) // null
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'is-bracketed($list)', returns: 'boolean' do %>
|
||||
Returns whether `$list` has square brackets.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug is-bracketed(1px 2px 3px); // false
|
||||
@debug is-bracketed([1px, 2px, 3px]); // true
|
||||
===
|
||||
@debug is-bracketed(1px 2px 3px) // false
|
||||
@debug is-bracketed([1px, 2px, 3px]) // true
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'join($list1, $list2, $separator: auto, $bracketed: auto)', returns: 'list' do %>
|
||||
Returns a new list containing the elements of `$list1` followed by the elements
|
||||
of `$list2`.
|
||||
|
||||
<% heads_up do %>
|
||||
Because individual values count as single-element lists, it's possible to use
|
||||
`join()` to add a value to the end of a list. However, *this is not
|
||||
recommended*, since if that value is a list it will be concatenated, which is
|
||||
probably not what you're expecting.
|
||||
|
||||
Use [`append()`](#append) instead to add a single value to a list. Only use
|
||||
`join()` to combine two lists together into one.
|
||||
<% end %>
|
||||
|
||||
If `$separator` is `comma`, the returned list is comma-separted. If it's
|
||||
`space`, the returned list is space-separated. If it's `auto` (the default), the
|
||||
returned list will use the same separator as `$list1` if it has a separator, or
|
||||
else `$list2` if it has a separator, or else `space`. Other values aren't
|
||||
allowed.
|
||||
|
||||
If `$bracketed` is `true`, the returned list has square brackets. If it's
|
||||
`false`, the returned list has no brackets. If it's `auto` (the default), the
|
||||
returned list will be bracketed if `$list1` is. Other values aren't allowed.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug join(10px 20px, 30px 40px); // 10px 20px 30px 40px
|
||||
@debug join((blue, red), (#abc, #def)); // blue, red, #abc, #def
|
||||
@debug join(10px, 20px); // 10px 20px
|
||||
@debug join(10px, 20px, $separator: comma); // 10px, 20px
|
||||
@debug join((blue, red), (#abc, #def), $separator: space); // blue red #abc #def
|
||||
@debug join([10px], 20px); // [10px 20px]
|
||||
@debug join(10px, 20px, $bracketed: true); // [10px 20px]
|
||||
===
|
||||
@debug join(10px 20px, 30px 40px) // 10px 20px 30px 40px
|
||||
@debug join((blue, red), (#abc, #def)) // blue, red, #abc, #def
|
||||
@debug join(10px, 20px) // 10px 20px
|
||||
@debug join(10px, 20px, comma) // 10px, 20px
|
||||
@debug join((blue, red), (#abc, #def), space) // blue red #abc #def
|
||||
@debug join([10px], 20px) // [10px 20px]
|
||||
@debug join(10px, 20px, $bracketed: true) // [10px 20px]
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'length($list)', returns: 'number' do %>
|
||||
Returns the length of `$list`.
|
||||
|
||||
This can also return the number of pairs in a map.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug length(10px); // 1
|
||||
@debug length(10px 20px 30px); // 3
|
||||
@debug length((width: 10px, height: 20px)); // 2
|
||||
===
|
||||
@debug length(10px) // 1
|
||||
@debug length(10px 20px 30px) // 3
|
||||
@debug length((width: 10px, height: 20px)) // 2
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'list-separator($list)', returns: 'unquoted string' do %>
|
||||
Returns the name of the separator used by `$list`, either `space` or `comma`.
|
||||
|
||||
If `$list` doesn't have a separator, returns `space`.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug list-separator(1px 2px 3px); // space
|
||||
@debug list-separator(1px, 2px, 3px); // comma
|
||||
@debug list-separator('Helvetica'); // space
|
||||
@debug list-separator(()); // space
|
||||
===
|
||||
@debug list-separator(1px 2px 3px) // space
|
||||
@debug list-separator(1px, 2px, 3px) // comma
|
||||
@debug list-separator('Helvetica') // space
|
||||
@debug list-separator(()) // space
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'nth($list, $n)' do %>
|
||||
Returns the element of `$list` at [index][] `$n`.
|
||||
|
||||
[index]: ../values/lists#indexes
|
||||
|
||||
If `$n` is negative, it counts from the end of `$list`. Throws an error if there
|
||||
is no element at index `$n`.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug nth(10px 20px 30px, 1); // 10px
|
||||
@debug nth(10px 20px 30px, -1); // 30px
|
||||
@debug nth((Helvetica, Arial, sans-serif), 3); // sans-serif
|
||||
===
|
||||
@debug nth(10px 20px 30px, 1) // 10px
|
||||
@debug nth(10px 20px 30px, -1) // 30px
|
||||
@debug nth((Helvetica, Arial, sans-serif), 3) // sans-serif
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'set-nth($list, $n, $value)', returns: 'list' do %>
|
||||
Returns a copy of `$list` with the element at [index][] `$n` replaced with
|
||||
`$value`.
|
||||
|
||||
[index]: ../values/lists#indexes
|
||||
|
||||
If `$n` is negative, it counts from the end of `$list`. Throws an error if there
|
||||
is no existing element at index `$n`.
|
||||
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
|
||||
@debug set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
|
||||
@debug set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto
|
||||
===
|
||||
@debug set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
|
||||
@debug set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
|
||||
@debug set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto
|
||||
<% end %>
|
||||
<% end %>
|
||||
|
||||
|
||||
<% function 'zip($lists...)', returns: 'list' do %>
|
||||
Combines every list in `$lists` into a single list of sub-lists.
|
||||
|
||||
Each element in the returned list contains all the elements at that position in
|
||||
`$lists`. The returned list is as long as the shortest list in `$lists`.
|
||||
|
||||
The returned list is always comma-separated and the sub-lists are always
|
||||
space-separated.
|
||||
|
||||
<% example(autogen_css: false) do %>
|
||||
@debug zip(10px 50px 100px, short mid long); // 10px short, 50px mid, 100px long
|
||||
@debug zip(10px 50px 100px, short mid); // 10px short, 50px mid
|
||||
===
|
||||
@debug zip(10px 50px 100px, short mid long) // 10px short, 50px mid, 100px long
|
||||
@debug zip(10px 50px 100px, short mid) // 10px short, 50px mid
|
||||
<% end %>
|
||||
<% end %>
|
||||
@ -39,6 +39,8 @@ more maintainable.
|
||||
|
||||
[functions]: ../functions/lists
|
||||
|
||||
### Indexes
|
||||
|
||||
Many of these functions take or return numbers, called *indexes*, that refer to
|
||||
the elements in a list. The index 1 indicates the first element of the list.
|
||||
Note that this is different than many programming languages where indexes start
|
||||
|
||||
Loading…
Reference in New Issue
Block a user