From ce2aebe91085f987aab31bd2a49820fb605cf386 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 27 Oct 2024 21:14:27 -0400
Subject: [PATCH] Update docs to reflect deprecation of "&" stack references

---
 docs/arrays.md      | 20 +++++++-------
 docs/booleans.md    | 14 ++++------
 docs/integers.md    | 29 ++++++++------------
 docs/metamethods.md |  2 +-
 docs/nums.md        | 17 ++++++------
 docs/pointers.md    | 66 ++++++++++++++++++---------------------------
 docs/sets.md        |  8 +++---
 docs/structs.md     |  4 +--
 docs/tables.md      |  4 +--
 docs/text.md        | 12 ++-------
 10 files changed, 71 insertions(+), 105 deletions(-)

diff --git a/docs/arrays.md b/docs/arrays.md
index 45b0e8a..ee28cf3 100644
--- a/docs/arrays.md
+++ b/docs/arrays.md
@@ -301,7 +301,7 @@ Clears all elements from the array.
 
 **Signature:**  
 ```tomo
-func clear(arr: &[T] -> Void)
+func clear(arr: @[T] -> Void)
 ```
 
 **Parameters:**
@@ -460,7 +460,7 @@ Removes and returns the top element of a heap. By default, this is the
 
 **Signature:**  
 ```tomo
-func heap_pop(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> T)
+func heap_pop(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> T)
 ```
 
 **Parameters:**
@@ -490,7 +490,7 @@ is a *minimum* heap.
 
 **Signature:**  
 ```tomo
-func heap_push(arr: &[T], item: T, by=T.compare -> Void)
+func heap_push(arr: @[T], item: T, by=T.compare -> Void)
 ```
 
 **Parameters:**
@@ -517,7 +517,7 @@ Converts an array into a heap.
 
 **Signature:**  
 ```tomo
-func heapify(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> Void)
+func heapify(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)
 ```
 
 **Parameters:**
@@ -544,7 +544,7 @@ Inserts an element at a specified position in the array.
 
 **Signature:**  
 ```tomo
-func insert(arr: &[T], item: T, at: Int = 0 -> Void)
+func insert(arr: @[T], item: T, at: Int = 0 -> Void)
 ```
 
 **Parameters:**
@@ -579,7 +579,7 @@ Inserts an array of items at a specified position in the array.
 
 **Signature:**  
 ```tomo
-func insert_all(arr: &[T], items: [T], at: Int = 0 -> Void)
+func insert_all(arr: @[T], items: [T], at: Int = 0 -> Void)
 ```
 
 **Parameters:**
@@ -639,7 +639,7 @@ Removes elements from the array starting at a specified index.
 
 **Signature:**  
 ```tomo
-func remove_at(arr: &[T], at: Int = -1, count: Int = 1 -> Void)
+func remove_at(arr: @[T], at: Int = -1, count: Int = 1 -> Void)
 ```
 
 **Parameters:**
@@ -672,7 +672,7 @@ Removes all occurrences of a specified item from the array.
 
 **Signature:**  
 ```tomo
-func remove_item(arr: &[T], item: T, max_count: Int = -1 -> Void)
+func remove_item(arr: @[T], item: T, max_count: Int = -1 -> Void)
 ```
 
 **Parameters:**
@@ -769,7 +769,7 @@ Shuffles the elements of the array in place.
 
 **Signature:**  
 ```tomo
-func shuffle(arr: &[T] -> Void)
+func shuffle(arr: @[T] -> Void)
 ```
 
 **Parameters:**
@@ -818,7 +818,7 @@ Sorts the elements of the array in place in ascending order (small to large).
 
 **Signature:**  
 ```tomo
-func sort(arr: &[T], by=T.compare -> Void)
+func sort(arr: @[T], by=T.compare -> Void)
 ```
 
 **Parameters:**
diff --git a/docs/booleans.md b/docs/booleans.md
index a08faa9..5610d86 100644
--- a/docs/booleans.md
+++ b/docs/booleans.md
@@ -16,13 +16,12 @@ boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`,
 
 **Signature:**  
 ```tomo
