YREA-SLS/docs/standard_library.md

670 lines
17 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), [enumerate](#enumerate), [filter](#filter), [foldl](#foldl), [foldr](#foldr), [length](#length), [map](#map), [mean](#mean), [reduce](#reduce), [reverse](#reverse), [shape](#shape), [slice](#slice), [sum](#sum), [transpose](#transpose), [window](#window), [zip](#zip)
**I/O Operations**: [input](#input), [print](#print), [read](#read), [write](#write)
**String Operations**: [concat](#concat), [ends_with](#ends_with), [find](#find), [format](#format), [join](#join), [length](#length), [replace](#replace), [split](#split), [starts_with](#starts_with), [substr](#substr), [trim](#trim)
**Type Conversion**: [parse](#parse), [to_f32, to_f64](#to_f32-to_f64), [to_i8, to_i16, to_i32, to_i64](#to_i8-to_i16-to_i32-to_i64), [to_str](#to_str), [to_u8, to_u16, to_u32, to_u64](#to_u8-to_u16-to_u32-to_u64)
**Utility Operations**: [assert](#assert), [implements](#implements), [type_of](#type_of)
### Alphabetical Reference
#### abs
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Return the absolute value of a number.
**Example**:
```
-42 abs // Returns 42
3.14 abs // Returns 3.14
```
**See Also**: [min](#min), [max](#max)
#### acos
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate arc cosine (inverse cosine) in radians.
**Example**:
```
1.0 acos // Returns 0.0
0.0 acos // Returns ~1.5708 (pi/2)
```
**See Also**: [cos](#cos), [asin](#asin), [atan](#atan)
#### asin
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate arc sine (inverse sine) in radians.
**Example**:
```
1.0 asin // Returns ~1.5708 (pi/2)
0.0 asin // Returns 0.0
```
**See Also**: [sin](#sin), [acos](#acos), [atan](#atan)
#### assert
**Signature**: `(TokenString TokenString --)`
**Description**: Evaluate expression and condition, halt if condition is false.
**Example**:
```
{ 2 3 + } { 5 == } assert
{ 5 square } { 25 == } assert
```
**See Also**: [type_of](#type_of), [implements](#implements)
#### 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)
#### atan
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate arc tangent (inverse tangent) in radians.
**Example**:
```
1.0 atan // Returns ~0.7854 (pi/4)
0.0 atan // Returns 0.0
```
**See Also**: [tan](#tan), [atan2](#atan2), [asin](#asin)
#### atan2
**Signature**: `(Math Math -- Math)`
**Trait**: Math
**Description**: Calculate two-argument arc tangent of y/x in radians, using signs to determine quadrant.
**Example**:
```
1.0 1.0 atan2 // Returns ~0.7854 (pi/4)
1.0 0.0 atan2 // Returns ~1.5708 (pi/2)
```
**See Also**: [atan](#atan), [tan](#tan)
#### ceil
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Round number up to nearest integer.
**Example**:
```
3.14 ceil // Returns 4.0
-2.7 ceil // Returns -2.0
```
**See Also**: [floor](#floor), [round](#round)
#### 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)
#### cos
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate cosine of angle in radians.
**Example**:
```
0.0 cos // Returns 1.0
3.14159 cos // Returns ~-1.0
```
**See Also**: [sin](#sin), [tan](#tan), [acos](#acos)
#### 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)
#### ends_with
**Signature**: `(String String -- bool)`
**Trait**: String
**Description**: Check if string ends with given suffix.
**Example**:
```
"hello" "lo" ends_with // Returns true
"hello" "he" ends_with // Returns false
```
**See Also**: [starts_with](#starts_with), [find](#find)
#### enumerate
**Signature**: `(ArrayOf<T> -- ArrayOf<Pair<Size T>>)`
**Description**: Add indices to array elements.
**Example**:
```
["a" "b" "c"] enumerate // Returns [[0 "a"] [1 "b"] [2 "c"]]
```
**See Also**: [zip](#zip), [map](#map)
#### 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)
#### find
**Signature**: `(String String -- Option<Size>)`
**Trait**: String
**Description**: Find position of substring, returns Option::Some(index) or Option::None.
**Example**:
```
"hello world" "world" find // Returns Option::Some(6)
"hello world" "xyz" find // Returns Option::None
```
**See Also**: [starts_with](#starts_with), [ends_with](#ends_with)
#### floor
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Round number down to nearest integer.
**Example**:
```
3.14 floor // Returns 3.0
-2.7 floor // Returns -3.0
```
**See Also**: [ceil](#ceil), [round](#round)
#### foldl
**Signature**: `(ArrayOf<T> U TokenString -- U)`
**Description**: Left fold array with accumulator function.
**Example**:
```
[1 2 3 4] 0 { + } foldl // Returns 10
```
**See Also**: [foldr](#foldr), [reduce](#reduce)
#### foldr
**Signature**: `(ArrayOf<T> U TokenString -- U)`
**Description**: Right fold array with accumulator function.
**Example**:
```
[1 2 3 4] 0 { + } foldr // Returns 10
```
**See Also**: [foldl](#foldl), [reduce](#reduce)
#### format
**Signature**: `(String Iterable<Stringifiable> -- String)`
**Trait**: String
**Description**: Format string with values, replacing %d, %s, %f placeholders.
**Example**:
```
"x=%d, y=%d" [5 10] format // Returns "x=5, y=10"
"Hello %s" ["World"] format // Returns "Hello World"
```
**See Also**: [to_str](#to_str), [concat](#concat)
#### implements
**Signature**: `(Self Identifier -- bool)`
**Description**: Check if value's type implements a specific trait.
**Example**:
```
42 ::Addable implements // Returns true
"hello" ::String implements // Returns true
```
**See Also**: [type_of](#type_of), [assert](#assert)
#### 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)
#### max
**Signature**: `(Math Math -- Math)`
**Trait**: Math
**Description**: Return the maximum of two values.
**Example**:
```
3 5 max // Returns 5
-2 1 max // Returns 1
```
**See Also**: [min](#min), [abs](#abs)
#### mean
**Signature**: `(ArrayOf<Number> -- f64)`
**Description**: Calculate the average of numeric array elements.
**Example**:
```
[1 2 3 4 5] mean // Returns 3.0
```
**See Also**: [sum](#sum), [reduce](#reduce)
#### min
**Signature**: `(Math Math -- Math)`
**Trait**: Math
**Description**: Return the minimum of two values.
**Example**:
```
3 5 min // Returns 3
-2 1 min // Returns -2
```
**See Also**: [max](#max), [abs](#abs)
#### 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)
#### rand
**Signature**: `(-- f64)`
**Description**: Generate random f64 in range [0.0, 1.0).
**Example**:
```
rand // Returns 0.7234... (random value)
100 rand * // Random value 0.0-99.999...
```
**See Also**: [seed](#seed)
#### 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), [foldl](#foldl)
#### replace
**Signature**: `(String String String -- String)`
**Trait**: String
**Description**: Replace all occurrences of substring with replacement.
**Example**:
```
"hello world" "world" "Stack" replace // Returns "hello Stack"
```
**See Also**: [split](#split), [concat](#concat)
#### 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)
#### round
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Round number to nearest integer.
**Example**:
```
3.14 round // Returns 3.0
3.7 round // Returns 4.0
```
**See Also**: [floor](#floor), [ceil](#ceil)
#### seed
**Signature**: `(u64 --)`
**Description**: Seed the random number generator with specific value.
**Example**:
```
12345 seed // Seed RNG for deterministic results
rand // Returns deterministic value
```
**See Also**: [rand](#rand)
#### sin
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate sine of angle in radians.
**Example**:
```
0.0 sin // Returns 0.0
1.5708 sin // Returns ~1.0 (pi/2)
```
**See Also**: [cos](#cos), [tan](#tan), [asin](#asin)
#### 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)
#### sqrt
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate square root.
**Example**:
```
16 sqrt // Returns 4.0
2.0 sqrt // Returns ~1.414
```
**See Also**: [^](#operator-exponent)
#### starts_with
**Signature**: `(String String -- bool)`
**Trait**: String
**Description**: Check if string starts with given prefix.
**Example**:
```
"hello" "hel" starts_with // Returns true
"hello" "lo" starts_with // Returns false
```
**See Also**: [ends_with](#ends_with), [find](#find)
#### 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)
#### sum
**Signature**: `(ArrayOf<Number> -- Number)`
**Description**: Sum all numeric elements in array.
**Example**:
```
[1 2 3 4 5] sum // Returns 15
```
**See Also**: [mean](#mean), [reduce](#reduce)
#### 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)
#### tan
**Signature**: `(Math -- Math)`
**Trait**: Math
**Description**: Calculate tangent of angle in radians.
**Example**:
```
0.0 tan // Returns 0.0
0.7854 tan // Returns ~1.0 (pi/4)
```
**See Also**: [sin](#sin), [cos](#cos), [atan](#atan)
#### 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)
#### trim
**Signature**: `(String -- String)`
**Trait**: String
**Description**: Remove leading and trailing whitespace.
**Example**:
```
" hello " trim // Returns "hello"
```
**See Also**: [split](#split), [replace](#replace)
#### type_of
**Signature**: `(Self -- Identifier)`
**Description**: Return the type of a value as an identifier literal.
**Example**:
```
42 type_of // Returns ::i64
"hello" type_of // Returns ::String
```
**See Also**: [implements](#implements), [assert](#assert)
#### 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)
#### zip
**Signature**: `(ArrayOf<T> ArrayOf<U> -- ArrayOf<Pair<T U>>)`
**Description**: Combine two arrays element-wise into pairs.
**Example**:
```
[1 2 3] [4 5 6] zip // Returns [[1 4] [2 5] [3 6]]
```
**See Also**: [enumerate](#enumerate), [map](#map)
---