Bruce/tomo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity

Update docs to reflect deprecation of "&" stack references

Browse Source
This commit is contained in:
Bruce Hill 2024-10-27 21:14:27 -04:00
parent efb7be5bc4
commit ce2aebe910
10 changed files with 71 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/arrays.md
View File

@ -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:**

14
docs/booleans.md
View File

@ -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
```
---

29
docs/integers.md
View File

@ -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
```
---

2
docs/metamethods.md
View File

@ -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.

17
docs/nums.md
View File

@ -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

66
docs/pointers.md
View File

@ -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.

8
docs/sets.md
View File

@ -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:**

4
docs/structs.md
View File

@ -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()
```

4
docs/tables.md
View File

@ -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:**

12
docs/text.md
View File

@ -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]
```
---