From 2207a6042e784274ff6b5621445da72690fff8c6 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Mon, 22 Oct 2018 18:26:07 -0700
Subject: [PATCH] Add documentation for list functions

---
 .../documentation/functions/lists.html.md.erb | 220 ++++++++++++++++++
 source/documentation/values/lists.html.md.erb |   2 +
 2 files changed, 222 insertions(+)
 create mode 100644 source/documentation/functions/lists.html.md.erb

diff --git a/source/documentation/functions/lists.html.md.erb b/source/documentation/functions/lists.html.md.erb
new file mode 100644
index 0000000..b9587ed
--- /dev/null
+++ b/source/documentation/functions/lists.html.md.erb
@@ -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 %>
diff --git a/source/documentation/values/lists.html.md.erb b/source/documentation/values/lists.html.md.erb
index 976cdd8..041eb7d 100644
--- a/source/documentation/values/lists.html.md.erb
+++ b/source/documentation/values/lists.html.md.erb
@@ -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