---
Title: 4 Basic Operations
Prev: Primitive Types
Next: 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](./complete_trait_reference.html) 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](./complete_trait_reference.html) for complete trait definitions and [Appendix C](./complete_operator_reference.html) 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](./complete_trait_reference.html) 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](./complete_trait_reference.html) 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](./complete_trait_reference.html) 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).

---