348 lines
8.9 KiB
Markdown
348 lines
8.9 KiB
Markdown
---
|
|
Title: A Standard Library
|
|
Prev: Advanced Topics
|
|
Next: Complete Trait Reference
|
|
---
|
|
|
|
## Appendix A: Standard Library
|
|
|
|
This appendix provides a complete alphabetical reference of all standard library functions and operations.
|
|
|
|
### Standard Library Categories
|
|
|
|
**Array Operations**: [at](#at), [concat](#concat), [each](#each), [filter](#filter), [length](#length), [map](#map), [reduce](#reduce), [reverse](#reverse), [shape](#shape), [slice](#slice), [transpose](#transpose), [window](#window)
|
|
|
|
**I/O Operations**: [at](#at), [concat](#concat), [each](#each), [filter](#filter)
|
|
|
|
**String Operations**: [length](#length), [map](#map) [reduce](#reduce), [reverse](#reverse), [shape](#shape)
|
|
|
|
**Type Conversion**: [slice](#slice), [to_i8, to_i16, to_i32, to_i64](#to_i8-to_i16-to_i32-to_i64), [to_u8, to_u16, to_u32, to_u64](#to_u8-to_u16-to_u32-to_u64), [to_f32, to_f64](#to_f32-to_f64), [to_str](#to_str)
|
|
|
|
**Utility Operations**: [transpose](#transpose), [window](#window)
|
|
|
|
### Alphabetical Reference
|
|
|
|
#### at
|
|
**Signature**: `(Selectable<T> Size -- T)`
|
|
**Trait**: Selectable<T>
|
|
**Description**: Access element at the given index.
|
|
**Example**:
|
|
```
|
|
[10 20 30] 1 at // Returns 20
|
|
```
|
|
**See Also**: [slice](#slice), [length](#length)
|
|
|
|
#### concat
|
|
**Signature**: `(Concatenable Concatenable -- Concatenable)`
|
|
**Trait**: Concatenable
|
|
**Description**: Concatenate two containers or strings.
|
|
**Example**:
|
|
```
|
|
[1 2 3] [4 5 6] concat // Returns [1 2 3 4 5 6]
|
|
"hello" " world" concat // Returns "hello world"
|
|
```
|
|
**See Also**: [join](#join), [split](#split)
|
|
|
|
#### depth
|
|
**Signature**: `(-- Size)`
|
|
**Trait**: Stackable
|
|
**Description**: Push current stack depth onto the stack.
|
|
**Example**:
|
|
```
|
|
1 2 3 depth // Returns 1 2 3 3
|
|
```
|
|
**See Also**: [pick](#pick), [roll](#roll)
|
|
|
|
#### drop
|
|
**Signature**: `(Self --)`
|
|
**Trait**: Stackable
|
|
**Description**: Remove and discard the top item from the stack.
|
|
**Example**:
|
|
```
|
|
5 10 drop // Returns 5
|
|
```
|
|
**See Also**: [dup](#dup), [swap](#swap)
|
|
|
|
#### dup
|
|
**Signature**: `(Self -- Self Self)`
|
|
**Trait**: Stackable
|
|
**Description**: Duplicate the top item on the stack.
|
|
**Example**:
|
|
```
|
|
5 dup // Returns 5 5
|
|
```
|
|
**See Also**: [drop](#drop), [over](#over)
|
|
|
|
#### each
|
|
**Signature**: `(ArrayOf<T> TokenString --)`
|
|
**Description**: Apply function to each element (side effects).
|
|
**Example**:
|
|
```
|
|
[1 2 3] { print } each // Prints 1, 2, 3
|
|
```
|
|
**See Also**: [map](#map), [filter](#filter)
|
|
|
|
#### eval
|
|
**Signature**: `(TokenString --)`
|
|
**Trait**: Implementable
|
|
**Description**: Parse and execute TokenString as code.
|
|
**Example**:
|
|
```
|
|
"2 3 +" eval // Returns 5
|
|
```
|
|
**See Also**: [lambda](#lambda)
|
|
|
|
#### filter
|
|
**Signature**: `(ArrayOf<T> TokenString -- ArrayOf<T>)`
|
|
**Description**: Keep only elements matching predicate.
|
|
**Example**:
|
|
```
|
|
[1 2 3 4 5] { 2 % 0 == } filter // Returns [2 4]
|
|
```
|
|
**See Also**: [map](#map), [reduce](#reduce)
|
|
|
|
#### input
|
|
**Signature**: `(String -- String)`
|
|
**Description**: Print prompt and read line from stdin.
|
|
**Example**:
|
|
```
|
|
"Enter name: " input // Prompts and returns user input
|
|
```
|
|
**See Also**: [print](#print), [read](#read)
|
|
|
|
#### join
|
|
**Signature**: `(ArrayOf<String> String -- String)`
|
|
**Description**: Join array of strings with delimiter.
|
|
**Example**:
|
|
```
|
|
["a" "b" "c"] "," join // Returns "a,b,c"
|
|
```
|
|
**See Also**: [split](#split), [concat](#concat)
|
|
|
|
#### lambda
|
|
**Signature**: `(TokenString -- Callable)`
|
|
**Trait**: Implementable
|
|
**Description**: Convert TokenString to callable code block.
|
|
**Example**:
|
|
```
|
|
{ dup * } lambda ::square swap
|
|
5 square eval // Returns 25
|
|
```
|
|
**See Also**: [eval](#eval)
|
|
|
|
#### length
|
|
**Signature**: `(Sized -- i64)`
|
|
**Trait**: Sized
|
|
**Description**: Get the number of elements in a container.
|
|
**Example**:
|
|
```
|
|
[1 2 3 4 5] length // Returns 5
|
|
"hello" length // Returns 5
|
|
```
|
|
**See Also**: [at](#at), [slice](#slice)
|
|
|
|
#### map
|
|
**Signature**: `(ArrayOf<T> TokenString -- ArrayOf<U>)`
|
|
**Description**: Transform each element with function.
|
|
**Example**:
|
|
```
|
|
[1 2 3 4] { 2 * } map // Returns [2 4 6 8]
|
|
```
|
|
**See Also**: [filter](#filter), [reduce](#reduce), [each](#each)
|
|
|
|
#### over
|
|
**Signature**: `(Self Self -- Self Self Self)`
|
|
**Trait**: Stackable
|
|
**Description**: Copy the second item to the top of the stack.
|
|
**Example**:
|
|
```
|
|
5 10 over // Returns 5 10 5
|
|
```
|
|
**See Also**: [dup](#dup), [swap](#swap), [rot](#rot)
|
|
|
|
#### parse
|
|
**Signature**: `(String -- Parseable)`
|
|
**Trait**: Parseable
|
|
**Description**: Parse string to value of inferred type.
|
|
**Example**:
|
|
```
|
|
"123" parse // Returns 123 (as appropriate numeric type)
|
|
```
|
|
**See Also**: [to_str](#to_str)
|
|
|
|
#### pick
|
|
**Signature**: `(Size -- Self)`
|
|
**Trait**: Stackable
|
|
**Description**: Copy nth item to top (0 = top, 1 = second, etc.).
|
|
**Example**:
|
|
```
|
|
1 2 3 4 2 pick // Returns 1 2 3 4 2
|
|
```
|
|
**See Also**: [roll](#roll), [depth](#depth)
|
|
|
|
#### print
|
|
**Signature**: `(Stringifiable --)`
|
|
**Description**: Print value to stdout.
|
|
**Example**:
|
|
```
|
|
"Hello" print // Prints: Hello
|
|
42 print // Prints: 42
|
|
```
|
|
**See Also**: [input](#input), [to_str](#to_str)
|
|
|
|
#### read
|
|
**Signature**: `(String -- String)`
|
|
**Description**: Read file contents as string.
|
|
**Example**:
|
|
```
|
|
"file.txt" read // Returns file contents
|
|
```
|
|
**See Also**: [write](#write)
|
|
|
|
#### reduce
|
|
**Signature**: `(ArrayOf<T> T TokenString -- T)`
|
|
**Description**: Fold array with accumulator function.
|
|
**Example**:
|
|
```
|
|
[1 2 3 4] 0 { + } reduce // Returns 10
|
|
```
|
|
**See Also**: [map](#map), [filter](#filter)
|
|
|
|
#### reverse
|
|
**Signature**: `(ArrayOf<T> -- ArrayOf<T>)`
|
|
**Description**: Reverse order of array elements.
|
|
**Example**:
|
|
```
|
|
[1 2 3] reverse // Returns [3 2 1]
|
|
```
|
|
**See Also**: [transpose](#transpose)
|
|
|
|
#### roll
|
|
**Signature**: `(Size Size --)`
|
|
**Trait**: Stackable
|
|
**Description**: Rotate n items, times times.
|
|
**Example**:
|
|
```
|
|
1 2 3 4 3 1 roll // Rotates top 3 once: 1 3 4 2
|
|
```
|
|
**See Also**: [rot](#rot), [pick](#pick)
|
|
|
|
#### rot
|
|
**Signature**: `(Self Self Self -- Self Self Self)`
|
|
**Trait**: Stackable
|
|
**Description**: Rotate the top three items.
|
|
**Example**:
|
|
```
|
|
1 2 3 rot // Returns 2 3 1
|
|
```
|
|
**See Also**: [swap](#swap), [roll](#roll)
|
|
|
|
#### slice
|
|
**Signature**: `(Sliceable Size Size -- Sliceable)`
|
|
**Trait**: Sliceable
|
|
**Description**: Extract elements from start to end index.
|
|
**Example**:
|
|
```
|
|
[10 20 30 40] 1 3 slice // Returns [20 30]
|
|
```
|
|
**See Also**: [at](#at), [length](#length)
|
|
|
|
#### split
|
|
**Signature**: `(String String -- ArrayOf<String>)`
|
|
**Trait**: String
|
|
**Description**: Split string by delimiter.
|
|
**Example**:
|
|
```
|
|
"a,b,c" "," split // Returns ["a" "b" "c"]
|
|
```
|
|
**See Also**: [join](#join), [substr](#substr)
|
|
|
|
#### substr
|
|
**Signature**: `(String Size Size -- String)`
|
|
**Trait**: String
|
|
**Description**: Extract substring from start to end index.
|
|
**Example**:
|
|
```
|
|
"hello" 1 3 substr // Returns "el"
|
|
```
|
|
**See Also**: [slice](#slice), [split](#split)
|
|
|
|
#### swap
|
|
**Signature**: `(Self Self -- Self Self)`
|
|
**Trait**: Stackable
|
|
**Description**: Swap the top two items on the stack.
|
|
**Example**:
|
|
```
|
|
5 10 swap // Returns 10 5
|
|
```
|
|
**See Also**: [dup](#dup), [rot](#rot)
|
|
|
|
#### to_f32, to_f64
|
|
**Signature**: `(Convertible -- f32/f64)`
|
|
**Trait**: Convertible
|
|
**Description**: Convert value to 32-bit or 64-bit float.
|
|
**Example**:
|
|
```
|
|
42 to_f64 // Returns 42.0
|
|
```
|
|
**See Also**: [to_i8, to_i16, to_i32, to_i64](#to_i8-to_i16-to_i32-to_i64), [to_u8, to_u16, to_u32, to_u64](#to_u8-to_u16-to_u32-to_u64)
|
|
|
|
#### to_i8, to_i16, to_i32, to_i64
|
|
**Signature**: `(Convertible -- i8/i16/i32/i64)`
|
|
**Trait**: Convertible
|
|
**Description**: Convert value to signed integer type.
|
|
**Example**:
|
|
```
|
|
3.14 to_i32 // Returns 3 (truncates)
|
|
```
|
|
**See Also**: [to_u8, to_u16, to_u32, to_u64](#to_u8-to_u16-to_u32-to_u64), [to_f32, to_f64](#to_f32-to_f64)
|
|
|
|
#### to_str
|
|
**Signature**: `(Stringifiable -- String)`
|
|
**Trait**: Stringifiable
|
|
**Description**: Convert value to string representation.
|
|
**Example**:
|
|
```
|
|
42 to_str // Returns "42"
|
|
```
|
|
**See Also**: [parse](#parse), [print](#print)
|
|
|
|
#### to_u8, to_u16, to_u32, to_u64
|
|
**Signature**: `(Convertible -- u8/u16/u32/u64)`
|
|
**Trait**: Convertible
|
|
**Description**: Convert value to unsigned integer type.
|
|
**Example**:
|
|
```
|
|
42 to_u32 // Returns 42 (as u32)
|
|
```
|
|
**See Also**: [to_i8, to_i16, to_i32, to_i64](#to_i8-to_i16-to_i32-to_i64), [to_f32, to_f64](#to_f32-to_f64)
|
|
|
|
#### transpose
|
|
**Signature**: `(ArrayOf<ArrayOf<T>> -- ArrayOf<ArrayOf<T>>)`
|
|
**Description**: Transpose a 2D array (swap rows and columns).
|
|
**Example**:
|
|
```
|
|
[[1 2] [3 4]] transpose // Returns [[1 3] [2 4]]
|
|
```
|
|
**See Also**: [reverse](#reverse)
|
|
|
|
#### window
|
|
**Signature**: `(ArrayOf<T> Size -- ArrayOf<ArrayOf<T>>)`
|
|
**Description**: Create sliding windows of given size.
|
|
**Example**:
|
|
```
|
|
[1 2 3 4] 2 window // Returns [[1 2] [2 3] [3 4]]
|
|
```
|
|
**See Also**: [slice](#slice)
|
|
|
|
#### write
|
|
**Signature**: `(String String --)`
|
|
**Description**: Write string to file.
|
|
**Example**:
|
|
```
|
|
"data" "file.txt" write // Writes "data" to file.txt
|
|
```
|
|
**See Also**: [read](#read)
|
|
|
|
---
|