Merge pull request #712 from vim-jp/revisit-data-list-docs

Data.List: Overhaul docs to be up-to-date

Author: ujihisa

doc/vital/Data/List.txt

@@ -20,28 +20,34 @@ manipulate |List|.
 	let s:V = vital#{plugin-name}#new()
 	let s:L = s:V.import("Data.List")
 
-	let s = []
-	echo s:L.push(s, 1)
-	" [1]
-	echo s:L.push(s, 2)
-	" [1, 2]
-	echo s:L.push(s, 3)
-	" [1, 2, 3]
-	echo s
+	echo s:L.cons(1, [2, 3])
 	" [1, 2, 3]
-	echo s:L.pop(s)
-	" 3
-	echo s:L.pop(s)
-	" 2
-	echo s
-	" [1]
+
+	echo s:L.conj([2, 3], 1)
+	" [2, 3, 1]
+
+	echo s:L.foldl('v:memo + v:val', 0, range(1, 10))
+	" 55 := 1+2+3+4+5+6+7+8+9+10
+
+	echo s:L.count({ x -> x % 2 == 0 }, [1, 2, 3, 4, 5])
+	"=> 2
+
+	echo s:L.intersect(['a', 'b', 'c'], ['b', 'c'])
+	" ['b', 'c']
+
+	s:L.new(3, { i -> i * 2 })
+	"=> [0, 2, 4]
+
+	echo s:L.permutations([1, 2, 3])
+	" [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]]
 <
 
 ==============================================================================
 TERM					*Vital.Data.List-term*
 
 {function}				*Vital.Data.List-term-function*
-	|Funcref| or |String|(as expression)
+	|Funcref| or |String|(as expression). We recommend you just to use
+	Vim's |expr-lambda| notation to pass this.
 
 ==============================================================================
 INTERFACE				*Vital.Data.List-interface*
@@ -51,6 +57,9 @@ FUNCTIONS				*Vital.Data.List-functions*
 new({size}, {f})			*Vital.Data.List.new()*
 	Creates a new |List| with given arguments. The given |Funcref| {f} is
 	called for {size} times with index.
+
+	Note that's vital Data.List does not provide a new wrapper list
+	dictionary or whatever. It simply uses Vim's |Lists|.
 >
 	s:L.new(3, { i -> i * 2 })
 	"=> [0, 2, 4]
@@ -109,11 +118,11 @@ cons({val}, {list})			*Vital.Data.List.cons()*
 	Non-destructive. This does not modify {list}.
 
 uncons({list})			*Vital.Data.List.uncons()*
-	Returns a pair of a head element and tail elements. {list} must not be
-	empty list.
+	Returns a pair of a head element and tail elements.
+	{list} must be nonempty, otherwise it throws an error.
 >
-	echo s:L.uncons([1,2,3,4,5])
-	" [1, [2,3,4,5]]
+	echo s:L.uncons([1, 2, 3, 4, 5])
+	" [1, [2, 3, 4, 5]]
 	echo s:L.uncons([1])
 	" [1, []]
 	echo s:L.uncons([])
@@ -140,6 +149,9 @@ conj({list}, {val})			*Vital.Data.List.conj()*
 	Non-destructive. This does not modify {list}.
 
 map({list}, {function})			*Vital.Data.List.map()*
+	Use this if you'd like to keep the original list. Vim's built-in
+	|map()| destroys the given {list}, but this doesn't.
+
 	Generalized map(). The followings are different of |map()|:
 	* Don't require taking the index as the argument
 	   (See the section of 'If {expr2} is a Funcref...' in |map()|)
@@ -163,6 +175,9 @@ map({list}, {function})			*Vital.Data.List.map()*
 
 
 filter({list}, {function})		*Vital.Data.List.filter()*
+	Use this if you'd like to keep the original list. Vim's built-in
+	|filter()| destroys the given {list}, but this doesn't.
+
 	Generalized filter(). The followings are different of |filter()|:
 	* Don't require taking the index as the argument
 	   (See the section of 'If {expr2} is a Funcref...' in |filter()|)
@@ -300,7 +315,9 @@ max_by({list}, {function})			*Vital.Data.List.max_by()*
 	Returns 0 if {list} is empty.
 	"v:val" can be used in {function} if {function} is string expression.
 >
-	echo s:L.max_by(['pineapple','orange','banana','apple'], 'len(v:val)')
+	echo s:L.max_by(
+	\ ['pineapple', 'orange', 'banana', 'apple'],
+	\ 'len(v:val)')
 	" pineapple
 	echo s:L.max_by([20, -50, -15, 30], function('abs'))
 	" -50
@@ -313,7 +330,9 @@ min_by({list}, {function})			*Vital.Data.List.min_by()*
 	Returns 0 if {list} is empty.
 	"v:val" can be used in {function} if {function} is string expression.
 >
-	echo s:L.min_by(['pineapple','orange','banana','apple'], 'len(v:val)')
+	echo s:L.min_by(
+	\ ['pineapple', 'orange', 'banana', 'apple'],
+	\ 'len(v:val)')
 	" apple
 	echo s:L.min_by([20, -50, -15, 30], function('abs'))
 	" -15
@@ -371,7 +390,7 @@ break({function}, {list})			*Vital.Data.List.break()*
 	Returns a list of two lists where concatenation of them is
 	equal to {list}, all the items of the first list do not satisfy
 	{function} and the first item of the second list satisfies {function}.
-	If {function} is the string expression,|v:val| has the value of the
+	If {function} is the string expression, |v:val| has the value of the
 	current item.
 >
 	function! Is5(x) abort
@@ -399,7 +418,7 @@ break({function}, {list})			*Vital.Data.List.break()*
 take_while({function}, {list})		*Vital.Data.List.take_while()*
 	Returns a list which is from the beginning of the given {list} to an
 	element that all of them satisfies given expression {function}.
-	If {function} is the string expression,|v:val| has the value of the
+	If {function} is the string expression, |v:val| has the value of the
 	current item.
 >
 	function! Under5(x) abort
@@ -426,7 +445,7 @@ take_while({function}, {list})		*Vital.Data.List.take_while()*
 
 drop_while({function}, {list})		*Vital.Data.List.drop_while()*
 	Returns the suffix remaining after |Vital.Data.List.take_while()|.
-	If {function} is the string expression,|v:val| has the value of the
+	If {function} is the string expression, |v:val| has the value of the
 	current item.
 >
 	function! Under5(x) abort