hanez/fun
1
0
Fork 0
forked from fun/fun
Code Pull requests Activity

Holiday is over, now I have fun again. No code changes. (0.38.11)

Browse source
This commit is contained in:
Johannes Findeisen 2026-02-17 14:59:39 +01:00
commit eaf5f88dc0
4 changed files with 270 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/README.md
View file

@ -6,6 +6,8 @@ This file serves as an index of the documents in this directory. Links are relat
- [handbook.md](./handbook.md) — Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview.
- [types.md](./types.md) — Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes.
- [numbers.md](./numbers.md) — Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns.
- [strings.md](./strings.md) — Working with strings: literals/escaping, concatenation, substr/find, split, and conversions.
- [arrays.md](./arrays.md) — Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms.
- [maps.md](./maps.md) — Working with maps: construction, lookup/update, merging, iteration, and common patterns.
- [includes.md](./includes.md) — Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`.

162
docs/numbers.md Normal file
View file

@ -0,0 +1,162 @@
# 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)

99
docs/strings.md Normal file
View file

@ -0,0 +1,99 @@
# Working with strings in Fun
This guide covers string literals, common operations (length, concatenation, substring, search, split), and interop patterns. Strings in Fun are immutable sequences of bytes/text.
## TL;DR
- Create with quotes: s = "hello". Escape with \n, \t, \", \\.
- Concatenate with +. Convert non-strings with to_string(x).
- Length: len(s). Substring: substr(s, start, length).
- Find index: find(s, needle) → 0-based index or -1 if not found.
- Split CSV: split("a,b,c", ",") → ["a","b","c"].
## Literals and escaping
```
s1 = "hello"
s2 = "line1\nline2" // newline
s3 = "quote: \" and backslash: \\" // escaped quote and backslash
print(s1) // hello
```
Notes:
- Strings are immutable; operations return new strings rather than modifying in place.
- Use to_string(x) when concatenating non-string values.
## Basic operations
Length and concatenation:
```
name = "Ada"
greet = "Hello, " + name + "!" // "Hello, Ada!"
print(len(greet)) // 12
```
Substring (start, length) and search:
```
s = "hello, world"
print(substr(s, 7, 5)) // world
idx = find(s, ",") // 5, or -1 if not found
if idx >= 0 { print("comma at index " + to_string(idx)) }
```
Splitting into arrays:
```
parts = split("a,b,c", ",") // ["a","b","c"]
for i = 0; i < len(parts); i = i + 1 {
print(parts[i])
}
```
## Conversions and formatting
```
n = 42
pi = 3.14
msg = "n=" + to_string(n) + ", pi=" + to_string(pi)
print(msg)
// parsing (may error if the string is not numeric)
n2 = to_number("123") // 123
```
If you need a specific type, you can use cast for advanced cases, e.g. cast("123", "number").
## Common patterns
- Guard on find results before slicing:
```
email = "user@example.org"
at = find(email, "@")
if at >= 0 {
user = substr(email, 0, at)
host = substr(email, at + 1, len(email) - at - 1)
print(user + " on " + host)
}
```
- Building paths or messages:
```
base = "/tmp"
file = "log.txt"
path = base + "/" + file
```
## Gotchas
- Strings are immutable: repeated concatenation in big loops can be costly; consider collecting pieces in an array and joining at the end if you have a helper for that in your setup.
- len(s) counts bytes/code units; be mindful when working with multi-byte encodings.
## See also
- Core overview: [types.md](./types.md)
- Arrays guide (useful when splitting/collecting text): [arrays.md](./arrays.md)

7
docs/types.md
View file

@ -2,6 +2,13 @@
This guide shows how to create and use the most common Fun datatypes with practical examples. It focuses on arrays and maps, and also recaps numbers, floats, strings, booleans and nil so examples are self‑contained.
See also:
- [arrays.md](./arrays.md) — Deeper dive into array creation, indexing/slicing, iteration, and helpers.
- [strings.md](./strings.md) — Practical guide to string literals, concatenation, substr/find, split, and conversions.
- [maps.md](./maps.md) — Detailed guide to map construction, lookup/update, merging, and patterns.
- [numbers.md](./numbers.md) — Numbers vs floats, arithmetic, conversions, clamping, bitwise ops, and common patterns.
## Quick overview
- number: signed integer (use uclamp/sclamp for width handling)