docs revamp
This commit is contained in:
10
docs/library/.pages
Normal file
10
docs/library/.pages
Normal file
@@ -0,0 +1,10 @@
|
||||
nav:
|
||||
- text.md
|
||||
- number.md
|
||||
- array.md
|
||||
- object.md
|
||||
- blob.md
|
||||
- time.md
|
||||
- math.md
|
||||
- json.md
|
||||
- random.md
|
||||
151
docs/library/array.md
Normal file
151
docs/library/array.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# array
|
||||
|
||||
The `array` function and its methods handle array creation and manipulation.
|
||||
|
||||
## Creation
|
||||
|
||||
### array(number)
|
||||
|
||||
Create an array of specified size, filled with `null`.
|
||||
|
||||
```javascript
|
||||
array(3) // [null, null, null]
|
||||
```
|
||||
|
||||
### array(number, initial)
|
||||
|
||||
Create an array with initial values.
|
||||
|
||||
```javascript
|
||||
array(3, 0) // [0, 0, 0]
|
||||
array(3, i => i * 2) // [0, 2, 4]
|
||||
```
|
||||
|
||||
### array(array)
|
||||
|
||||
Copy an array.
|
||||
|
||||
```javascript
|
||||
var copy = array(original)
|
||||
```
|
||||
|
||||
### array(array, from, to)
|
||||
|
||||
Slice an array.
|
||||
|
||||
```javascript
|
||||
array([1, 2, 3, 4, 5], 1, 4) // [2, 3, 4]
|
||||
array([1, 2, 3], -2) // [2, 3]
|
||||
```
|
||||
|
||||
### array(array, another)
|
||||
|
||||
Concatenate arrays.
|
||||
|
||||
```javascript
|
||||
array([1, 2], [3, 4]) // [1, 2, 3, 4]
|
||||
```
|
||||
|
||||
### array(object)
|
||||
|
||||
Get keys of an object.
|
||||
|
||||
```javascript
|
||||
array({a: 1, b: 2}) // ["a", "b"]
|
||||
```
|
||||
|
||||
### array(text)
|
||||
|
||||
Split text into grapheme clusters.
|
||||
|
||||
```javascript
|
||||
array("hello") // ["h", "e", "l", "l", "o"]
|
||||
array("👨👩👧") // ["👨👩👧"]
|
||||
```
|
||||
|
||||
### array(text, separator)
|
||||
|
||||
Split text by separator.
|
||||
|
||||
```javascript
|
||||
array("a,b,c", ",") // ["a", "b", "c"]
|
||||
```
|
||||
|
||||
### array(text, length)
|
||||
|
||||
Split text into chunks.
|
||||
|
||||
```javascript
|
||||
array("abcdef", 2) // ["ab", "cd", "ef"]
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### array.for(arr, fn, reverse, exit)
|
||||
|
||||
Iterate over elements.
|
||||
|
||||
```javascript
|
||||
array.for([1, 2, 3], function(el, i) {
|
||||
log.console(i, el)
|
||||
})
|
||||
|
||||
// With early exit
|
||||
array.for([1, 2, 3, 4], function(el) {
|
||||
if (el > 2) return true
|
||||
log.console(el)
|
||||
}, false, true) // prints 1, 2
|
||||
```
|
||||
|
||||
### array.find(arr, fn, reverse, from)
|
||||
|
||||
Find element index.
|
||||
|
||||
```javascript
|
||||
array.find([1, 2, 3], 2) // 1
|
||||
array.find([1, 2, 3], x => x > 1) // 1
|
||||
array.find([1, 2, 3], x => x > 1, true) // 2 (from end)
|
||||
```
|
||||
|
||||
### array.filter(arr, fn)
|
||||
|
||||
Filter elements.
|
||||
|
||||
```javascript
|
||||
array.filter([1, 2, 3, 4], x => x % 2 == 0) // [2, 4]
|
||||
```
|
||||
|
||||
### array.reduce(arr, fn, initial, reverse)
|
||||
|
||||
Reduce to single value.
|
||||
|
||||
```javascript
|
||||
array.reduce([1, 2, 3, 4], (a, b) => a + b) // 10
|
||||
array.reduce([1, 2, 3, 4], (a, b) => a + b, 10) // 20
|
||||
```
|
||||
|
||||
### array.sort(arr, select)
|
||||
|
||||
Sort array (returns new array).
|
||||
|
||||
```javascript
|
||||
array.sort([3, 1, 4, 1, 5]) // [1, 1, 3, 4, 5]
|
||||
|
||||
// Sort by field
|
||||
array.sort([{n: 3}, {n: 1}], "n") // [{n: 1}, {n: 3}]
|
||||
|
||||
// Sort by index
|
||||
array.sort([[3, "c"], [1, "a"]], 0) // [[1, "a"], [3, "c"]]
|
||||
```
|
||||
|
||||
## Map with array()
|
||||
|
||||
The `array(arr, fn)` form maps over elements:
|
||||
|
||||
```javascript
|
||||
array([1, 2, 3], x => x * 2) // [2, 4, 6]
|
||||
|
||||
array([1, 2, 3], function(el, i) {
|
||||
return el + i
|
||||
}) // [1, 3, 5]
|
||||
```
|
||||
182
docs/library/blob.md
Normal file
182
docs/library/blob.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# blob
|
||||
|
||||
Blobs are binary large objects — containers of bits (not bytes). They're used for encoding data, messages, images, network payloads, and more.
|
||||
|
||||
## States
|
||||
|
||||
A blob exists in one of two states:
|
||||
|
||||
- **antestone** (mutable) — write operations allowed
|
||||
- **stone** (immutable) — read operations allowed
|
||||
|
||||
```javascript
|
||||
var blob = use('blob')
|
||||
|
||||
var b = blob.make() // antestone
|
||||
blob.write_bit(b, 1)
|
||||
blob.write_fit(b, 42, 8)
|
||||
stone(b) // now stone, readable
|
||||
```
|
||||
|
||||
## Creation
|
||||
|
||||
### blob.make()
|
||||
|
||||
Create an empty blob.
|
||||
|
||||
```javascript
|
||||
var b = blob.make()
|
||||
```
|
||||
|
||||
### blob.make(capacity)
|
||||
|
||||
Create with initial capacity (bits).
|
||||
|
||||
```javascript
|
||||
var b = blob.make(1024) // 1024 bits capacity
|
||||
```
|
||||
|
||||
### blob.make(length, logical)
|
||||
|
||||
Create filled with zeros or ones.
|
||||
|
||||
```javascript
|
||||
blob.make(64, false) // 64 zero bits
|
||||
blob.make(64, true) // 64 one bits
|
||||
```
|
||||
|
||||
### blob.make(blob, from, to)
|
||||
|
||||
Copy a range from another blob.
|
||||
|
||||
```javascript
|
||||
var slice = blob.make(original, 0, 32) // first 32 bits
|
||||
```
|
||||
|
||||
## Writing (antestone only)
|
||||
|
||||
### blob.write_bit(b, logical)
|
||||
|
||||
Append a single bit.
|
||||
|
||||
```javascript
|
||||
blob.write_bit(b, true) // append 1
|
||||
blob.write_bit(b, false) // append 0
|
||||
```
|
||||
|
||||
### blob.write_fit(b, value, length)
|
||||
|
||||
Append a fixed-width integer.
|
||||
|
||||
```javascript
|
||||
blob.write_fit(b, 255, 8) // 8-bit value
|
||||
blob.write_fit(b, 1000, 16) // 16-bit value
|
||||
```
|
||||
|
||||
### blob.write_blob(b, other)
|
||||
|
||||
Append another blob's contents.
|
||||
|
||||
```javascript
|
||||
blob.write_blob(b, other_blob)
|
||||
```
|
||||
|
||||
### blob.write_dec64(b, number)
|
||||
|
||||
Append a 64-bit DEC64 number.
|
||||
|
||||
```javascript
|
||||
blob.write_dec64(b, 3.14159)
|
||||
```
|
||||
|
||||
### blob.write_text(b, text)
|
||||
|
||||
Append text (kim-encoded length + characters).
|
||||
|
||||
```javascript
|
||||
blob.write_text(b, "hello")
|
||||
```
|
||||
|
||||
### blob.write_pad(b, block_size)
|
||||
|
||||
Pad to block boundary (1 bit + zeros).
|
||||
|
||||
```javascript
|
||||
blob.write_pad(b, 8) // pad to byte boundary
|
||||
```
|
||||
|
||||
## Reading (stone only)
|
||||
|
||||
### blob.read_logical(b, from)
|
||||
|
||||
Read a single bit.
|
||||
|
||||
```javascript
|
||||
var bit = blob.read_logical(b, 0) // first bit
|
||||
```
|
||||
|
||||
### blob.read_fit(b, from, length)
|
||||
|
||||
Read a fixed-width integer.
|
||||
|
||||
```javascript
|
||||
var value = blob.read_fit(b, 0, 8) // read 8 bits from position 0
|
||||
```
|
||||
|
||||
### blob.read_blob(b, from, to)
|
||||
|
||||
Extract a range as new blob.
|
||||
|
||||
```javascript
|
||||
var slice = blob.read_blob(b, 8, 24) // bits 8-23
|
||||
```
|
||||
|
||||
### blob.read_dec64(b, from)
|
||||
|
||||
Read a 64-bit DEC64 number.
|
||||
|
||||
```javascript
|
||||
var num = blob.read_dec64(b, 0)
|
||||
```
|
||||
|
||||
### blob.read_text(b, from)
|
||||
|
||||
Read kim-encoded text.
|
||||
|
||||
```javascript
|
||||
var str = blob.read_text(b, 0)
|
||||
```
|
||||
|
||||
### blob.pad?(b, from, block_size)
|
||||
|
||||
Check if padding is valid.
|
||||
|
||||
```javascript
|
||||
if (blob["pad?"](b, pos, 8)) {
|
||||
// valid byte-aligned padding
|
||||
}
|
||||
```
|
||||
|
||||
## Length
|
||||
|
||||
```javascript
|
||||
length(b) // returns bit count
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```javascript
|
||||
var blob = use('blob')
|
||||
|
||||
// Encode a simple message
|
||||
var msg = blob.make()
|
||||
blob.write_fit(msg, 1, 8) // message type
|
||||
blob.write_fit(msg, 42, 32) // payload
|
||||
blob.write_text(msg, "hello") // text data
|
||||
stone(msg)
|
||||
|
||||
// Decode
|
||||
var type = blob.read_fit(msg, 0, 8)
|
||||
var payload = blob.read_fit(msg, 8, 32)
|
||||
var txt = blob.read_text(msg, 40)
|
||||
```
|
||||
90
docs/library/json.md
Normal file
90
docs/library/json.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# json
|
||||
|
||||
JSON encoding and decoding.
|
||||
|
||||
```javascript
|
||||
var json = use('json')
|
||||
```
|
||||
|
||||
## Encoding
|
||||
|
||||
### json.encode(value, space, replacer, whitelist)
|
||||
|
||||
Convert a value to JSON text.
|
||||
|
||||
```javascript
|
||||
json.encode({a: 1, b: 2})
|
||||
// '{"a":1,"b":2}'
|
||||
|
||||
// Pretty print with 2-space indent
|
||||
json.encode({a: 1, b: 2}, 2)
|
||||
// '{
|
||||
// "a": 1,
|
||||
// "b": 2
|
||||
// }'
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- **value** — the value to encode
|
||||
- **space** — indentation (number of spaces or string)
|
||||
- **replacer** — function to transform values
|
||||
- **whitelist** — array of keys to include
|
||||
|
||||
```javascript
|
||||
// With replacer
|
||||
json.encode({a: 1, b: 2}, null, function(key, value) {
|
||||
if (key == "b") return value * 10
|
||||
return value
|
||||
})
|
||||
// '{"a":1,"b":20}'
|
||||
|
||||
// With whitelist
|
||||
json.encode({a: 1, b: 2, c: 3}, null, null, ["a", "c"])
|
||||
// '{"a":1,"c":3}'
|
||||
```
|
||||
|
||||
## Decoding
|
||||
|
||||
### json.decode(text, reviver)
|
||||
|
||||
Parse JSON text to a value.
|
||||
|
||||
```javascript
|
||||
json.decode('{"a":1,"b":2}')
|
||||
// {a: 1, b: 2}
|
||||
|
||||
json.decode('[1, 2, 3]')
|
||||
// [1, 2, 3]
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- **text** — JSON string to parse
|
||||
- **reviver** — function to transform parsed values
|
||||
|
||||
```javascript
|
||||
// With reviver
|
||||
json.decode('{"date":"2024-01-15"}', function(key, value) {
|
||||
if (key == "date") return parse_date(value)
|
||||
return value
|
||||
})
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```javascript
|
||||
var json = use('json')
|
||||
|
||||
// Save configuration
|
||||
var config = {
|
||||
debug: true,
|
||||
maxRetries: 3,
|
||||
endpoints: ["api.example.com"]
|
||||
}
|
||||
var config_text = json.encode(config, 2)
|
||||
|
||||
// Load configuration
|
||||
var loaded = json.decode(config_text)
|
||||
log.console(loaded.debug) // true
|
||||
```
|
||||
153
docs/library/math.md
Normal file
153
docs/library/math.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# math
|
||||
|
||||
Cell provides three math modules with identical functions but different angle representations:
|
||||
|
||||
```javascript
|
||||
var math = use('math/radians') // angles in radians
|
||||
var math = use('math/degrees') // angles in degrees
|
||||
var math = use('math/cycles') // angles in cycles (0-1)
|
||||
```
|
||||
|
||||
## Trigonometry
|
||||
|
||||
### sine(angle)
|
||||
|
||||
```javascript
|
||||
math.sine(math.pi / 2) // 1 (radians)
|
||||
math.sine(90) // 1 (degrees)
|
||||
math.sine(0.25) // 1 (cycles)
|
||||
```
|
||||
|
||||
### cosine(angle)
|
||||
|
||||
```javascript
|
||||
math.cosine(0) // 1
|
||||
```
|
||||
|
||||
### tangent(angle)
|
||||
|
||||
```javascript
|
||||
math.tangent(math.pi / 4) // 1 (radians)
|
||||
```
|
||||
|
||||
### arc_sine(n)
|
||||
|
||||
Inverse sine.
|
||||
|
||||
```javascript
|
||||
math.arc_sine(1) // π/2 (radians)
|
||||
```
|
||||
|
||||
### arc_cosine(n)
|
||||
|
||||
Inverse cosine.
|
||||
|
||||
```javascript
|
||||
math.arc_cosine(0) // π/2 (radians)
|
||||
```
|
||||
|
||||
### arc_tangent(n, denominator)
|
||||
|
||||
Inverse tangent. With two arguments, computes atan2.
|
||||
|
||||
```javascript
|
||||
math.arc_tangent(1) // π/4 (radians)
|
||||
math.arc_tangent(1, 1) // π/4 (radians)
|
||||
math.arc_tangent(-1, -1) // -3π/4 (radians)
|
||||
```
|
||||
|
||||
## Exponentials and Logarithms
|
||||
|
||||
### e(power)
|
||||
|
||||
Euler's number raised to a power. Default power is 1.
|
||||
|
||||
```javascript
|
||||
math.e() // 2.718281828...
|
||||
math.e(2) // e²
|
||||
```
|
||||
|
||||
### ln(n)
|
||||
|
||||
Natural logarithm (base e).
|
||||
|
||||
```javascript
|
||||
math.ln(math.e()) // 1
|
||||
```
|
||||
|
||||
### log(n)
|
||||
|
||||
Base 10 logarithm.
|
||||
|
||||
```javascript
|
||||
math.log(100) // 2
|
||||
```
|
||||
|
||||
### log2(n)
|
||||
|
||||
Base 2 logarithm.
|
||||
|
||||
```javascript
|
||||
math.log2(8) // 3
|
||||
```
|
||||
|
||||
## Powers and Roots
|
||||
|
||||
### power(base, exponent)
|
||||
|
||||
```javascript
|
||||
math.power(2, 10) // 1024
|
||||
```
|
||||
|
||||
### sqrt(n)
|
||||
|
||||
Square root.
|
||||
|
||||
```javascript
|
||||
math.sqrt(16) // 4
|
||||
```
|
||||
|
||||
### root(radicand, n)
|
||||
|
||||
Nth root.
|
||||
|
||||
```javascript
|
||||
math.root(27, 3) // 3 (cube root)
|
||||
```
|
||||
|
||||
## Constants
|
||||
|
||||
Available in the radians module:
|
||||
|
||||
```javascript
|
||||
math.pi // 3.14159...
|
||||
math.e() // 2.71828...
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```javascript
|
||||
var math = use('math/radians')
|
||||
|
||||
// Distance between two points
|
||||
function distance(x1, y1, x2, y2) {
|
||||
var dx = x2 - x1
|
||||
var dy = y2 - y1
|
||||
return math.sqrt(dx * dx + dy * dy)
|
||||
}
|
||||
|
||||
// Angle between two points
|
||||
function angle(x1, y1, x2, y2) {
|
||||
return math.arc_tangent(y2 - y1, x2 - x1)
|
||||
}
|
||||
|
||||
// Rotate a point
|
||||
function rotate(x, y, angle) {
|
||||
var c = math.cosine(angle)
|
||||
var s = math.sine(angle)
|
||||
return {
|
||||
x: x * c - y * s,
|
||||
y: x * s + y * c
|
||||
}
|
||||
}
|
||||
```
|
||||
143
docs/library/number.md
Normal file
143
docs/library/number.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# number
|
||||
|
||||
The `number` function and its methods handle numeric conversion and operations.
|
||||
|
||||
## Conversion
|
||||
|
||||
### number(logical)
|
||||
|
||||
Convert boolean to number.
|
||||
|
||||
```javascript
|
||||
number(true) // 1
|
||||
number(false) // 0
|
||||
```
|
||||
|
||||
### number(text, radix)
|
||||
|
||||
Parse text to number. Radix is 2-36 (default: 10).
|
||||
|
||||
```javascript
|
||||
number("42") // 42
|
||||
number("ff", 16) // 255
|
||||
number("1010", 2) // 10
|
||||
```
|
||||
|
||||
### number(text, format)
|
||||
|
||||
Parse formatted numbers.
|
||||
|
||||
| Format | Description |
|
||||
|--------|-------------|
|
||||
| `""` | Standard decimal |
|
||||
| `"u"` | Underbar separator (1_000) |
|
||||
| `"d"` | Comma separator (1,000) |
|
||||
| `"s"` | Space separator (1 000) |
|
||||
| `"v"` | European (1.000,50) |
|
||||
| `"b"` | Binary |
|
||||
| `"o"` | Octal |
|
||||
| `"h"` | Hexadecimal |
|
||||
| `"j"` | JavaScript style (0x, 0o, 0b prefixes) |
|
||||
|
||||
```javascript
|
||||
number("1,000", "d") // 1000
|
||||
number("0xff", "j") // 255
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### number.abs(n)
|
||||
|
||||
Absolute value.
|
||||
|
||||
```javascript
|
||||
number.abs(-5) // 5
|
||||
number.abs(5) // 5
|
||||
```
|
||||
|
||||
### number.sign(n)
|
||||
|
||||
Returns -1, 0, or 1.
|
||||
|
||||
```javascript
|
||||
number.sign(-5) // -1
|
||||
number.sign(0) // 0
|
||||
number.sign(5) // 1
|
||||
```
|
||||
|
||||
### number.floor(n, place)
|
||||
|
||||
Round down.
|
||||
|
||||
```javascript
|
||||
number.floor(4.9) // 4
|
||||
number.floor(4.567, 2) // 4.56
|
||||
```
|
||||
|
||||
### number.ceiling(n, place)
|
||||
|
||||
Round up.
|
||||
|
||||
```javascript
|
||||
number.ceiling(4.1) // 5
|
||||
number.ceiling(4.123, 2) // 4.13
|
||||
```
|
||||
|
||||
### number.round(n, place)
|
||||
|
||||
Round to nearest.
|
||||
|
||||
```javascript
|
||||
number.round(4.5) // 5
|
||||
number.round(4.567, 2) // 4.57
|
||||
```
|
||||
|
||||
### number.trunc(n, place)
|
||||
|
||||
Truncate toward zero.
|
||||
|
||||
```javascript
|
||||
number.trunc(4.9) // 4
|
||||
number.trunc(-4.9) // -4
|
||||
```
|
||||
|
||||
### number.whole(n)
|
||||
|
||||
Get the integer part.
|
||||
|
||||
```javascript
|
||||
number.whole(4.9) // 4
|
||||
number.whole(-4.9) // -4
|
||||
```
|
||||
|
||||
### number.fraction(n)
|
||||
|
||||
Get the fractional part.
|
||||
|
||||
```javascript
|
||||
number.fraction(4.75) // 0.75
|
||||
```
|
||||
|
||||
### number.min(...values)
|
||||
|
||||
Return the smallest value.
|
||||
|
||||
```javascript
|
||||
number.min(3, 1, 4, 1, 5) // 1
|
||||
```
|
||||
|
||||
### number.max(...values)
|
||||
|
||||
Return the largest value.
|
||||
|
||||
```javascript
|
||||
number.max(3, 1, 4, 1, 5) // 5
|
||||
```
|
||||
|
||||
### number.remainder(dividend, divisor)
|
||||
|
||||
Compute remainder.
|
||||
|
||||
```javascript
|
||||
number.remainder(17, 5) // 2
|
||||
```
|
||||
112
docs/library/object.md
Normal file
112
docs/library/object.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# object
|
||||
|
||||
The `object` function and related utilities handle object creation and manipulation.
|
||||
|
||||
## Creation
|
||||
|
||||
### object(obj)
|
||||
|
||||
Shallow copy an object.
|
||||
|
||||
```javascript
|
||||
var copy = object(original)
|
||||
```
|
||||
|
||||
### object(obj, another)
|
||||
|
||||
Combine two objects.
|
||||
|
||||
```javascript
|
||||
object({a: 1}, {b: 2}) // {a: 1, b: 2}
|
||||
object({a: 1}, {a: 2}) // {a: 2}
|
||||
```
|
||||
|
||||
### object(obj, keys)
|
||||
|
||||
Select specific keys.
|
||||
|
||||
```javascript
|
||||
object({a: 1, b: 2, c: 3}, ["a", "c"]) // {a: 1, c: 3}
|
||||
```
|
||||
|
||||
### object(keys)
|
||||
|
||||
Create object from keys (values are `true`).
|
||||
|
||||
```javascript
|
||||
object(["a", "b", "c"]) // {a: true, b: true, c: true}
|
||||
```
|
||||
|
||||
### object(keys, value)
|
||||
|
||||
Create object from keys with specified value.
|
||||
|
||||
```javascript
|
||||
object(["a", "b"], 0) // {a: 0, b: 0}
|
||||
```
|
||||
|
||||
### object(keys, fn)
|
||||
|
||||
Create object from keys with computed values.
|
||||
|
||||
```javascript
|
||||
object(["a", "b", "c"], (k, i) => i) // {a: 0, b: 1, c: 2}
|
||||
```
|
||||
|
||||
## Prototypes
|
||||
|
||||
### meme(prototype)
|
||||
|
||||
Create a new object with the given prototype.
|
||||
|
||||
```javascript
|
||||
var animal = {speak: function() { log.console("...") }}
|
||||
var dog = meme(animal)
|
||||
dog.speak = function() { log.console("woof") }
|
||||
```
|
||||
|
||||
### proto(obj)
|
||||
|
||||
Get an object's prototype.
|
||||
|
||||
```javascript
|
||||
var p = proto(dog) // animal
|
||||
```
|
||||
|
||||
### isa(obj, prototype)
|
||||
|
||||
Check if prototype is in the chain.
|
||||
|
||||
```javascript
|
||||
isa(dog, animal) // true
|
||||
```
|
||||
|
||||
## Serialization
|
||||
|
||||
### splat(obj)
|
||||
|
||||
Flatten an object's prototype chain into a plain object. Only includes primitive types (numbers, text, booleans, arrays, objects).
|
||||
|
||||
```javascript
|
||||
var base = {x: 1}
|
||||
var derived = meme(base)
|
||||
derived.y = 2
|
||||
|
||||
splat(derived) // {x: 1, y: 2}
|
||||
```
|
||||
|
||||
When sending objects between actors with `$send`, they are automatically splatted.
|
||||
|
||||
## Key Iteration
|
||||
|
||||
```javascript
|
||||
var obj = {a: 1, b: 2, c: 3}
|
||||
|
||||
// Get all keys
|
||||
var keys = array(obj) // ["a", "b", "c"]
|
||||
|
||||
// Iterate
|
||||
for (var key in obj) {
|
||||
log.console(key, obj[key])
|
||||
}
|
||||
```
|
||||
71
docs/library/random.md
Normal file
71
docs/library/random.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# random
|
||||
|
||||
Random number generation.
|
||||
|
||||
```javascript
|
||||
var random = use('random')
|
||||
```
|
||||
|
||||
## Functions
|
||||
|
||||
### random.random()
|
||||
|
||||
Returns a number between 0 (inclusive) and 1 (exclusive).
|
||||
|
||||
```javascript
|
||||
random.random() // e.g., 0.7234...
|
||||
```
|
||||
|
||||
### random.random_fit()
|
||||
|
||||
Returns a random 56-bit integer in the range -36028797018963968 to 36028797018963967.
|
||||
|
||||
```javascript
|
||||
random.random_fit() // e.g., 12345678901234
|
||||
```
|
||||
|
||||
### random.random_whole(max)
|
||||
|
||||
Returns a whole number from 0 (inclusive) to max (exclusive).
|
||||
|
||||
```javascript
|
||||
random.random_whole(10) // 0-9
|
||||
random.random_whole(100) // 0-99
|
||||
random.random_whole(6) + 1 // dice roll: 1-6
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```javascript
|
||||
var random = use('random')
|
||||
|
||||
// Random boolean
|
||||
var coin_flip = random.random() < 0.5
|
||||
|
||||
// Random element from array
|
||||
function pick(arr) {
|
||||
return arr[random.random_whole(length(arr))]
|
||||
}
|
||||
|
||||
var colors = ["red", "green", "blue"]
|
||||
var color = pick(colors)
|
||||
|
||||
// Shuffle array
|
||||
function shuffle(arr) {
|
||||
var result = array(arr) // copy
|
||||
for (var i = length(result) - 1; i > 0; i--) {
|
||||
var j = random.random_whole(i + 1)
|
||||
var temp = result[i]
|
||||
result[i] = result[j]
|
||||
result[j] = temp
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
// Random in range
|
||||
function random_range(min, max) {
|
||||
return min + random.random() * (max - min)
|
||||
}
|
||||
|
||||
var x = random_range(-10, 10) // -10 to 10
|
||||
```
|
||||
123
docs/library/text.md
Normal file
123
docs/library/text.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# text
|
||||
|
||||
The `text` function and its methods handle string conversion and manipulation.
|
||||
|
||||
## Conversion
|
||||
|
||||
### text(array, separator)
|
||||
|
||||
Convert an array to text, joining elements with a separator (default: space).
|
||||
|
||||
```javascript
|
||||
text([1, 2, 3]) // "1 2 3"
|
||||
text([1, 2, 3], ", ") // "1, 2, 3"
|
||||
text(["a", "b"], "-") // "a-b"
|
||||
```
|
||||
|
||||
### text(number, radix)
|
||||
|
||||
Convert a number to text. Radix is 2-36 (default: 10).
|
||||
|
||||
```javascript
|
||||
text(255) // "255"
|
||||
text(255, 16) // "ff"
|
||||
text(255, 2) // "11111111"
|
||||
```
|
||||
|
||||
### text(text, from, to)
|
||||
|
||||
Extract a substring from index `from` to `to`.
|
||||
|
||||
```javascript
|
||||
text("hello world", 0, 5) // "hello"
|
||||
text("hello world", 6) // "world"
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### text.lower(text)
|
||||
|
||||
Convert to lowercase.
|
||||
|
||||
```javascript
|
||||
text.lower("HELLO") // "hello"
|
||||
```
|
||||
|
||||
### text.upper(text)
|
||||
|
||||
Convert to uppercase.
|
||||
|
||||
```javascript
|
||||
text.upper("hello") // "HELLO"
|
||||
```
|
||||
|
||||
### text.trim(text, reject)
|
||||
|
||||
Remove characters from both ends. Default removes whitespace.
|
||||
|
||||
```javascript
|
||||
text.trim(" hello ") // "hello"
|
||||
text.trim("xxhelloxx", "x") // "hello"
|
||||
```
|
||||
|
||||
### text.search(text, target, from)
|
||||
|
||||
Find the position of `target` in `text`. Returns `null` if not found.
|
||||
|
||||
```javascript
|
||||
text.search("hello world", "world") // 6
|
||||
text.search("hello world", "xyz") // null
|
||||
text.search("hello hello", "hello", 1) // 6
|
||||
```
|
||||
|
||||
### text.replace(text, target, replacement, limit)
|
||||
|
||||
Replace occurrences of `target` with `replacement`.
|
||||
|
||||
```javascript
|
||||
text.replace("hello", "l", "L") // "heLLo"
|
||||
text.replace("hello", "l", "L", 1) // "heLlo"
|
||||
|
||||
// With function
|
||||
text.replace("hello", "l", function(match, pos) {
|
||||
return pos == 2 ? "L" : match
|
||||
}) // "heLlo"
|
||||
```
|
||||
|
||||
### text.format(text, collection, transformer)
|
||||
|
||||
Substitute `{key}` placeholders with values from a collection.
|
||||
|
||||
```javascript
|
||||
text.format("Hello, {name}!", {name: "World"})
|
||||
// "Hello, World!"
|
||||
|
||||
text.format("{0} + {1} = {2}", [1, 2, 3])
|
||||
// "1 + 2 = 3"
|
||||
```
|
||||
|
||||
### text.normalize(text)
|
||||
|
||||
Unicode normalize the text (NFC form).
|
||||
|
||||
```javascript
|
||||
text.normalize("café") // normalized form
|
||||
```
|
||||
|
||||
### text.codepoint(text)
|
||||
|
||||
Get the Unicode codepoint of the first character.
|
||||
|
||||
```javascript
|
||||
text.codepoint("A") // 65
|
||||
text.codepoint("😀") // 128512
|
||||
```
|
||||
|
||||
### text.extract(text, pattern, from, to)
|
||||
|
||||
Match a pattern and extract named groups.
|
||||
|
||||
```javascript
|
||||
text.extract("2024-01-15", /(\d+)-(\d+)-(\d+)/)
|
||||
// Returns match info
|
||||
```
|
||||
116
docs/library/time.md
Normal file
116
docs/library/time.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# time
|
||||
|
||||
The time module provides time constants and conversion functions.
|
||||
|
||||
```javascript
|
||||
var time = use('time')
|
||||
```
|
||||
|
||||
## Constants
|
||||
|
||||
| Constant | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| `time.second` | 1 | Seconds in a second |
|
||||
| `time.minute` | 60 | Seconds in a minute |
|
||||
| `time.hour` | 3600 | Seconds in an hour |
|
||||
| `time.day` | 86400 | Seconds in a day |
|
||||
| `time.week` | 604800 | Seconds in a week |
|
||||
| `time.month` | 2629746 | Seconds in a month (30.44 days) |
|
||||
| `time.year` | 31556952 | Seconds in a year (365.24 days) |
|
||||
|
||||
## Getting Current Time
|
||||
|
||||
### time.number()
|
||||
|
||||
Get current time as seconds since epoch.
|
||||
|
||||
```javascript
|
||||
var now = time.number() // e.g., 1702656000
|
||||
```
|
||||
|
||||
### time.record()
|
||||
|
||||
Get current time as a record.
|
||||
|
||||
```javascript
|
||||
var now = time.record()
|
||||
// {year: 2024, month: 1, day: 15, hour: 10, minute: 30, second: 45, nanosecond: 123456789}
|
||||
```
|
||||
|
||||
### time.text(format)
|
||||
|
||||
Get current time as formatted text.
|
||||
|
||||
```javascript
|
||||
time.text() // default format
|
||||
time.text("yyyy-MM-dd HH:mm:ss.SSS") // custom format
|
||||
```
|
||||
|
||||
## Converting Time
|
||||
|
||||
### time.number(text, format, zone)
|
||||
|
||||
Parse text to timestamp.
|
||||
|
||||
```javascript
|
||||
time.number("2024-01-15", "yyyy-MM-dd")
|
||||
```
|
||||
|
||||
### time.number(record)
|
||||
|
||||
Convert record to timestamp.
|
||||
|
||||
```javascript
|
||||
time.number({year: 2024, month: 1, day: 15})
|
||||
```
|
||||
|
||||
### time.text(number, format, zone)
|
||||
|
||||
Format timestamp as text.
|
||||
|
||||
```javascript
|
||||
time.text(1702656000, "yyyy-MM-dd") // "2024-01-15"
|
||||
```
|
||||
|
||||
### time.record(number)
|
||||
|
||||
Convert timestamp to record.
|
||||
|
||||
```javascript
|
||||
time.record(1702656000)
|
||||
// {year: 2024, month: 1, day: 15, ...}
|
||||
```
|
||||
|
||||
## Time Arithmetic
|
||||
|
||||
```javascript
|
||||
var now = time.number()
|
||||
|
||||
// Tomorrow at this time
|
||||
var tomorrow = now + time.day
|
||||
|
||||
// One week ago
|
||||
var last_week = now - time.week
|
||||
|
||||
// In 2 hours
|
||||
var later = now + (2 * time.hour)
|
||||
|
||||
// Format future time
|
||||
log.console(time.text(tomorrow))
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```javascript
|
||||
var time = use('time')
|
||||
|
||||
// Measure execution time
|
||||
var start = time.number()
|
||||
// ... do work ...
|
||||
var elapsed = time.number() - start
|
||||
log.console(`Took ${elapsed} seconds`)
|
||||
|
||||
// Schedule for tomorrow
|
||||
var tomorrow = time.number() + time.day
|
||||
log.console(`Tomorrow: ${time.text(tomorrow, "yyyy-MM-dd")}`)
|
||||
```
|
||||
Reference in New Issue
Block a user