diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 6 | ||||
| -rw-r--r-- | docs/tutorials/02-syntax.md | 56 | ||||
| -rw-r--r-- | docs/tutorials/04-arrays.md | 647 | ||||
| -rw-r--r-- | docs/tutorials/05-dictionaries.md | 762 | ||||
| -rw-r--r-- | docs/tutorials/tutorials.json | 6 |
5 files changed, 1471 insertions, 6 deletions
diff --git a/docs/README.md b/docs/README.md index 016c7f5..92ab103 100644 --- a/docs/README.md +++ b/docs/README.md @@ -69,14 +69,14 @@ command. ### MacOS -To build on MacOS, first install *cmake* and *json-c* via +To build on MacOS, first install *cmake*, *json-c* and *libmd* via [Homebrew](https://brew.sh/), then clone the ucode repository and execute *cmake* followed by *make*: - $ brew install cmake json-c + $ brew install cmake json-c libmd $ git clone https://github.com/jow-/ucode.git $ cd ucode/ - $ cmake -DUBUS_SUPPORT=OFF -DUCI_SUPPORT=OFF -DULOOP_SUPPORT=OFF . + $ cmake -DUBUS_SUPPORT=OFF -DUCI_SUPPORT=OFF -DULOOP_SUPPORT=OFF -DCMAKE_BUILD_RPATH=/usr/local/lib -DCMAKE_INSTALL_RPATH=/usr/local/lib . $ make $ sudo make install diff --git a/docs/tutorials/02-syntax.md b/docs/tutorials/02-syntax.md index c140804..5510343 100644 --- a/docs/tutorials/02-syntax.md +++ b/docs/tutorials/02-syntax.md @@ -284,7 +284,56 @@ a counting `for` loop that is a variation of the `while` loop. %} ``` -#### 3.3. Alternative syntax +#### 3.3. Switch statement + +The `switch` statement selects code blocks to execute based on an expression's +value. Unlike other control statements, it doesn't support alternative syntax +with colons and end keywords. + +Switch statements use strict equality (`===`) for comparison. Case values can be +arbitrary expressions evaluated at runtime. Without a `break` statement, +execution continues through subsequent cases. + +The optional `default` case executes when no case matches. It's typically placed +last but will only execute if no previous matching case was found. + +The entire switch statement shares one block scope. Variables declared in any +case are visible in all cases. Curly braces may be used within cases to create +case-specific variable scopes. + +```javascript +{% + day = 3; + specialDay = 1; + + switch (day) { + case specialDay + 2: + print("Wednesday\n"); + break; + + case 1: + let message = "Start of week"; + print(message + "\n"); + break; + + case 2: { + let message = "Tuesday"; + print(message + "\n"); + break; + } + + case 4: + case 5: + print("Thursday or Friday\n"); + break; + + default: + print("Weekend\n"); + } +%} +``` + +#### 3.4. Alternative syntax Since conditional statements and loops are often used for template formatting purposes, e.g. to repeat a specific markup for each item of a list, ucode @@ -312,7 +361,8 @@ Printing a list: {% endfor %} ``` -For each control statement type, a corresponding alternative end keyword is defined: +For each control statement type except switch statements, a corresponding +alternative end keyword is defined: - `if (...): ... endif` - `for (...): ... endfor` @@ -629,4 +679,4 @@ in the table below. Operators with a higher precedence value are evaluated before operators with a lower precedence value. When operators have the same precedence, their associativity determines the order of evaluation -(e.g., left-to-right or right-to-left).
\ No newline at end of file +(e.g., left-to-right or right-to-left). diff --git a/docs/tutorials/04-arrays.md b/docs/tutorials/04-arrays.md new file mode 100644 index 0000000..789e990 --- /dev/null +++ b/docs/tutorials/04-arrays.md @@ -0,0 +1,647 @@ +Arrays in ucode are ordered collections that can store any ucode value. Unlike +many other scripting languages where arrays are implemented as hash tables or +linked lists, ucode arrays are true arrays in memory. This implementation detail +provides several distinctive characteristics that developers should understand +when working with arrays in ucode. + +## Key Characteristics of Ucode Arrays + +### True Memory Arrays + +Ucode arrays are implemented as true arrays in memory, which means: +- They offer fast random access to elements by index +- They are stored contiguously in memory +- Memory allocation expands as needed to accommodate the highest used index + +### Sparse Array Behavior + +Because ucode arrays are true arrays in memory: +- Memory is always allocated contiguously up to the highest used index +- All positions (including unused ones) consume memory +- "Empty" or unused positions contain `null` values +- There is no special optimization for sparse arrays + +### Negative Index Support + +Ucode arrays provide convenient negative indexing: +- `-1` refers to the last element +- `-2` refers to the second-last element +- And so on, allowing easy access to elements from the end of the array + +### Type Flexibility + +Arrays in ucode can hold any ucode value type: +- Booleans, numbers (integers and doubles), strings +- Objects and arrays (allowing nested arrays) +- Functions and null values +- No type restrictions between elements (unlike typed arrays in some languages) + +## Core Array Functions + +### Array Information Functions + +#### {@link module:core#length|length(x)} → {number} + +Returns the number of elements in an array. This is one of the most fundamental +array operations in ucode. + +``` +let fruits = ["apple", "banana", "orange"]; +length(fruits); // 3 + +let sparse = []; +sparse[10] = "value"; +length(sparse); // 11 (includes empty slots) +``` + +For arrays, `length()` returns the highest index plus one, which means it +includes empty slots in sparse arrays. If the input is not an array, string, or +object, `length()` returns null. + +#### {@link module:core#index|index(arr_or_str, needle)} → {number} + +Searches for a value in an array and returns the index of the first matching occurrence. + +``` +let colors = ["red", "green", "blue", "green"]; +index(colors, "green"); // 1 (returns first match) +index(colors, "yellow"); // -1 (not found) +``` + +Unlike many other languages where array search functions return -1 or null for +non-matching items, `index()` in ucode specifically returns -1 when the value +isn't found. It returns null only if the first argument is neither an array nor +a string. + +#### {@link module:core#rindex|rindex(arr_or_str, needle)} → {number} + +Similar to `index()`, but searches backward from the end of the array: + +``` +let colors = ["red", "green", "blue", "green"]; +rindex(colors, "green"); // 3 (last occurrence) +``` + +#### Checking if a Value is an Array + +To determine if a value is an array, use the `type()` function: + +``` +function isArray(value) { + return type(value) == "array"; +} + +isArray([1, 2, 3]); // true +isArray("string"); // false +isArray({key: "value"}); // false +isArray(null); // false +``` + +The `type()` function is extremely useful for defensive programming, especially +in ucode where functions often need to determine the type of their arguments to +process them correctly. + +### Manipulation Functions + +#### {@link module:core#push|push(arr, ...values)} → {*} + +Adds one or more elements to the end of an array and returns the last pushed +value. + +``` +let x = [1, 2, 3]; +push(x, 4, 5, 6); // 6 +print(x); // [1, 2, 3, 4, 5, 6] +``` + +Returns null if the array was empty or if a non-array argument was passed. + +#### {@link module:core#pop|pop(arr)} → {*} + +Removes the last element from an array and returns it. + +``` +let x = [1, 2, 3]; +let lastItem = pop(x); // 3 +print(x); // [1, 2] +``` + +Returns null if the array was empty or if a non-array argument was passed. + +#### {@link module:core#unshift|unshift(arr, ...values)} → {*} + +Adds one or more elements to the beginning of an array and returns the last +value added. + +``` +let x = [3, 4, 5]; +unshift(x, 1, 2); // 2 +print(x); // [1, 2, 3, 4, 5] +``` + +#### {@link module:core#shift|shift(arr)} → {*} + +Removes the first element from an array and returns it. + +``` +let x = [1, 2, 3]; +let firstItem = shift(x); // 1 +print(x); // [2, 3] +``` + +Returns null if the array was empty or if a non-array argument was passed. + +### Transformation Functions + +#### {@link module:core#map|map(arr, fn)} → {Array} + +Creates a new array populated with the results of calling a provided function on +every element in the calling array. + +``` +let numbers = [1, 2, 3, 4]; +let squares = map(numbers, x => x * x); // [1, 4, 9, 16] +``` + +Note: The callback function receives three arguments: +1. The current element value +2. The current index +3. The array being processed + +``` +let values = map(["foo", "bar", "baz"], function(value, index, array) { + return `${index}: ${value} (from array of length ${length(array)})`; +}); +``` + +##### Important Pitfall with Built-in Functions + +A common mistake when using `map()` is passing a built-in function directly as +the callback. Consider this example attempting to convert an array of strings to +integers: + +``` +// ⚠️ INCORRECT: This will not work as expected! +let strings = ["10", "32", "13"]; +let nums = map(strings, int); // Results will be unpredictable! +``` + +This fails because the `map()` function calls the callback with three arguments: +1. The current value (`"10"`, `"32"`, etc.) +2. The current index (`0`, `1`, `2`) +3. The original array (`["10", "32", "13"]`) + +So what actually happens is equivalent to: +``` +int("10", 0, ["10", "32", "13"]) // Interprets 0 as base parameter! +int("32", 1, ["10", "32", "13"]) // Interprets 1 as base parameter! +int("13", 2, ["10", "32", "13"]) // Interprets 2 as base parameter! +``` + +The second argument to `int()` is interpreted as the numeric base, causing +unexpected conversion results: + +- `"10"` in base 0 is interpreted as decimal 10 (base 0 is a special case that auto-detects the base) +- `"32"` in base 1 produces `NaN` because base 1 is invalid (a numeral system needs at least 2 distinct digits) +- `"13"` in base 2 produces `1` because in binary only `0` and `1` are valid digits - it converts `"1"` successfully and stops at the invalid character `"3"` + +The actual result would be `[10, NaN, 1]`, which is certainly not what you'd +expect when trying to convert string numbers to integers! + +To fix this, wrap the function call in an arrow function or a regular function +that controls the number of arguments: + +``` +// ✓ CORRECT: Using arrow function to control arguments +let strings = ["10", "32", "13"]; +let nums = map(strings, x => int(x)); // [10, 32, 13] + +// Alternative approach using a named function +function toInt(str) { + return int(str); +} +let nums2 = map(strings, toInt); // [10, 32, 13] +``` + +This pattern applies to many other built-in functions like `length()`, `trim()`, +`b64enc()`, etc. Always wrap built-in functions when using them with `map()` to +ensure they receive only the intended arguments. + +#### {@link module:core#filter|filter(arr, fn)} → {Array} + +Creates a new array with all elements that pass the test implemented by the +provided function. + +``` +let numbers = [1, 2, 3, 4, 5, 6]; +let evens = filter(numbers, x => x % 2 == 0); // [2, 4, 6] +``` + +The callback function receives the same three arguments as in `map()`. + +#### {@link module:core#sort|sort(arr, fn)} → {Array} + +Sorts the elements of an array in place and returns the sorted array, optionally +using a custom compare function. + +``` +let numbers = [3, 1, 4, 2]; +sort(numbers); // [1, 2, 3, 4] +``` + +With a custom compare function: + +``` +let people = [ + { name: "Alice", age: 25 }, + { name: "Bob", age: 30 }, + { name: "Charlie", age: 20 } +]; + +sort(people, (a, b) => a.age - b.age); +// [{ name: "Charlie", age: 20 }, { name: "Alice", age: 25 }, { name: "Bob", age: 30 }] +``` + +#### {@link module:core#reverse|reverse(arr)} → {Array} + +Returns a new array with the order of all elements reversed. + +``` +let arr = [1, 2, 3]; +reverse(arr); // [3, 2, 1] +``` + +This function also works on strings: + +``` +reverse("hello"); // "olleh" +``` + +Returns null if the argument is neither an array nor a string. + +#### {@link module:core#uniq|uniq(array)} → {Array} + +Creates a new array with all duplicate elements removed. + +``` +let array = [1, 2, 2, 3, 1, 4, 5, 4]; +uniq(array); // [1, 2, 3, 4, 5] +``` + +Returns null if a non-array argument is given. + +### Helper Functions and Recipes + +The ucode standard library provides essential array functions, but many common +operations must be implemented manually. Below, you'll find example +implementations for frequently needed array operations that aren't built into +the core library. + +These recipes demonstrate how to leverage ucode's existing functions to build +more complex array utilities. + +#### Array Intersection + +Returns a new array containing elements present in all provided arrays. + +``` +function intersect(...arrays) { + if (!length(arrays)) + return []; + + let result = arrays[0]; + + for (let i = 1; i < length(arrays); i++) { + result = filter(result, item => item in arrays[i]); + } + + return uniq(result); +} + +// Example usage: +let a = [1, 2, 3, 4]; +let b = [2, 3, 5]; +let c = [2, 3, 6]; +intersect(a, b, c); // [2, 3] +``` + +This implementation takes advantage of ucode's `in` operator, which checks if a +value exists in an array using strict equality comparison. This makes the code +more concise than using `index()` and checking if the result is not -1. + +#### Array Merge/Concatenation + +Combines multiple arrays into a new array. Taking advantage of ucode's variadic +`push()` function with the spread operator provides an elegant solution: + +``` +function merge(...arrays) { + let result = []; + + for (arr in arrays) { + push(result, ...arr); // Spreads all elements from the array directly into push + } + + return result; +} + +// Example usage: +let a = [1, 2]; +let b = [3, 4]; +let c = [5, 6]; +merge(a, b, c); // [1, 2, 3, 4, 5, 6] +``` + +This implementation leverages the variadic nature of `push()`, which accepts any +number of arguments. The spread operator (`...`) unpacks each array, passing all +its elements as individual arguments to `push()`. This is both more efficient +and more readable than nested loops. + +For processing very large arrays, you might want to use a batching approach to +avoid potential call stack limitations: + +``` +function mergeWithBatching(...arrays) { + let result = []; + const BATCH_SIZE = 1000; + + for (arr in arrays) { + // Handle array in batches to avoid excessive function arguments + for (let i = 0; i < length(arr); i += BATCH_SIZE) { + let batch = slice(arr, i, i + BATCH_SIZE); + push(result, ...batch); + } + } + + return result; +} +``` + +#### Array Difference + +Returns elements in the first array not present in subsequent arrays. + +``` +function difference(array, ...others) { + return filter(array, item => { + for (other in others) { + if (item in other) + return false; + } + return true; + }); +} + +// Example usage: +let a = [1, 2, 3, 4, 5]; +let b = [2, 3]; +let c = [4]; +difference(a, b, c); // [1, 5] +``` + +This implementation uses the `in` operator for concise and efficient membership +testing, filtering out any elements from the first array that appear in any of +the subsequent arrays. + +#### Array Chunk + +Splits an array into chunks of specified size. + +``` +function chunk(array, size) { + if (size <= 0) + return []; + + let result = []; + + for (let i = 0; i < length(array); i += size) { + push(result, slice(array, i, i + size)); + } + + return result; +} + +// Example usage: +let nums = [1, 2, 3, 4, 5, 6, 7, 8]; +chunk(nums, 3); // [[1, 2, 3], [4, 5, 6], [7, 8]] +``` + +This implementation uses a counting `for` loop combined with `slice()`, which is +both more idiomatic and more efficient. The approach: + +1. Iterates through the array in steps of `size` +2. Uses `slice()` to extract chunks of the appropriate size +3. Automatically handles the last chunk being smaller if the array length isn't divisible by the chunk size + +This pattern leverages ucode's built-in functions for cleaner, more maintainable +code. No temporary variables are needed to track the current chunk or count, +making the implementation more straightforward. + +#### Array Sum + +Calculates the sum of all numeric elements in an array. + +``` +function sum(array) { + let result = 0; + + for (item in array) { + if (type(item) == "int" || type(item) == "double") + result += item; + } + + return result; +} + +// Example usage: +let nums = [1, 2, 3, 4, 5]; +sum(nums); // 15 +``` + +#### Array Flatten + +Flattens a nested array structure. + +``` +function flatten(array, depth) { + if (depth === undefined) + depth = 1; + + let result = []; + + for (item in array) { + if (type(item) == "array" && depth > 0) { + let flattened = flatten(item, depth - 1); + for (subItem in flattened) { + push(result, subItem); + } + } else { + push(result, item); + } + } + + return result; +} + +// Example usage: +let nested = [1, [2, [3, 4], 5], 6]; +flatten(nested); // [1, 2, [3, 4], 5, 6] +flatten(nested, 2); // [1, 2, 3, 4, 5, 6] +``` + +## Advanced Array Techniques and Considerations + +### Memory Management + +When working with arrays in ucode, you should understand several important +memory characteristics that affect performance and resource usage: + +#### Sparse Array Memory Implications + +Since ucode arrays are true arrays in memory, array memory consumption scales +linearly with the highest index used, regardless of how many elements are +actually stored: + +``` +let arr = []; +arr[1000000] = "value"; // Allocates memory for 1,000,001 pointers +``` + +Important technical details about ucode array memory usage: +- Each array element consumes pointer-sized memory (4 bytes on 32-bit systems, 8 bytes on 64-bit systems) +- No optimizations exist for sparse arrays - every position up to the highest index is allocated +- When an array grows beyond its capacity, it's reallocated with a growth factor of 1.5 +- Memory is allocated even for "empty" slots (which contain the `null` value) + +For example, on a 64-bit system, creating an array with a single element at +index 1,000,000 would consume approximately 8MB of memory (1,000,001 * 8 bytes), +even though only one actual value is stored. + +``` +// Demonstrates memory consumption +let smallArray = []; +for (let i = 0; i < 10; i++) + smallArray[i] = i; + +let sparseArray = []; +sparseArray[1000000] = "far away"; + +print(`Small array has ${length(smallArray)} elements\n`); +print(`Sparse array has ${length(sparseArray)} elements\n`); +// Even though only one value is actually set, memory is allocated for all positions +``` + +This behavior makes ucode arrays efficient for random access but potentially +wasteful for very sparse data structures. For data with large gaps or when +working on memory-constrained systems, consider alternative approaches like +objects with numeric string keys. + +#### Negative Index Implementation + +While negative indices provide convenient access to elements from the end of an +array, they involve an internal conversion process: + +``` +let arr = [1, 2, 3, 4, 5]; +arr[-1]; // Internally converted to arr[length(arr) - 1], or arr[4] +arr[-3]; // Internally converted to arr[length(arr) - 3], or arr[2] +``` + +This conversion adds a small computational overhead compared to direct positive +indexing. For performance-critical code processing large arrays, consider using +positive indices when possible. + +#### Mixed-Type Arrays and Sorting + +Arrays in ucode can contain mixed types, offering great flexibility but +requiring careful handling, especially with operations like `sort()`: + +``` +let mixed = ["apple", 10, true, {name: "object"}, [1, 2]]; + +// Sort behaves differently with mixed types +// Numbers come first, then arrays, then strings, then booleans, then objects +sort(mixed); // [10, [1, 2], "apple", true, {name: "object"}] +``` + +When sorting mixed-type arrays, consider implementing a custom comparison +function to define the sorting behavior explicitly: + +``` +function mixedTypeSort(a, b) { + // Sort by type first, then by value + let typeA = type(a); + let typeB = type(b); + + if (typeA != typeB) { + // Define a type precedence order + let typePrecedence = { + "int": 1, + "double": 2, + "string": 3, + "bool": 4, + "array": 5, + "object": 6 + }; + return typePrecedence[typeA] - typePrecedence[typeB]; + } + + // If same type, compare values appropriately + if (typeA == "string" || typeA == "array") + return length(a) - length(b); + return a - b; +} + +// Now sorting is more predictable +sort(mixed, mixedTypeSort); +``` + +### Performance Optimization + +When working with large arrays, consider these optimization techniques: + +1. **Pre-allocation**: Where possible, create arrays with known capacity rather than growing incrementally +2. **Batch operations**: Minimize individual push/pop/shift/unshift calls by processing in batches +3. **Avoid unnecessary copies**: Use in-place operations when possible +4. **Filter early**: Filter arrays early in processing pipelines to reduce subsequent operation sizes + +### Array Deep Copying + +Since arrays are reference types, creating true copies requires special handling: + +``` +function deepCopy(arr) { + if (type(arr) != "array") + return arr; + + let result = []; + for (item in arr) { + if (type(item) == "array") + push(result, deepCopy(item)); + else if (type(item) == "object") + push(result, deepCopyObject(item)); + else + push(result, item); + } + return result; +} + +function deepCopyObject(obj) { + if (type(obj) != "object") + return obj; + + let result = {}; + for (key in keys(obj)) { + if (type(obj[key]) == "array") + result[key] = deepCopy(obj[key]); + else if (type(obj[key]) == "object") + result[key] = deepCopyObject(obj[key]); + else + result[key] = obj[key]; + } + return result; +} +``` + +This approach ensures all nested arrays and objects are properly copied rather +than referenced. diff --git a/docs/tutorials/05-dictionaries.md b/docs/tutorials/05-dictionaries.md new file mode 100644 index 0000000..52c9824 --- /dev/null +++ b/docs/tutorials/05-dictionaries.md @@ -0,0 +1,762 @@ +Dictionaries in ucode (also referred to as objects) are key-value collections +that provide efficient lookups by key. Unlike arrays which use numeric indices, +dictionaries use string keys to access values. Understanding how dictionaries +are implemented in ucode and their distinctive characteristics will help you +write more efficient and effective code. + +## Key Characteristics of Ucode Dictionaries + +### Hash Table Implementation with Ordered Keys + +Ucode dictionaries are implemented as ordered hash tables, which means: +- They offer fast O(1) average-case lookups by key +- Keys are hashed to determine storage location +- Memory allocation is dynamic and grows as needed +- Unlike arrays, memory is not allocated contiguously +- Key order is preserved based on declaration or assignment sequence +- Keys can be reordered using `sort()` + +### String-Only Keys with Important Limitations + +One important limitation of ucode dictionaries: +- All keys must be strings +- Non-string keys are implicitly converted to strings +- Numeric keys become string representations (e.g., `5` becomes `"5"`) +- This differs from JavaScript where objects can use Symbols as keys + +#### Warning: Null Byte Truncation in Keys + +A critical implementation detail to be aware of is that dictionary keys +containing null bytes (`\0`) will be silently truncated at the first null byte: + +``` +let dict = {"foo\0bar": 123}; +print(dict.foo); // 123 +print(exists(dict, "foo\0bar")); // false +print(exists(dict, "foo")); // true +``` + +This happens because the underlying hash table implementation treats keys as +C-style null-terminated strings. While this behavior may change in future +versions of ucode, you should currently: + +- Never use keys containing null bytes +- Sanitize any untrusted external input used as dictionary keys +- Be especially careful when using binary data or user input as keys + +This issue can lead to subtle bugs and potential security vulnerabilities if +malicious users craft input with embedded null bytes to manipulate key lookups. + +### Type Flexibility for Values + +Like arrays, dictionary values in ucode can be of any type: +- Booleans, numbers (integers and doubles), strings +- Objects and arrays (allowing nested structures) +- Functions and null values +- Different keys can store different value types + +### Reference Semantics + +Dictionaries are reference types in ucode: +- Assigning a dictionary to a new variable creates a reference, not a copy +- Modifying a dictionary through any reference affects all references +- Equality comparisons test reference identity, not structural equality + +## Core Dictionary Functions + +### Dictionary Information Functions + +#### {@link module:core#length|length(x)} → {number} + +Returns the number of keys in a dictionary. + +``` +let user = {name: "Alice", age: 30, role: "Admin"}; +length(user); // 3 + +let empty = {}; +length(empty); // 0 +``` + +For dictionaries, `length()` returns the count of keys. If the input is not an +array, string, or object, `length()` returns null. + +#### {@link module:core#keys|keys(obj)} → {Array} + +Returns an array containing all keys in the dictionary. + +``` +let config = {debug: true, timeout: 500, retries: 3}; +keys(config); // ["debug", "timeout", "retries"] +``` + +Unlike many other languages, ucode maintains key ordering based on declaration +or assignment order. Keys are returned in the same order they were defined or +assigned. + +#### {@link module:core#values|values(obj)} → {Array} + +Returns an array containing all values in the dictionary. + +``` +let counts = {apples: 5, oranges: 10, bananas: 7}; +values(counts); // [5, 10, 7] +``` + +The returned values correspond to the declaration/assignment order of keys in +the dictionary, matching the order that would be returned by `keys()`. + +#### {@link module:core#exists|exists(obj, key)} → {boolean} + +Checks whether a key exists in a dictionary. + +``` +let settings = {theme: "dark", fontSize: 16}; +exists(settings, "theme"); // true +exists(settings, "language"); // false +``` + +This function offers a straightforward way to check for key existence without +accessing the value. + +#### Checking if a Value is a Dictionary + +To determine if a value is a dictionary (object), use the `type()` function: + +``` +function isObject(value) { + return type(value) == "object"; +} + +isObject({key: "value"}); // true +isObject([1, 2, 3]); // false +isObject("string"); // false +isObject(null); // false +``` + +### Manipulation Functions + +In ucode, dictionary manipulation is performed primarily through direct property +access using dot notation or bracket notation. + +#### Adding or Updating Properties + +``` +let user = {name: "Bob"}; + +// Adding new properties +user.age = 25; +user["email"] = "bob@example.com"; + +// Updating existing properties +user.name = "Robert"; +user["age"] += 1; + +print(user); // {name: "Robert", age: 26, email: "bob@example.com"} +``` + +#### Removing Properties + +Properties can be removed using the `delete` operator: + +``` +let product = {id: "p123", name: "Laptop", price: 999, discontinued: false}; + +delete product.discontinued; +print(product); // {id: "p123", name: "Laptop", price: 999} + +delete product["price"]; +print(product); // {id: "p123", name: "Laptop"} +``` + +#### Merging Dictionaries + +Ucode supports using spread expressions to merge dictionaries elegantly: + +``` +let defaults = {theme: "light", fontSize: 12, notifications: true}; +let userSettings = {theme: "dark"}; + +// Merge dictionaries with spread syntax +let merged = {...defaults, ...userSettings}; +print(merged); // {theme: "dark", fontSize: 12, notifications: true} +``` + +When merging with spread syntax, properties from later objects overwrite those +from earlier objects if the keys are the same. This provides a clean way to +implement default options with overrides: + +``` +// Apply user preferences with fallbacks +let config = { + ...systemDefaults, + ...globalSettings, + ...userPreferences +}; +``` + +For situations requiring more complex merging logic, you can implement a custom +function: + +``` +function merge(target, ...sources) { + for (source in sources) { + for (key in keys(source)) { + target[key] = source[key]; + } + } + return target; +} + +let defaults = {theme: "light", fontSize: 12, notifications: true}; +let userSettings = {theme: "dark"}; +let merged = merge({}, defaults, userSettings); +print(merged); // {theme: "dark", fontSize: 12, notifications: true} +``` + +Note that this performs a shallow merge. For nested objects, a deep merge would +be needed: + +``` +function deepMerge(target, ...sources) { + if (!sources.length) return target; + + for (source in sources) { + if (type(source) !== "object") continue; + + for (key in keys(source)) { + if (type(source[key]) == "object" && type(target[key]) == "object") { + // Recursively merge nested objects + target[key] = deepMerge({...target[key]}, source[key]); + } else { + // For primitive values or when target key doesn't exist/isn't an object + target[key] = source[key]; + } + } + } + + return target; +} + +let userProfile = { + name: "Alice", + preferences: { + theme: "light", + sidebar: { + visible: true, + width: 250 + } + } +}; + +let updates = { + preferences: { + theme: "dark", + sidebar: { + width: 300 + } + } +}; + +let merged = deepMerge({}, userProfile, updates); +/* Result: +{ + name: "Alice", + preferences: { + theme: "dark", + sidebar: { + visible: true, + width: 300 + } + } +} +*/ +``` + +### Iteration Techniques + +#### Iterating with for-in + +The most common way to iterate through a dictionary is using `for-in`: + +``` +let metrics = {visits: 1024, conversions: 85, bounceRate: 0.35}; + +for (key in metrics) { + printf("%s: %J\n", key, metrics[key]); +} +// Output: +// visits: 1024 +// conversions: 85 +// bounceRate: 0.35 +``` + +#### Iterating over Entries (Key-Value Pairs) + +A more advanced iteration technique gives access to both keys and values: + +``` +let product = {name: "Widget", price: 19.99, inStock: true}; + +for (key in keys(product)) { + let value = product[key]; + printf("%s: %J\n", key, value); +} +``` + +#### Enhanced for-in Loop + +Ucode provides an enhanced for-in loop that can destructure keys and values: + +``` +let inventory = {apples: 50, oranges: 25, bananas: 30}; + +for (item, quantity in inventory) { + printf("We have %d %s in stock\n", quantity, item); +} +// Output: +// We have 50 apples in stock +// We have 25 oranges in stock +// We have 30 bananas in stock +``` + +This syntax offers a more elegant way to work with both keys and values +simultaneously. + +## Key Ordering and Sorting + +One distinctive feature of ucode dictionaries is their predictable key ordering. +Unlike many other languages where hash-based dictionaries have arbitrary or +implementation-dependent key ordering, ucode maintains key order based on +declaration or assignment sequence. + +### Predictable Iteration Order + +When iterating through a dictionary, keys are always processed in their +insertion order: + +``` +let scores = {}; +scores.alice = 95; +scores.bob = 87; +scores.charlie = 92; + +// Keys will be iterated in the exact order they were added +for (name in scores) { + printf("%s: %d\n", name, scores[name]); +} +// Output will consistently be: +// alice: 95 +// bob: 87 +// charlie: 92 +``` + +This predictable ordering applies to all dictionary operations: for-in loops, +`keys()`, and `values()`. + +### Sorting Dictionary Keys + +You can explicitly reorder dictionary keys using the `sort()` function: + +``` +let stats = { + average: 72.5, + median: 68, + mode: 65, + range: 45 +}; + +// Sort keys alphabetically +sort(stats); + +// Now keys will be iterated in alphabetical order +for (metric in stats) { + printf("%s: %J\n", metric, stats[metric]); +} +// Output: +// average: 72.5 +// median: 68 +// mode: 65 +// range: 45 +``` + +Custom sorting is also supported: + +``` +let inventory = { + apples: 45, + bananas: 25, + oranges: 30, + grapes: 60 +}; + +// Sort by value (quantity) in descending order +sort(inventory, (k1, k2, v1, v2) => v2 - v1); + +// Keys will now be ordered by their associated values +for (fruit, quantity in inventory) { + printf("%s: %d\n", fruit, quantity); +} +// Output: +// grapes: 60 +// apples: 45 +// oranges: 30 +// bananas: 25 +``` + +This ability to maintain and manipulate key order makes ucode dictionaries +particularly useful for: +- Configuration objects where property order matters +- UI element definitions that should be processed in a specific sequence +- Data structures that need to maintain insertion chronology + +## Advanced Dictionary Techniques + +### Nested Dictionaries + +Dictionaries can contain other dictionaries, allowing for complex data +structures: + +``` +let company = { + name: "Acme Corp", + founded: 1985, + address: { + street: "123 Main St", + city: "Metropolis", + zipCode: "12345" + }, + departments: { + engineering: { + headCount: 50, + projects: ["Alpha", "Beta", "Gamma"] + }, + sales: { + headCount: 30, + regions: ["North", "South", "East", "West"] + } + } +}; + +// Accessing nested properties +printf("Engineering headcount: %d\n", company.departments.engineering.headCount); +``` + +### Dictionary as a Cache + +Dictionaries are excellent for implementing caches or memoization: + +``` +function memoizedFibonacci() { + let cache = {}; + + // Return the actual fibonacci function with closure over cache + return function fib(n) { + // Check if result exists in cache + if (exists(cache, n)) { + return cache[n]; + } + + // Calculate result for new inputs + let result; + if (n <= 1) { + result = n; + } else { + result = fib(n-1) + fib(n-2); + } + + // Store result in cache + cache[n] = result; + return result; + }; +} + +let fibonacci = memoizedFibonacci(); +printf("Fibonacci 40: %d\n", fibonacci(40)); // Fast computation due to caching +``` + +### Using Dictionaries for Lookups + +Dictionaries excel at lookup tables and can replace complex conditional logic: + +``` +// Instead of: +function getStatusMessage(code) { + if (code == 200) return "OK"; + else if (code == 404) return "Not Found"; + else if (code == 500) return "Server Error"; + // ...and so on + return "Unknown Status"; +} + +// Use a dictionary: +let statusMessages = { + "200": "OK", + "404": "Not Found", + "500": "Server Error" +}; + +function getStatusMessage(code) { + return statusMessages[code] ?? "Unknown Status"; +} +``` + +### Dictionary Patterns and Recipes + +#### Deep Clone + +Creating a deep copy of a dictionary with nested objects: + +``` +function deepClone(obj) { + if (type(obj) != "object") { + return obj; + } + + let clone = {}; + for (key in keys(obj)) { + if (type(obj[key]) == "object") { + clone[key] = deepClone(obj[key]); + } else if (type(obj[key]) == "array") { + clone[key] = deepCloneArray(obj[key]); + } else { + clone[key] = obj[key]; + } + } + return clone; +} + +function deepCloneArray(arr) { + let result = []; + for (item in arr) { + if (type(item) == "object") { + push(result, deepClone(item)); + } else if (type(item) == "array") { + push(result, deepCloneArray(item)); + } else { + push(result, item); + } + } + return result; +} +``` + +#### Dictionary Filtering + +Creating a new dictionary with only desired key-value pairs: + +``` +function filterObject(obj, filterFn) { + let result = {}; + for (key in keys(obj)) { + if (filterFn(key, obj[key])) { + result[key] = obj[key]; + } + } + return result; +} + +// Example: Keep only numeric values +let mixed = {a: 1, b: "string", c: 3, d: true, e: 4.5}; +let numbersOnly = filterObject(mixed, (key, value) => + type(value) == "int" || type(value) == "double" +); +print(numbersOnly); // {a: 1, c: 3, e: 4.5} +``` + +#### Object Mapping + +Transforming values in a dictionary while keeping the same keys: + +``` +function mapObject(obj, mapFn) { + let result = {}; + for (key in keys(obj)) { + result[key] = mapFn(key, obj[key]); + } + return result; +} + +// Example: Double all numeric values +let prices = {apple: 1.25, banana: 0.75, cherry: 2.50}; +let discountedPrices = mapObject(prices, (fruit, price) => price * 0.8); +print(discountedPrices); // {apple: 1, banana: 0.6, cherry: 2} +``` + +#### Dictionary Equality + +Comparing dictionaries by value instead of by reference: + +``` +function objectEquals(obj1, obj2) { + // Check if both are objects + if (type(obj1) != "object" || type(obj2) != "object") { + return obj1 === obj2; + } + + // Check key count + let keys1 = keys(obj1); + let keys2 = keys(obj2); + if (length(keys1) != length(keys2)) { + return false; + } + + // Check each key-value pair + for (key in keys1) { + if (!exists(obj2, key)) { + return false; + } + + if (type(obj1[key]) == "object" && type(obj2[key]) == "object") { + // Recursively check nested objects + if (!objectEquals(obj1[key], obj2[key])) { + return false; + } + } else if (type(obj1[key]) == "array" && type(obj2[key]) == "array") { + // For arrays, we would need array equality check + if (!arrayEquals(obj1[key], obj2[key])) { + return false; + } + } else if (obj1[key] !== obj2[key]) { + return false; + } + } + return true; +} + +function arrayEquals(arr1, arr2) { + if (length(arr1) != length(arr2)) { + return false; + } + + for (let i = 0; i < length(arr1); i++) { + if (type(arr1[i]) == "object" && type(arr2[i]) == "object") { + if (!objectEquals(arr1[i], arr2[i])) { + return false; + } + } else if (type(arr1[i]) == "array" && type(arr2[i]) == "array") { + if (!arrayEquals(arr1[i], arr2[i])) { + return false; + } + } else if (arr1[i] !== arr2[i]) { + return false; + } + } + return true; +} +``` + +## Performance Considerations and Best Practices + +### Hash Collision Impacts + +Since ucode dictionaries use hash tables: +- Hash collisions can occur (different keys hash to same value) +- Hash collision resolution affects performance +- As dictionaries grow large, performance degradation may occur +- Performance is generally consistent but can have occasional spikes due to rehashing + +### Key Naming Considerations + +String keys have important implications: +- Choose short, descriptive keys to minimize memory usage +- Be consistent with key naming conventions +- Remember that property access via dot notation (`obj.prop`) and bracket notation (`obj["prop"]`) are equivalent +- Keys containing special characters or reserved words must use bracket notation: `obj["special-key"]` + +### Memory Usage Optimization + +To optimize dictionary memory usage: +- Delete unused keys to prevent memory leaks +- Use shallow structures when possible +- Consider serialization for large dictionaries not actively used +- Be aware that circular references delay garbage collection until mark-sweep GC runs + +``` +// Circular reference example +let obj1 = {}; +let obj2 = {ref: obj1}; +obj1.ref = obj2; // Creates a circular reference + +// While reference counting won't collect these immediately, +// a mark-sweep GC run will eventually reclaim this memory +// when the objects become unreachable from the root scope +``` + +### Performance Patterns + +#### Property Access Optimization + +When repeatedly accessing the same property in loops, consider caching: + +``` +// Less efficient - repeated property access +for (let i = 0; i < 1000; i++) { + processValue(config.complexComputedValue); +} + +// More efficient - cache the property +let cachedValue = config.complexComputedValue; +for (let i = 0; i < 1000; i++) { + processValue(cachedValue); +} +``` + +#### Key Existence Check Performance + +Different methods for checking key existence have varying performance +implications: + +``` +// Option 1: Using exists() - most explicit and readable +if (exists(user, "email")) { + sendEmail(user.email); +} + +// Option 2: Direct property access with null check +if (user.email != null) { + sendEmail(user.email); +} + +// Option 3: Using in operator with keys +if ("email" in keys(user)) { + sendEmail(user.email); +} +``` + +Option 1 is typically the most performant as it's specifically designed for +this purpose. + +### Dictionary Implementation Details + +Understanding internal implementation details can help write more efficient code: + +1. **Initial Capacity**: Dictionaries start with a small capacity and grow as needed +2. **Load Factor**: When dictionaries reach a certain fullness threshold, they're resized +3. **Hash Function**: Keys are hashed using a specialized string hashing function +4. **Collision Resolution**: Ucode typically uses open addressing with linear probing +5. **Deletion**: When keys are deleted, they're marked as deleted but space isn't reclaimed until rehashing +6. **Order Preservation**: Unlike many hash table implementations, ucode tracks and maintains insertion order + +These implementation details explain why: +- Iterating over a dictionary with many deleted keys might be slower +- Adding many keys may trigger occasional performance pauses for rehashing +- Key order is consistent and predictable, matching declaration/assignment order +- Dictionaries can be deliberately reordered using `sort()` + +## Conclusion + +Dictionaries in ucode provide a powerful and flexible way to organize data by +key-value relationships. By understanding their implementation characteristics +and following best practices, you can effectively leverage dictionaries for +everything from simple configuration storage to complex nested data structures. + +Remember that dictionaries excel at: +- Fast lookups by string key +- Dynamic property addition and removal +- Representing structured data +- Implementing caches and lookup tables + +When working with large dictionaries or performance-critical code, consider the +memory usage patterns and optimization techniques described in this article to +ensure your code remains efficient and maintainable. diff --git a/docs/tutorials/tutorials.json b/docs/tutorials/tutorials.json index df4e339..e6528cc 100644 --- a/docs/tutorials/tutorials.json +++ b/docs/tutorials/tutorials.json @@ -7,5 +7,11 @@ }, "03-memory": { "title": "Memory Management" + }, + "04-arrays": { + "title": "Working with Arrays" + }, + "05-dictionaries": { + "title": "Working with Dictionaries" } } |