---
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
```

**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](./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.

---