KylerOlsen/YREA-SLS
KylerOlsen
/
YREA-SLS
1
0
Fork 0
Code Releases 3 Wiki Activity
YREA-SLS/docs/complete_trait_reference.md

909 lines
19 KiB
Markdown
Raw Blame History

---
Title: B Complete Trait Reference
Prev: Standard Library
Next: Complete Operator Reference
---
## Appendix B: Complete Trait Reference
This appendix contains all built-in trait definitions with complete documentation, organized alphabetically.
### Trait List
- Addable
- ArrayOf<T>
- Bitwise
- Comparable
- Concatenable
- Convertible
- Equatable
- Exponentiable
- Identifier
- Implementable
- Iterable<T>
- Logarithmic
- Logical
- Math
- Multiplyable
- Number
- Orderable
- Parseable
- Selectable<T>
- Size
- Sized
- Sliceable
- Stackable
- String
- Stringifiable
### Addable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) +:
(Self Self -- Self) -:
} ::Addable trait
```
**Methods**:
#### +:
**Signature**: `(Self Self -- Self)`
**Description**: Add two values together.
**Example**: `3 4 + // => 7`
#### -:
**Signature**: `(Self Self -- Self)`
**Description**: Subtract second value from first.
**Example**: `10 3 - // => 7`
**Standard Implementations**: All numeric types (i8, i16, i32, i64, u8, u16, u32, u64, f32, f64)
**Related Traits**: Multiplyable, Number, Math
**See Also**: Section 4.2 (Arithmetic Operators)
### ArrayOf<T>
**Generic Parameters**: T (element type)
**Inherits**: Sized, Selectable<T>, Sliceable
**Definition**:
```
[ ::Sized ::Selectable<T> ::Sliceable ] ::ArrayOf<T> inher
{ } ::ArrayOf<T> trait
```
**Description**: Composite trait for arrays, inheriting all container operations.
**Standard Implementations**: Array types
**Related Traits**: Sized, Selectable, Sliceable, Iterable
**See Also**: Section 7.4 (Arrays)
### Bitwise
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) bitand:
(Self Self -- Self) bitor:
(Self Self -- Self) bitxor:
(Self -- Self) bitnot:
(Self Size -- Self) shl:
(Self Size -- Self) shr:
} ::Bitwise trait
```
**Methods**:
#### bitand:
**Signature**: `(Self Self -- Self)`
**Description**: Bitwise AND of two values.
**Example**: `0xFF 0x0F bitand // => 0x0F`
#### bitor:
**Signature**: `(Self Self -- Self)`
**Description**: Bitwise OR of two values.
**Example**: `0xF0 0x0F bitor // => 0xFF`
#### bitxor:
**Signature**: `(Self Self -- Self)`
**Description**: Bitwise XOR of two values.
**Example**: `0xFF 0x0F bitxor // => 0xF0`
#### bitnot:
**Signature**: `(Self -- Self)`
**Description**: Bitwise NOT (complement) of value.
**Example**: `0xFF bitnot // => (inverted bits)`
#### shl:
**Signature**: `(Self Size -- Self)`
**Description**: Shift bits left by n positions.
**Example**: `4 2 shl // => 16`
#### shr:
**Signature**: `(Self Size -- Self)`
**Description**: Shift bits right by n positions.
**Example**: `16 2 shr // => 4`
**Standard Implementations**: Integer types (i8, i16, i32, i64, u8, u16, u32, u64)
**Related Traits**: None
**See Also**: Section 4.5 (Bitwise Operators)
### Comparable
**Generic Parameters**: None
**Inherits**: Orderable, Equatable
**Definition**:
```
[ ::Orderable ::Equatable ] ::Comparable inher
{ } ::Comparable trait
```
**Description**: Composite trait combining ordering and equality comparisons.
**Standard Implementations**: All numeric types, strings, characters
**Related Traits**: Orderable, Equatable, Size, Number
**See Also**: Section 4.3 (Comparison Operators)
### Concatenable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) concat:
} ::Concatenable trait
```
**Methods**:
#### concat:
**Signature**: `(Self Self -- Self)`
**Description**: Join two containers or strings together.
**Example**: `"hello" " world" concat // => "hello world"`
**Standard Implementations**: Arrays, strings
**Related Traits**: String, ArrayOf
**See Also**: Section 7.4 (Arrays), Appendix A (concat)
### Convertible
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- i8) to_i8:
(Self -- i16) to_i16:
(Self -- i32) to_i32:
(Self -- i64) to_i64:
(Self -- u8) to_u8:
(Self -- u16) to_u16:
(Self -- u32) to_u32:
(Self -- u64) to_u64:
(Self -- f32) to_f32:
(Self -- f64) to_f64:
} ::Convertible trait
```
**Methods**: Provides explicit type conversion methods to all numeric types.
**Standard Implementations**: All numeric types
**Related Traits**: Stringifiable, Parseable, Size
**See Also**: Section 11.5 (Type Conversion)
### Equatable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- bool) ==:
(Self Self -- bool) !=:
} ::Equatable trait
```
**Methods**:
#### ==:
**Signature**: `(Self Self -- bool)`
**Description**: Test if two values are equal.
**Example**: `5 5 == // => true`
#### !=:
**Signature**: `(Self Self -- bool)`
**Description**: Test if two values are not equal.
**Example**: `5 3 != // => true`
**Standard Implementations**: All types
**Related Traits**: Orderable, Comparable
**See Also**: Section 4.3 (Comparison Operators)
### Exponentiable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) ^:
} ::Exponentiable trait
```
**Methods**:
#### ^:
**Signature**: `(Self Self -- Self)`
**Description**: Raise first value to the power of the second.
**Example**: `2 8 ^ // => 256`
**Standard Implementations**: Numeric types
**Related Traits**: Addable, Multiplyable, Number, Math
**See Also**: Section 4.2 (Arithmetic Operators)
### Identifier
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{ } ::Identifier trait
```
**Description**: Marker trait for identifier types.
**Standard Implementations**: Identifier literals
**Related Traits**: Implementable
**See Also**: Section 11.2 (Identifier Literals)
### Implementable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(TokenString Identifier --) trait:
(Identifier TokenString Identifier --) impl:
(ArrayOf<Identifier> Identifier --) inher:
} ::Implementable trait
```
**Methods**:
#### trait:
**Signature**: `(TokenString Identifier --)`
**Description**: Define a new trait.
**Example**: `{ (Self -- ) draw: } ::Drawable trait`
#### impl:
**Signature**: `(Identifier TokenString Identifier --)`
**Description**: Implement a trait for a type.
**Example**: `::Drawable { ... } ::Rectangle impl`
#### inher:
**Signature**: `(ArrayOf<Identifier> Identifier --)`
**Description**: Declare trait inheritance.
**Example**: `[ ::Orderable ::Equatable ] ::Comparable inher`
**Standard Implementations**: Language-level operators
**Related Traits**: Identifier
**See Also**: Section 9 (Trait System)
### Iterable<T>
**Generic Parameters**: T (element type)
**Inherits**: None
**Definition**:
```
{
(Self -- Self Option<T>) next:
} ::Iterable<T> trait
```
**Methods**:
#### next:
**Signature**: `(Self -- Self Option<T>)`
**Description**: Get next item from iterator.
**Example**: Iterator protocol for collections
**Standard Implementations**: Arrays, ranges, iterators
**Related Traits**: ArrayOf, Selectable
**See Also**: Section 8.3 (Type Tuples - Variable Arguments)
### Logarithmic
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) logb:
(Self -- Self) log:
(Self -- Self) ln:
} ::Logarithmic trait
```
**Methods**:
#### logb:
**Signature**: `(Self Self -- Self)`
**Description**: Logarithm with custom base.
**Example**: `8 2 logb // => 3.0`
#### log:
**Signature**: `(Self -- Self)`
**Description**: Logarithm base 10.
**Example**: `100 log // => 2.0`
#### ln:
**Signature**: `(Self -- Self)`
**Description**: Natural logarithm (base e).
**Example**: `2.718 ln // => 1.0`
**Standard Implementations**: Floating point types
**Related Traits**: Exponentiable, Number, Math
**See Also**: Section 4.2 (Arithmetic Operators)
### Logical
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- bool) truthy:
(Self Self -- Self) and:
(Self Self -- Self) or:
(Self -- Self) not:
} ::Logical trait
```
**Methods**:
#### truthy:
**Signature**: `(Self -- bool)`
**Description**: Convert to boolean (truthiness check).
**Example**: `5 truthy // => true`, `0 truthy // => false`
#### and:
**Signature**: `(Self Self -- Self)`
**Description**: Logical AND - returns first if falsy, else second.
**Example**: `true false and // => false`
#### or:
**Signature**: `(Self Self -- Self)`
**Description**: Logical OR - returns first if truthy, else second.
**Example**: `true false or // => true`
#### not:
**Signature**: `(Self -- Self)`
**Description**: Logical NOT - inverts truthiness.
**Example**: `false not // => true`
**Standard Implementations**: bool, numbers, Option, Result
**Related Traits**: None
**See Also**: Section 4.4 (Logical Operators)
### Math
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- Self) sqrt:
(Self -- Self) abs:
(Self -- Self) sin:
(Self -- Self) cos:
(Self -- Self) tan:
(Self -- Self) asin:
(Self -- Self) acos:
(Self -- Self) atan:
(Self Self -- Self) atan2:
(Self -- Self) floor:
(Self -- Self) ceil:
(Self -- Self) round:
(Self Self -- Self) min:
(Self Self -- Self) max:
} ::Math trait
```
**Methods**:
#### sqrt:
**Signature**: `(Self -- Self)`
**Description**: Calculate square root.
**Example**: `16 sqrt // => 4.0`
#### abs:
**Signature**: `(Self -- Self)`
**Description**: Return absolute value.
**Example**: `-42 abs // => 42`
#### sin:
**Signature**: `(Self -- Self)`
**Description**: Calculate sine (radians).
**Example**: `0.0 sin // => 0.0`
#### cos:
**Signature**: `(Self -- Self)`
**Description**: Calculate cosine (radians).
**Example**: `0.0 cos // => 1.0`
#### tan:
**Signature**: `(Self -- Self)`
**Description**: Calculate tangent (radians).
**Example**: `0.0 tan // => 0.0`
#### asin:
**Signature**: `(Self -- Self)`
**Description**: Calculate arc sine (radians).
**Example**: `1.0 asin // => ~1.5708`
#### acos:
**Signature**: `(Self -- Self)`
**Description**: Calculate arc cosine (radians).
**Example**: `1.0 acos // => 0.0`
#### atan:
**Signature**: `(Self -- Self)`
**Description**: Calculate arc tangent (radians).
**Example**: `1.0 atan // => ~0.7854`
#### atan2:
**Signature**: `(Self Self -- Self)`
**Description**: Two-argument arc tangent.
**Example**: `1.0 1.0 atan2 // => ~0.7854`
#### floor:
**Signature**: `(Self -- Self)`
**Description**: Round down to nearest integer.
**Example**: `3.14 floor // => 3.0`
#### ceil:
**Signature**: `(Self -- Self)`
**Description**: Round up to nearest integer.
**Example**: `3.14 ceil // => 4.0`
#### round:
**Signature**: `(Self -- Self)`
**Description**: Round to nearest integer.
**Example**: `3.7 round // => 4.0`
#### min:
**Signature**: `(Self Self -- Self)`
**Description**: Return minimum of two values.
**Example**: `3 5 min // => 3`
#### max:
**Signature**: `(Self Self -- Self)`
**Description**: Return maximum of two values.
**Example**: `3 5 max // => 5`
**Standard Implementations**: Numeric types (especially floating point)
**Related Traits**: Number, Addable, Multiplyable, Exponentiable, Logarithmic
**See Also**: Section 4.2 (Arithmetic Operators), Section 4.6 (Randomness)
### Multiplyable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- Self) *:
(Self Self -- Self) /:
(Self Self -- Self) %:
} ::Multiplyable trait
```
**Methods**:
#### *:
**Signature**: `(Self Self -- Self)`
**Description**: Multiply two values.
**Example**: `5 6 * // => 30`
#### /:
**Signature**: `(Self Self -- Self)`
**Description**: Divide first value by second.
**Example**: `20 4 / // => 5`
#### %:
**Signature**: `(Self Self -- Self)`
**Description**: Remainder after division (modulo).
**Example**: `17 5 % // => 2`
**Standard Implementations**: All numeric types
**Related Traits**: Addable, Exponentiable, Number, Math
**See Also**: Section 4.2 (Arithmetic Operators)
### Number
**Generic Parameters**: None
**Inherits**: Addable, Multiplyable, Exponentiable, Comparable, Logarithmic
**Definition**:
```
[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher
{ } ::Number trait
```
**Description**: Composite trait representing the full suite of numeric operations.
**Standard Implementations**: All numeric types (i8, i16, i32, i64, u8, u16, u32, u64, f32, f64)
**Related Traits**: Addable, Multiplyable, Exponentiable, Comparable, Logarithmic, Math
**See Also**: Section 4.2 (Arithmetic Operators)
### Orderable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Self -- bool) >:
(Self Self -- bool) >=:
(Self Self -- bool) <:
(Self Self -- bool) <=:
} ::Orderable trait
```
**Methods**:
#### >:
**Signature**: `(Self Self -- bool)`
**Description**: True if first value is greater than second.
**Example**: `5 3 > // => true`
#### >=:
**Signature**: `(Self Self -- bool)`
**Description**: True if first value is greater than or equal to second.
**Example**: `5 5 >= // => true`
#### <:
**Signature**: `(Self Self -- bool)`
**Description**: True if first value is less than second.
**Example**: `3 5 < // => true`
#### <=:
**Signature**: `(Self Self -- bool)`
**Description**: True if first value is less than or equal to second.
**Example**: `5 5 <= // => true`
**Standard Implementations**: All numeric types, strings, characters
**Related Traits**: Equatable, Comparable
**See Also**: Section 4.3 (Comparison Operators)
### Parseable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(String -- Self) parse:
} ::Parseable trait
```
**Methods**:
#### parse:
**Signature**: `(String -- Self)`
**Description**: Parse string to value of this type.
**Example**: `"123" parse // => 123`
**Standard Implementations**: All numeric types, bool
**Related Traits**: Stringifiable, Convertible
**See Also**: Appendix A (parse)
### Selectable<T>
**Generic Parameters**: T (element type)
**Inherits**: None
**Definition**:
```
{
(Self Size -- T) at:
} ::Selectable<T> trait
```
**Methods**:
#### at:
**Signature**: `(Self Size -- T)`
**Description**: Access element at given index.
**Example**: `[10 20 30] 1 at // => 20`
**Standard Implementations**: Arrays, strings
**Related Traits**: ArrayOf, Sized, Sliceable
**See Also**: Section 7.4 (Arrays)
### Size
**Generic Parameters**: None
**Inherits**: Addable, Comparable, Convertible
**Definition**:
```
[ ::Addable ::Comparable ::Convertible ] ::Size inher
{ } ::Size trait
```
**Description**: Represents types suitable for indexing and sizing operations.
**Standard Implementations**: All integer types (i8, i16, i32, i64, u8, u16, u32, u64)
**Related Traits**: Addable, Comparable, Convertible
**See Also**: Section 4.1 (Stack Operations - pick, roll)
### Sized
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- i64) length:
} ::Sized trait
```
**Methods**:
#### length:
**Signature**: `(Self -- i64)`
**Description**: Get the number of elements in a container.
**Example**: `[1 2 3 4 5] length // => 5`
**Standard Implementations**: Arrays, strings
**Related Traits**: ArrayOf, Selectable, Sliceable
**See Also**: Section 7.4 (Arrays)
### Sliceable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self Size Size -- Self) slice:
} ::Sliceable trait
```
**Methods**:
#### slice:
**Signature**: `(Self Size Size -- Self)`
**Description**: Extract elements from start to end index.
**Example**: `[10 20 30 40] 1 3 slice // => [20 30]`
**Standard Implementations**: Arrays, strings
**Related Traits**: ArrayOf, Sized, Selectable
**See Also**: Section 7.4 (Arrays)
### Stackable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- Self Self) dup:
(Self -- ) drop:
(Self Self -- Self Self) swap:
(Self Self -- Self Self Self) over:
(Self Self Self -- Self Self Self) rot:
(Size -- Self) pick:
(Size Size -- ) roll:
(-- Size) depth:
} ::Stackable trait
```
**Methods**:
#### dup:
**Signature**: `(Self -- Self Self)`
**Description**: Duplicate the top item on the stack.
**Example**: `5 dup // => 5 5`
#### drop:
**Signature**: `(Self -- )`
**Description**: Remove and discard the top item.
**Example**: `5 10 drop // => 5`
#### swap:
**Signature**: `(Self Self -- Self Self)`
**Description**: Swap the top two items.
**Example**: `5 10 swap // => 10 5`
#### over:
**Signature**: `(Self Self -- Self Self Self)`
**Description**: Copy the second item to the top.
**Example**: `5 10 over // => 5 10 5`
#### rot:
**Signature**: `(Self Self Self -- Self Self Self)`
**Description**: Rotate the top three items.
**Example**: `1 2 3 rot // => 2 3 1`
#### pick:
**Signature**: `(Size -- Self)`
**Description**: Copy nth item to top (0 = top).
**Example**: `1 2 3 4 2 pick // => 1 2 3 4 2`
#### roll:
**Signature**: `(Size Size -- )`
**Description**: Rotate n items, times times.
**Example**: `1 2 3 4 3 1 roll // => 1 3 4 2`
#### depth:
**Signature**: `(-- Size)`
**Description**: Push current stack depth.
**Example**: `1 2 3 depth // => 1 2 3 3`
**Standard Implementations**: All primitive types
**Related Traits**: None
**See Also**: Section 4.1 (Stack Operations)
### String
**Generic Parameters**: None
**Inherits**: Concatenable
**Definition**:
```
[ ::Concatenable ] ::String inher
{
(Self Size Size -- Self) substr:
(Self Self -- ArrayOf<Self>) split:
(Self Self String -- Self) replace:
(Self -- Self) trim:
(Self Self -- Option<Size>) find:
(Self Self -- bool) starts_with:
(Self Self -- bool) ends_with:
} ::String trait
```
**Methods**:
#### substr:
**Signature**: `(Self Size Size -- Self)`
**Description**: Extract substring from start to end index.
**Example**: `"hello" 1 3 substr // => "el"`
#### split:
**Signature**: `(Self Self -- ArrayOf<Self>)`
**Description**: Split string by delimiter.
**Example**: `"a,b,c" "," split // => ["a" "b" "c"]`
#### replace:
**Signature**: `(Self Self String -- Self)`
**Description**: Replace all occurrences of substring.
**Example**: `"hello world" "world" "Stack" replace // => "hello Stack"`
#### trim:
**Signature**: `(Self -- Self)`
**Description**: Remove leading and trailing whitespace.
**Example**: `" hello " trim // => "hello"`
#### find:
**Signature**: `(Self Self -- Option<Size>)`
**Description**: Find position of substring.
**Example**: `"hello world" "world" find // => Option::Some(6)`
#### starts_with:
**Signature**: `(Self Self -- bool)`
**Description**: Check if string starts with prefix.
**Example**: `"hello" "hel" starts_with // => true`
#### ends_with:
**Signature**: `(Self Self -- bool)`
**Description**: Check if string ends with suffix.
**Example**: `"hello" "lo" ends_with // => true`
**Standard Implementations**: String type
**Related Traits**: Concatenable, Sized, Sliceable
**See Also**: Section 11.5 (String Operations)
### Stringifiable
**Generic Parameters**: None
**Inherits**: None
**Definition**:
```
{
(Self -- String) to_str:
} ::Stringifiable trait
```
**Methods**:
#### to_str:
**Signature**: `(Self -- String)`
**Description**: Convert value to string representation.
**Example**: `42 to_str // => "42"`
**Standard Implementations**: All types
**Related Traits**: Parseable, Convertible
**See Also**: Section 11.5 (Type Conversion)
---
View Git Blame Copy Permalink