Rename List.first() to List.where()

3 files changed, 72 insertions, 73 deletions

diff --git a/api/api.md b/api/api.md
index 15526d43..a0306ae8 100644
--- a/api/api.md
+++ b/api/api.md
@@ -798,30 +798,6 @@ target | `T` | The item to search for.  | -
 = none : Int?
 
 ```
-## List.first
-
-```tomo
-List.first : func(list: [T], predicate: func(item:&T -> Bool) -> Int)
-```
-
-Find the index of the first item that matches a predicate function (if any).
-
-Argument | Type | Description | Default
----------|------|-------------|---------
-list | `[T]` | The list to search through.  | -
-predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item should be returned or `no` if it should not.  | -
-
-**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches.
-
-
-**Example:**
-```tomo
->> [4, 5, 6].find(func(i:&Int): i.is_prime())
-= 5 : Int?
->> [4, 6, 8].find(func(i:&Int): i.is_prime())
-= none : Int?
-
-```
 ## List.from
 
 ```tomo
@@ -1328,6 +1304,30 @@ list | `[T]` | The list to process.  | -
 = {10, 20, 30}
 
 ```
+## List.where
+
+```tomo
+List.where : func(list: [T], predicate: func(item:&T -> Bool) -> Int)
+```
+
+Find the index of the first item that matches a predicate function (if any).
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+list | `[T]` | The list to search through.  | -
+predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item's index should be returned or `no` if it should not.  | -
+
+**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches.
+
+
+**Example:**
+```tomo
+>> [4, 5, 6].where(func(i:&Int): i.is_prime())
+= 5 : Int?
+>> [4, 6, 8].find(func(i:&Int): i.is_prime())
+= none : Int?
+
+```
 
 # Num
 ## Num.1_PI
diff --git a/api/lists.md b/api/lists.md
index 727aa077..32433bee 100644
--- a/api/lists.md
+++ b/api/lists.md
@@ -119,30 +119,6 @@ target | `T` | The item to search for.  | -
 = none : Int?
 
 ```
-## List.first
-
-```tomo
-List.first : func(list: [T], predicate: func(item:&T -> Bool) -> Int)
-```
-
-Find the index of the first item that matches a predicate function (if any).
-
-Argument | Type | Description | Default
----------|------|-------------|---------
-list | `[T]` | The list to search through.  | -
-predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item should be returned or `no` if it should not.  | -
-
-**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches.
-
-
-**Example:**
-```tomo
->> [4, 5, 6].find(func(i:&Int): i.is_prime())
-= 5 : Int?
->> [4, 6, 8].find(func(i:&Int): i.is_prime())
-= none : Int?
-
-```
 ## List.from
 
 ```tomo
@@ -649,3 +625,27 @@ list | `[T]` | The list to process.  | -
 = {10, 20, 30}
 
 ```
+## List.where
+
+```tomo
+List.where : func(list: [T], predicate: func(item:&T -> Bool) -> Int)
+```
+
+Find the index of the first item that matches a predicate function (if any).
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+list | `[T]` | The list to search through.  | -
+predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item's index should be returned or `no` if it should not.  | -
+
+**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches.
+
+
+**Example:**
+```tomo
+>> [4, 5, 6].where(func(i:&Int): i.is_prime())
+= 5 : Int?
+>> [4, 6, 8].find(func(i:&Int): i.is_prime())
+= none : Int?
+
+```
diff --git a/api/lists.yaml b/api/lists.yaml
index 4a7c48c1..595555ac 100644
--- a/api/lists.yaml
+++ b/api/lists.yaml
@@ -108,31 +108,6 @@ List.find:
     >> [10, 20, 30, 40, 50].find(9999)
     = none : Int?
     
-List.first:
-  short: find an index where a predicate matches
-  description: >
-    Find the index of the first item that matches a predicate function (if any).
-  return:
-    type: 'Int'
-    description: >
-      Returns the index of the first item where the predicate is true or `!Int` if no
-      item matches.
-  args:
-    list:
-      type: '[T]'
-      description: >
-        The list to search through.
-    predicate:
-      type: 'func(item:&T -> Bool)'
-      description: >
-        A function that returns `yes` if the item should be returned or
-        `no` if it should not.
-  example: |
-    >> [4, 5, 6].find(func(i:&Int): i.is_prime())
-    = 5 : Int?
-    >> [4, 6, 8].find(func(i:&Int): i.is_prime())
-    = none : Int?
-    
 List.from:
   short: slice an array from a start index
   description: >
@@ -684,3 +659,27 @@ List.unique:
     >> [10, 20, 10, 10, 30].unique()
     = {10, 20, 30}
     
+List.where:
+  short: find an index where a predicate matches
+  description: >
+    Find the index of the first item that matches a predicate function (if any).
+  return:
+    type: 'Int'
+    description: >
+      Returns the index of the first item where the predicate is true or `!Int` if no
+      item matches.
+  args:
+    list:
+      type: '[T]'
+      description: >
+        The list to search through.
+    predicate:
+      type: 'func(item:&T -> Bool)'
+      description: >
+        A function that returns `yes` if the item's index should be returned or
+        `no` if it should not.
+  example: |
+    >> [4, 5, 6].where(func(i:&Int): i.is_prime())
+    = 5 : Int?
+    >> [4, 6, 8].find(func(i:&Int): i.is_prime())
+    = none : Int?