-func from_text(text: Text, success: Bool = !&Bool -> Bool)
+func from_text(text: Text -> Bool?)
 ```
 
 **Parameters:**
 
 - `text`: The string containing the boolean value.
-- `success`: If provided, this boolean value reference will be set to `yes` if the given text is a recognizable boolean value or `no` otherwise.
 
 **Returns:**  
 `yes` if the string matches a recognized truthy boolean value; otherwise return `no`.
@@ -30,14 +29,11 @@ func from_text(text: Text, success: Bool = !&Bool -> Bool)
 **Example:**  
 ```tomo
 >> Bool.from_text("yes")
-= yes
+= yes?
 >> Bool.from_text("no")
-= no
->> success := yes
->> Bool.from_text("???", &success)
-= no
->> success
-= no
+= no?
+>> Bool.from_text("???")
+= !Bool
 ```
 
 ---
diff --git a/docs/integers.md b/docs/integers.md
index 60ccd71..ef30b74 100644
--- a/docs/integers.md
+++ b/docs/integers.md
@@ -144,39 +144,32 @@ Converts a text representation of an integer into an integer.
 
 **Signature:**  
 ```tomo
-func from_text(text: Text, success: Bool = !&Bool? -> Int)
+func from_text(text: Text -> Int?)
 ```
 
 **Parameters:**
 
 - `text`: The text containing the integer.
-- `success`: If non-null, this pointer will be set to `yes` if the whole text
-  is a valid integer that fits within the representable range of the integer
-  type, otherwise `no`.
 
 **Returns:**  
 The integer represented by the text. If the given text contains a value outside
-of the representable range, the number will be truncated to the minimum or
-maximum representable value. Other failures to parse the number will return
-zero.
+of the representable range or if the entire text can't be parsed as an integer,
+a null value will be returned.
 
 **Example:**  
 ```tomo
 >> Int.from_text("123")
-= 123
+= 123?
 >> Int.from_text("0xFF")
-= 255
+= 255?
 
-success := no
->> Int.from_text("asdf", &success)
-= 0
->> success
-= no
+# Can't parse:
+>> Int.from_text("asdf")
+= !Int
 
->> Int8.from_text("9999999", &success)
-= 127
->> success
-= no
+# Outside valid range:
+>> Int8.from_text("9999999")
+= !Int
 ```
 
 ---
diff --git a/docs/metamethods.md b/docs/metamethods.md
index dbd1106..ca2eccc 100644
--- a/docs/metamethods.md
+++ b/docs/metamethods.md
@@ -3,7 +3,7 @@
 This language relies on a small set of "metamethods" which define special
 behavior that is required for all types:
 
-- `func as_text(obj:&(optional)T, colorize=no, type:&TypeInfo_t -> Text)`: a method to
+- `func as_text(obj:&T?, colorize=no, type:&TypeInfo_t -> Text)`: a method to
   convert the type to a string. If `colorize` is `yes`, then the method should
   include ANSI escape codes for syntax highlighting. If the `obj` pointer is
   `NULL`, a string representation of the type will be returned instead.
diff --git a/docs/nums.md b/docs/nums.md
index fc683fe..9072f86 100644
--- a/docs/nums.md
+++ b/docs/nums.md
@@ -543,7 +543,7 @@ The largest integer less than or equal to `x`.
 ### `format`
 
 **Description:**
-Formats a number as a string with a specified precision.
+Formats a number as a text with a specified precision.
 
 **Signature:**
 ```tomo
@@ -556,7 +556,7 @@ func format(n: Num, precision: Int = 0 -> Text)
 - `precision`: The number of decimal places. Default is `0`.
 
 **Returns:**
-A string representation of the number with the specified precision.
+A text representation of the number with the specified precision.
 
 **Example:**
 ```tomo
@@ -569,20 +569,19 @@ A string representation of the number with the specified precision.
 ### `from_text`
 
 **Description:**
-Converts a string representation of a number into a floating-point number.
+Converts a text representation of a number into a floating-point number.
 
 **Signature:**
 ```tomo
-func from_text(text: Text, the_rest: Text = "!&Text" -> Num)
+func from_text(text: Text -> Num?)
 ```
 
 **Parameters:**
 
-- `text`: The string containing the number.
-- `the_rest`: A string indicating what to return if the conversion fails. Default is `"!&Text"`.
+- `text`: The text containing the number.
 
 **Returns:**
-The number represented by the string.
+The number represented by the text or a null value if the entire text can't be parsed as a number.
 
 **Example:**
 ```tomo
@@ -917,7 +916,7 @@ func nan(tag: Text = "" -> Num)
 
 **Parameters:**
 
