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

Mathematical Functions:

16 sqrt     // ( a -- result ) Square root
-5 abs      // ( a -- result ) Absolute value
0.0 sin     // ( a -- result ) Sine (radians)
0.0 cos     // ( a -- result ) Cosine (radians)
0.0 tan     // ( a -- result ) Tangent (radians)
1.0 asin    // ( a -- result ) Arc sine
1.0 acos    // ( a -- result ) Arc cosine
1.0 atan    // ( a -- result ) Arc tangent
1.0 0.0 atan2  // ( y x -- result ) Two-argument arc tangent
3.14 floor  // ( a -- result ) Round down
3.14 ceil   // ( a -- result ) Round up
3.14 round  // ( a -- result ) Round to nearest
3 5 min     // ( a b -- result ) Minimum of two values
3 5 max     // ( a b -- result ) Maximum of two values

Examples:

10 5 +      // => 15
10 3 /      // => 3
10 3 %      // => 1
2 10 ^      // => 1024
16 sqrt     // => 4.0
-42 abs     // => 42
3.14159 sin // => ~0.0
3.7 round   // => 4.0

Implementation Details: Arithmetic operators implement the ::Addable, ::Multiplyable, ::Exponentiable, ::Logarithmic, and ::Math 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.

4.6 Randomness¶

Random number generation is provided through built-in operators:

rand        // ( -- f64 ) Generate random f64 in range [0.0, 1.0)
seed        // ( u64 -- ) Seed the random number generator

Examples:

rand                    // => 0.7234... (random value)
12345 seed              // Seed RNG with specific value
rand                    // => 0.4321... (deterministic after seed)

// Random integer in range
100 rand * floor        // Random integer 0-99

Implementation Note: The specific random number generation algorithm is implementation-defined but should be a high-quality PRNG suitable for general use (not cryptography).