patch 9.0.0196: finding value in list may require a for loopv9.0.0196

Problem:    Finding value in list may require a for loop.
Solution:   Add indexof(). (Yegappan Lakshmanan, closes #10903)

2 files changed, 51 insertions, 3 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index a65f60d413..3c0f143c51 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -291,6 +291,8 @@ iconv({expr}, {from}, {to})	String	convert encoding of {expr}
 indent({lnum})			Number	indent of line {lnum}
 index({object}, {expr} [, {start} [, {ic}]])
 				Number	index in {object} where {expr} appears
+indexof({object}, {expr} [, {opts}]])
+				Number	index in {object} where {expr} is true
 input({prompt} [, {text} [, {completion}]])
 				String	get input from the user
 inputdialog({prompt} [, {text} [, {cancelreturn}]])
@@ -4730,19 +4732,25 @@ indent({lnum})	The result is a Number, which is indent of line {lnum} in the
 			GetLnum()->indent()
 
 index({object}, {expr} [, {start} [, {ic}]])			*index()*
+		Find {expr} in {object} and return its index.  See
+		|filterof()| for using a lambda to select the item.
+
 		If {object} is a |List| return the lowest index where the item
 		has a value equal to {expr}.  There is no automatic
 		conversion, so the String "4" is different from the Number 4.
 		And the number 4 is different from the Float 4.0.  The value
-		of 'ignorecase' is not used here, case always matters.
+		of 'ignorecase' is not used here, case matters as indicated by
+		the {ic} argument.
 
 		If {object} is |Blob| return the lowest index where the byte
 		value is equal to {expr}.
 
 		If {start} is given then start looking at the item with index
 		{start} (may be negative for an item relative to the end).
+
 		When {ic} is given and it is |TRUE|, ignore case.  Otherwise
 		case must match.
+
 		-1 is returned when {expr} is not found in {object}.
 		Example: >
 			:let idx = index(words, "the")
@@ -4751,6 +4759,44 @@ index({object}, {expr} [, {start} [, {ic}]])			*index()*
 <		Can also be used as a |method|: >
 			GetObject()->index(what)
 
+indexof({object}, {expr} [, {opt}])			*indexof()*
+		{object} must be a |List| or a |Blob|.
+		If {object} is a |List|, evaluate {expr} for each item in the
+		List until the expression returns v:true and return the index
+		of this item.
+
+		If {object} is a |Blob| evaluate {expr} for each byte in the
+		Blob until the expression returns v:true and return the index
+		of this byte.
+
+		{expr} must be a |string| or |Funcref|.
+
+		If {expr} is a |string|: If {object} is a |List|, inside
+		{expr} |v:key| has the index of the current List item and
+		|v:val| has the value of the item.  If {object} is a |Blob|,
+		inside {expr} |v:key| has the index of the current byte and
+		|v:val| has the byte value.
+
+		If {expr} is a |Funcref| it must take two arguments:
+			1. the key or the index of the current item.
+			2. the value of the current item.
+		The function must return |TRUE| if the item is found and the
+		search should stop.
+
+		The optional argument {opt} is a Dict and supports the
+		following items:
+		    start	start evaluating {expr} at the item with index
+				{start} (may be negative for an item relative
+				to the end).
+		Returns -1 when {expr} evaluates to v:false for all the items.
+		Example: >
+			:let l = [#{n: 10}, #{n: 20}, #{n: 30]]
+			:let idx = indexof(l, "v:val.n == 20")
+			:let idx = indexof(l, {i, v -> v.n == 30})
+
+<		Can also be used as a |method|: >
+			mylist->indexof(expr)
+
 input({prompt} [, {text} [, {completion}]])		*input()*
 		The result is a String, which is whatever the user typed on
 		the command-line.  The {prompt} argument is either a prompt
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index c1f74d6241..1938e35460 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -792,14 +792,16 @@ List manipulation:					*list-functions*
 	reduce()		reduce a List to a value
 	slice()			take a slice of a List
 	sort()			sort a List
-	reverse()		reverse the order of a List
+	reverse()		reverse the order of a List or Blob
 	uniq()			remove copies of repeated adjacent items
 	split()			split a String into a List
 	join()			join List items into a String
 	range()			return a List with a sequence of numbers
 	string()		String representation of a List
 	call()			call a function with List as arguments
-	index()			index of a value in a List
+	index()			index of a value in a List or Blob
+	indexof()		index in a List or Blob where an expression
+				evaluates to true 
 	max()			maximum value in a List
 	min()			minimum value in a List
 	count()			count number of times a value appears in a List