-- `tag`: An optional tag to describe the NaN. Default is an empty string.
+- `tag`: An optional tag to describe the NaN. Default is an empty text.
 
 **Returns:**
 A NaN value.
@@ -1086,7 +1085,7 @@ func scientific(n: Num, precision: Int = 0 -> Text)
 - `precision`: The number of decimal places. Default is `0`.
 
 **Returns:**
-A string representation of the number in scientific notation with the specified precision.
+A text representation of the number in scientific notation with the specified precision.
 
 **Example:**
 ```tomo
diff --git a/docs/pointers.md b/docs/pointers.md
index b1d0fc1..174c429 100644
--- a/docs/pointers.md
+++ b/docs/pointers.md
@@ -1,12 +1,8 @@
 # Pointers
 
 Pointers are numeric values that represent a location in memory where some type
-of data lives. Pointers are created using either the `@` prefix operator to
-**a**llocate heap memory or the `&` prefix operator to get the address of a
-variable. Stack pointers (`&`) are more limited than heap pointers (`@`) and
-cannot be stored inside an array, set, table, struct, enum, or channel.
-However, stack pointers are useful for methods that mutate local variables and
-don't need to save the pointer anywhere.
+of data lives. Pointers are created using the `@` prefix operator to
+**a**llocate heap memory.
 
 Pointers are the way in Tomo that you can create mutable data. All
 datastructures are by default, immutable, but using pointers, you can create
@@ -34,25 +30,6 @@ do_mutation(my_nums)
 = @[10, 1, 2]
 ```
 
-In general, heap pointers can be used as stack pointers if necessary, since
-the usage of stack pointers is restricted, but heap pointers don't have the
-same restrictions, so it's good practice to define functions that don't need
-to store pointers to use stack references. This lets you pass references to
-local variables or pointers to heap data depending on your needs.
-
-```tomo
-func swap_first_two(data:&[Int]):
-    data[1], data[2] = data[2], data[1]
-
-...
-
-heap_nums := @[10, 20, 30]
-swap_first_two(heap_nums)
-
-local_nums := [10, 20, 30]
-swap_first_two(&local_nums)
-```
-
 ## Dereferencing
 
 Pointers can be dereferenced to access the value that's stored at the pointer's
@@ -89,15 +66,14 @@ consistent.
 ## Null Safety
 
 Tomo pointers are, by default, guaranteed to be non-null. If you write a
-function that takes either a `&T` or `@T`, the value that will be given
-is always non-null. However, optional pointers can be used by adding a
-question mark to the type: `&T?` or `@T?`. A null value can be created
-using the syntax `!@T` or `!&T`. You can also append a question mark to
-a pointer value so the type checker knows it's supposed to be optional:
+function that takes a `@T`, the value that will be given is always non-null.
+However, optional pointers can be used by adding a question mark to the type:
+`@T?`. A null value can be created using the syntax `!@T`. You can also append
+a question mark to a pointer value so the type checker knows it's supposed to
+be optional:
 
 ```
 optional := @[10, 20]?
-optional := &foo?
 ```
 
 The compiler will not allow you to dereference an optionally null pointer
@@ -120,15 +96,25 @@ you can use `ptr.foo` on a pointer to that struct type as well, without needing
 to use `ptr[].foo`. The same is true for array accesses like `ptr[i]` and method
 calls like `ptr:reversed()`.
 
-As a matter of convenience, local variables can also be automatically promoted
-to stack references when invoking methods that require a stack reference as the
-first argument. For example:
+# Read-Only Views
+
+In a small number of API methods (`array:first()`, `array:binary_search()`,
+`array:sort()`, `array:sorted()`, and `array:heapify()`), the methods allow you
+to provide custom comparison functions. However, for safety, we don't actually
+want the comparison methods to be able mutate the values inside of immutable
+array values. For implementation reasons, we can't pass the values themselves
+to the comparison functions, but need to pass pointers to the array members.
+So, to work around this, Tomo allows you to define functions that take
+immutable view pointers as arguments. These behave similarly to `@` pointers,
+but their type signature uses `&` instead of `@` and read-only view pointers
+cannot be used to mutate the contents that they point to and cannot be stored
+inside of any datastructures as elements or members.
 
 ```tomo
-func swap_first_two(arr:&[Int]):
-    arr[1], arr[2] = arr[2], arr[1]
-...
-my_arr := [10, 20, 30] // not a pointer
-swap_first_two(my_arr) // ok, automatically converted to &my_arr
-my_arr:shuffle() // ok, automatically converted to &my_arr
+nums := @[10, 20, 30]
+>> nums:first(func(x:&Int): x / 2 == 10)
+= 2?
 ```
