From 5feecff9d93522002c74a1423d138c2aa8bc150d Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Tue, 3 Sep 2024 03:53:36 -0400
Subject: Deprecate `Where` and change channel API to use a boolean `front`
 value

---
 docs/channels.md | 20 ++++++++------------
 docs/text.md     | 27 +--------------------------
 2 files changed, 9 insertions(+), 38 deletions(-)

(limited to 'docs')

diff --git a/docs/channels.md b/docs/channels.md
index 88cb46ff..8763f11d 100644
--- a/docs/channels.md
+++ b/docs/channels.md
@@ -31,15 +31,14 @@ Adds an item to the channel.
 
 **Usage:**  
 ```markdown
-give(channel:|T|, item: T, where: Where = Where.End) -> Void
+give(channel:|T|, item: T, front: Bool = no) -> Void
 ```
 
 **Parameters:**
 
 - `channel`: The channel to which the item will be added.
 - `item`: The item to add to the channel.
-- `where`: Where to put the item (at the `Start` or `End` of the queue).
-  `Anywhere` defaults to `End`.
+- `front`: Whether to put the item at the front of the channel (as opposed to the back).
 
 **Returns:**  
 Nothing.
@@ -58,15 +57,14 @@ Adds multiple items to the channel.
 
 **Usage:**  
 ```markdown
-give_all(channel:|T|, items: [T], where: Where = Where.End) -> Void
+give_all(channel:|T|, items: [T], front: Bool = no) -> Void
 ```
 
 **Parameters:**
 
 - `channel`: The channel to which the items will be added.
 - `items`: The array of items to add to the channel.
-- `where`: Where to put the items (at the `Start` or `End` of the queue).
-  `Anywhere` defaults to `End`.
+- `front`: Whether to put the item at the front of the channel (as opposed to the back).
 
 **Returns:**  
 Nothing.
@@ -85,14 +83,13 @@ Removes and returns an item from the channel. If the channel is empty, it waits
 
 **Usage:**  
 ```markdown
-get(channel:|T|, where: Where = Where.Start) -> T
+get(channel:|T|, front: Bool = yes) -> T
 ```
 
 **Parameters:**
 
 - `channel`: The channel from which to remove an item.
-- `where`: Where to get the item from (from the `Start` or `End` of the queue).
-  `Anywhere` defaults to `Start`.
+- `front`: Whether to put the item at the front of the channel (as opposed to the back).
 
 **Returns:**  
 The item removed from the channel.
@@ -113,14 +110,13 @@ it. If the channel is empty, it waits until an item is available.
 
 **Usage:**  
 ```markdown
-peek(channel:|T|, where: Where = Where.Start) -> T
+peek(channel:|T|, front: Bool = yes) -> T
 ```
 
 **Parameters:**
 
 - `channel`: The channel from which to remove an item.
-- `where`: Which end of the channel to peek from (the `Start` or `End`).
-  `Anywhere` defaults to `Start`.
+- `front`: Whether to put the item at the front of the channel (as opposed to the back).
 
 **Returns:**  
 The item removed from the channel.
diff --git a/docs/text.md b/docs/text.md
index ca8c875d..5d399edd 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -270,7 +270,7 @@ Text.find(pattern:Text, start=1, length=!&Int64?)->Int
 Text.find_all(pattern:Text)->[Text]
 Text.split(pattern:Text)->[Text]
 Text.replace(pattern:Text, replacement:Text)->[Text]
-Text.has(pattern:Text, where=Where.Anywhere)->Bool
+Text.has(pattern:Text)->Bool
 ```
 
 See [Text Functions](#Text-Functions) for the full API documentation.
@@ -345,31 +345,6 @@ many repetitions you want by putting a number or range of numbers first using
 [..0-1 question mark]
 ```
 
-## Some Examples
-
-URL query string parameters:
-
-```
-text := "example.com/page?a=b&c=d"
->> text:find(before=$Pat`?`, $Pat`[..]`):split($Pat`&`)
-= ["a=b", "c=d"]
-```
-
-Remove or get file extension:
-
-```
-filename := "foo.txt"
->> filename:without($Pat`.[:id:]`, where=End)
-= "foo"
-
->> filename:find(before=$Pat`.`, $Pat`[:id:][:end:]`)
-= MatchResult.Success(match="txt")
-
->> filename := "foo.tar.gz"
->> ".":join(filename:split($Pat`.`):from(2))
-= "tar.gz"
-```
-
 # Text Functions
 
 ## `as_c_string`
-- 
cgit v1.2.3