YREA-SLS/docs/basic_operations.md

Title	Prev	Next
YREA SLS | 4 Basic Operation	Primitive Types	Functions

4. Basic Operations

4.1 Stack Operations

Stack manipulation is fundamental to the language. All values exist on the stack, and these operations let you rearrange them.

Basic Manipulation

dup         // ( a -- a a ) Duplicate top item
drop        // ( a -- ) Remove top item
swap        // ( a b -- b a ) Swap top two items
over        // ( a b -- a b a ) Copy second item to top
rot         // ( a b c -- b c a) Rotate top three items

Stack Inspection

depth       // ( -- n ) Push current stack depth
pick        // ( n -- x ) Copy nth item to top (0 = top)
roll        // ( n times -- ) Rotate n items, times times

Stack Effect Notation: Throughout this specification, comments use stack effect notation to show what operations consume and produce. The format is // ( before -- after ) where items on the left of -- are consumed from the stack, and items on the right are produced.

Examples:

5 dup        // => 5 5
5 10 swap    // => 10 5
1 2 3 rot    // => 2 3 1
1 2 3 depth  // => 1 2 3 3

Implementation Details: Stack operations implement the ::Stackable trait. See Appendix B for the complete trait definition.

4.2 Arithmetic Operators

Basic arithmetic operations work on numeric types:

3 4 +       // ( a b -- result ) Addition
10 3 -      // ( a b -- result ) Subtraction
5 6 *       // ( a b -- result ) Multiplication
20 4 /      // ( a b -- result ) Division
17 5 %      // ( a b -- result ) Modulo (remainder)
2 8 ^       // ( a b -- result ) Exponentiation
100 log     // ( a -- result ) Logarithm base 10
2.718 ln    // ( a -- result ) Natural logarithm

Examples:

10 5 +      // => 15
10 3 /      // => 3
10 3 %      // => 1
2 10 ^      // => 1024

Implementation Details: Arithmetic operators implement the ::Addable, ::Multiplyable, ::Exponentiable, and ::Logarithmic traits. See Appendix B for complete trait definitions and Appendix C for the full operator reference.

4.3 Comparison Operators

Comparison operations return boolean values:

5 3 >       // ( a b -- bool ) Greater than
5 3 >=      // ( a b -- bool ) Greater or equal
5 3 <       // ( a b -- bool ) Less than
5 3 <=      // ( a b -- bool ) Less or equal
5 5 ==      // ( a b -- bool ) Equal
5 3 !=      // ( a b -- bool ) Not equal

Examples:

10 5 >      // => true
10 10 ==    // => true
10 5 <      // => false

Implementation Details: Comparison operators implement the ::Orderable and ::Equatable traits. See Appendix B for complete trait definitions.

4.4 Logical Operators

Logical operations work with boolean values and truthiness:

true false and    // ( a b -- result ) Logical AND
true false or     // ( a b -- result ) Logical OR
true not          // ( a -- result ) Logical NOT

Truthiness: Non-boolean values can be tested for truthiness. By default, most values are truthy. Numbers are falsy when zero, Option::None is falsy, Result::Err is falsy.

Examples:

true true and     // => true
true false or     // => true
false not         // => true
5 0 and          // => 0 (falsy)

Implementation Details: Logical operators implement the ::Logical trait. See Appendix B for the complete trait definition and truthiness rules.

4.5 Bitwise Operators

Bitwise operations work on integer types:

0xFF 0x0F bitand     // ( a b -- result ) Bitwise AND
0xFF 0x0F bitor      // ( a b -- result ) Bitwise OR
0xFF 0x0F bitxor     // ( a b -- result ) Bitwise XOR
0xFF bitnot          // ( a -- result ) Bitwise NOT
8 2 shl              // ( a n -- result ) Left shift
8 2 shr              // ( a n -- result ) Right shift

Examples:

0xFF 0x0F bitand    // => 0x0F
0xF0 0x0F bitor     // => 0xFF
0xFF bitnot         // => 0xFFFFFFFFFFFFFF00 (on 64-bit)
4 2 shl             // => 16

Implementation Details: Bitwise operators implement the ::Bitwise trait. See Appendix B for the complete trait definition.

---