177 lines
5.6 KiB
Markdown
177 lines
5.6 KiB
Markdown
---
|
|
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).
|
|
|
|
---
|