162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
# Working with numbers and floats in Fun
|
||
|
||
This guide covers the numeric types in Fun, with a focus on the integer "number" type and the 64‑bit floating point "float" type. You’ll find creation, arithmetic, conversion, clamping, bitwise operations, and common patterns.
|
||
|
||
## TL;DR
|
||
|
||
- number = signed integer; float = 64‑bit floating point.
|
||
- Use +, -, *, / for arithmetic. If you need fractional results, make at least one operand a float.
|
||
- Modulo: a % b. Integer division with / may discard the fractional part; cast to float to preserve it.
|
||
- Convert/parse: to_number("123"), to_string(x), cast(x, "float"), cast(x, "number").
|
||
- Clamp to widths when interfacing with external code: uclamp(n, bits), sclamp(n, bits).
|
||
- Bitwise (numbers only): &, |, ^, ~, <<, >>.
|
||
|
||
## Numeric types at a glance
|
||
|
||
- number: signed integer (implementation‑defined width; use uclamp/sclamp for fixed‑width interop)
|
||
- float: IEEE‑754 double precision (64‑bit)
|
||
|
||
```
|
||
an = 42 // number
|
||
af = 3.14159 // float
|
||
print(typeof(an)) // "number"
|
||
print(typeof(af)) // "float"
|
||
```
|
||
|
||
## Literals
|
||
|
||
- Integer (number): 0, 1, -7, 120
|
||
- Floating point (float): 0.0, 1.5, -2.75, 1e3, -4.2e-1
|
||
|
||
```
|
||
x = 10
|
||
y = 2.5
|
||
z = -3
|
||
```
|
||
|
||
## Arithmetic
|
||
|
||
Basic arithmetic works as you’d expect:
|
||
|
||
```
|
||
a = 7
|
||
b = 2
|
||
print(a + b) // 9
|
||
print(a - b) // 5
|
||
print(a * b) // 14
|
||
print(a % b) // 1 (modulo)
|
||
```
|
||
|
||
Division and result type:
|
||
|
||
```
|
||
// If you need a fractional result, ensure a float is involved
|
||
print(7 / 2) // implementation may yield 3 or 3.5 depending on numeric rules
|
||
print(cast(7, "float") / 2) // 3.5 (recommended when you need fractions)
|
||
print(7 / 2.0) // 3.5
|
||
```
|
||
|
||
Mixing numbers and floats promotes the operation to float semantics:
|
||
|
||
```
|
||
print(2 + 0.5) // 2.5
|
||
```
|
||
|
||
## Comparisons
|
||
|
||
```
|
||
print(3 < 5) // 1 (true)
|
||
print(3 == 3) // 1
|
||
print(3 != 4) // 1
|
||
|
||
// Be explicit when comparing ints vs floats if types matter
|
||
print(1 == 1.0) // may be true, but types differ
|
||
print(cast(1.0, "number") == 1) // 1 (true) with explicit cast
|
||
```
|
||
|
||
## Conversions and parsing
|
||
|
||
```
|
||
n = to_number("123") // 123 (number)
|
||
f = cast(n, "float") // 123.0 (float)
|
||
n2 = cast(3.9, "number") // 3 (truncation semantics)
|
||
print(to_string(f)) // "123"
|
||
```
|
||
|
||
If parsing fails (e.g., to_number("abc")), expect a runtime error; guard accordingly.
|
||
|
||
## Clamping to fixed widths
|
||
|
||
When interoperating with bytecode, C APIs, or binary formats, clamp integers to a specific bit width.
|
||
|
||
```
|
||
// Unsigned clamp to N bits
|
||
u8 = uclamp(300, 8) // 44
|
||
u16 = uclamp(70000, 16)
|
||
|
||
// Signed clamp to N bits
|
||
s8 = sclamp(-130, 8) // wraps into signed 8‑bit range
|
||
```
|
||
|
||
Choose the bits according to the target field (8, 16, 32, 64). See your interop API docs for exact ranges.
|
||
|
||
## Bitwise operations (numbers)
|
||
|
||
Bitwise operators apply to the integer number type.
|
||
|
||
```
|
||
a = 0b0110 // if binary literals aren’t supported in your setup, use decimals: a = 6
|
||
b = 0b0011 // or b = 3
|
||
|
||
print(a & b) // 0b0010 -> 2
|
||
print(a | b) // 0b0111 -> 7
|
||
print(a ^ b) // 0b0101 -> 5
|
||
print(~a) // bitwise NOT (two’s complement rules)
|
||
print(a << 1) // 12
|
||
print(a >> 1) // 3
|
||
```
|
||
|
||
Note: Bitwise ops are defined for numbers, not floats. Cast floats to numbers first when needed.
|
||
|
||
## Common patterns
|
||
|
||
Ensuring float math to avoid unintended truncation:
|
||
|
||
```
|
||
avg = cast(sum, "float") / cast(count, "float")
|
||
```
|
||
|
||
Safe division with guard against zero:
|
||
|
||
```
|
||
num = 10
|
||
den = 0
|
||
if den == 0 {
|
||
print("division by zero")
|
||
} else {
|
||
print(num / den)
|
||
}
|
||
```
|
||
|
||
Parsing user input with fallback:
|
||
|
||
```
|
||
raw = "not-a-number"
|
||
val = 0
|
||
// simplistic guard pattern; adapt to your error handling style
|
||
if find(raw, "0") >= 0 || find(raw, "1") >= 0 { // crude pre-check
|
||
val = to_number(raw)
|
||
}
|
||
```
|
||
|
||
## Gotchas
|
||
|
||
- Integer division vs float division: promote to float when you need fractional results.
|
||
- Overflow/underflow: clamp explicitly when targeting fixed‑width fields; otherwise values follow the VM’s integer semantics.
|
||
- Bitwise with negatives uses two’s complement; ~x equals -(x+1).
|
||
|
||
## See also
|
||
|
||
- Core overview: [types.md](./types.md)
|
||
- Math helpers and advanced ops: check [math/opcodes](./opcodes.md) and the vm/math sources for available functions.
|
||
- Strings: [strings.md](./strings.md)
|