diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/arrays.md | 20 | ||||
| -rw-r--r-- | docs/booleans.md | 14 | ||||
| -rw-r--r-- | docs/integers.md | 29 | ||||
| -rw-r--r-- | docs/metamethods.md | 2 | ||||
| -rw-r--r-- | docs/nums.md | 17 | ||||
| -rw-r--r-- | docs/pointers.md | 66 | ||||
| -rw-r--r-- | docs/sets.md | 8 | ||||
| -rw-r--r-- | docs/structs.md | 4 | ||||
| -rw-r--r-- | docs/tables.md | 4 | ||||
| -rw-r--r-- | docs/text.md | 12 |
10 files changed, 71 insertions, 105 deletions
diff --git a/docs/arrays.md b/docs/arrays.md index 45b0e8a6..ee28cf3b 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 a08faa9f..5610d863 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 60ccd71b..ef30b74d 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 dbd11069..ca2ecccd 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 fc683fe7..9072f86a 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 b1d0fc19..174c4296 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 bc1b3aca..e9c44b29 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 842f815b..ce4f6ff5 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 eb727d7e..1de58118 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 e8392b8f..7941e6a5 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] ``` --- |