+
+Normal `@` pointers can be promoted to immutable view pointers automatically,
+but not vice versa.
diff --git a/docs/sets.md b/docs/sets.md
index bc1b3ac..e9c44b2 100644
--- a/docs/sets.md
+++ b/docs/sets.md
@@ -133,7 +133,7 @@ Adds multiple items to the set.
 
 **Signature:**  
 ```tomo
-func add_all(set:&{T}, items: [T] -> Void)
+func add_all(set:@{T}, items: [T] -> Void)
 ```
 
 **Parameters:**
@@ -158,7 +158,7 @@ Removes an item from the set.
 
 **Signature:**  
 ```tomo
-func remove(set:&{T}, item: T -> Void)
+func remove(set:@{T}, item: T -> Void)
 ```
 
 **Parameters:**
@@ -183,7 +183,7 @@ Removes multiple items from the set.
 
 **Signature:**  
 ```tomo
-func remove_all(set:&{T}, items: [T] -> Void)
+func remove_all(set:@{T}, items: [T] -> Void)
 ```
 
 **Parameters:**
@@ -208,7 +208,7 @@ Removes all items from the set.
 
 **Signature:**  
 ```tomo
-func clear(set:&{T} -> Void)
+func clear(set:@{T} -> Void)
 ```
 
 **Parameters:**
diff --git a/docs/structs.md b/docs/structs.md
index 842f815..ce4f6ff 100644
--- a/docs/structs.md
+++ b/docs/structs.md
@@ -27,10 +27,10 @@ struct Foo(name:Text, age:Int):
     func greet(f:Foo):
         say("Hi my name is $f.name and I am $f.age years old!")
 
-    func get_older(f:&Foo):
+    func get_older(f:@Foo):
         f.age += 1
 ...
-my_foo := Foo("Alice", 28)
+my_foo := @Foo("Alice", 28)
 my_foo:greet()
 my_foo:get_older()
 ```
diff --git a/docs/tables.md b/docs/tables.md
index eb727d7..1de5811 100644
--- a/docs/tables.md
+++ b/docs/tables.md
@@ -118,7 +118,7 @@ not already in the table, its value will be assumed to be zero.
 
 **Signature:**  
 ```tomo
-func bump(t:&{K:V}, key: K, amount: Int = 1 -> Void)
+func bump(t:@{K:V}, key: K, amount: Int = 1 -> Void)
 ```
 
 **Parameters:**
@@ -148,7 +148,7 @@ Removes all key-value pairs from the table.
 
 **Signature:**  
 ```tomo
-func clear(t:&{K:V})
+func clear(t:@{K:V})
 ```
 
 **Parameters:**
diff --git a/docs/text.md b/docs/text.md
index e8392b8..7941e6a 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -274,7 +274,7 @@ functions that would normally be handled by a more extensive API:
 
 ```
 Text.has(pattern:Pattern)->Bool
-Text.find(pattern:Pattern, start=1, length=!&Int64?)->Int
+Text.find(pattern:Pattern, start=1)->Int
 Text.find_all(pattern:Pattern)->[Text]
 Text.matches(pattern:Pattern)->[Text]?
 Text.map(pattern:Pattern, fn:func(t:Text)->Text)->Text
@@ -642,7 +642,7 @@ See: [Patterns](#Patterns) for more information on patterns.
 
 **Signature:**  
 ```tomo
-func find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int64 -> Int)
+func find(text: Text, pattern: Pattern, start: Int = 1)
 ```
 
 **Parameters:**
@@ -650,8 +650,6 @@ func find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int6
 - `text`: The text to be searched.
 - `pattern`: The pattern to search for.
 - `start`: The index to start the search.
-- `length`: If non-null, this pointer's value will be set to the length of the
-  match, or `-1` if there is no match.
 
 **Returns:**  
 `0` if the target pattern is not found, otherwise the index where the match was
@@ -667,12 +665,6 @@ found.
 = 2
 >> " one   two  three   ":find("{id}", start=5)
 = 8
-
->> len := 0[64]
->> "   one  ":find("{id}", length=&len)
-= 4
->> len
-= 3[64]
 ```
 
 ---