john/cell
1
0
Fork 0
Code Issues 31 Pull Requests Packages Projects Releases 2 Wiki Activity

document c types

Browse Source
This commit is contained in:
John Alanbrook
2025-02-09 00:00:40 -06:00
parent 95c64f51de
commit 7cffdab28a
89 changed files with 4133 additions and 1390 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
docs/api/modules/util.md
View File

@@ -1,56 +1,65 @@
# util
# util
A collection of general-purpose utility functions for object manipulation, merging,
deep copying, safe property access, etc.
## guid()
### guid
**Returns**: A random 32-character string (hex).
Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant).
## insertion_sort(arr, cmp)
**Returns**: A random 32-character string (hex).
### insertion_sort(arr, cmp)
In-place insertion sort of an array using cmp(a,b)->Number for ordering.
**arr**: The array to be sorted in-place.
**cmp**: Comparison function cmp(a,b)->Number.
**Returns**: The same array, sorted in-place.
In-place insertion sort of an array using cmp(a,b)->Number for ordering.
### deepfreeze(obj)
## deepfreeze(obj)
**obj**: The object to recursively freeze.
**Returns**: None
Recursively freeze an object and all of its nested objects so they cannot be modified.
## dainty_assign(target, source)
**obj**: The object to recursively freeze.
**Returns**: None
### dainty_assign(target, source)
Copy non-function properties from source into matching keys of target without overwriting
keys that don't exist in target. Arrays are deep-copied, and objects are recursively assigned.
**target**: The target object whose keys may be updated.
**source**: The source object containing new values.
**Returns**: None
Copy non-function properties from source into matching keys of target without overwriting
keys that don't exist in target. Arrays are deep-copied, and objects are recursively assigned.
### get(obj, path, defValue)
## get(obj, path, defValue)
Safely retrieve a nested property from obj at path (array or dot-string).
Returns defValue if the property is undefined.
**obj**: The object to traverse.
@@ -59,23 +68,27 @@ keys that don't exist in target. Arrays are deep-copied, and objects are recursi
**defValue**: The default value if the property is undefined.
**Returns**: The nested property or defValue.
Safely retrieve a nested property from obj at path (array or dot-string).
Returns defValue if the property is undefined.
### isEmpty(o)
## isEmpty(o)
**o**: The object to check.
**Returns**: Boolean indicating if the object is empty.
Return true if the object has no own properties, otherwise false.
## dig(obj, path, def)
**o**: The object to check.
**Returns**: Boolean indicating if the object is empty.
### dig(obj, path, def)
Ensure a nested path of objects exists inside obj; create objects if missing, and set
the final path component to def.
**obj**: The root object to modify.
@@ -84,26 +97,30 @@ Return true if the object has no own properties, otherwise false.
**def**: The value to store in the final path component, default {}.
**Returns**: The assigned final value.
Ensure a nested path of objects exists inside obj; create objects if missing, and set
the final path component to def.
### access(obj, name)
## access(obj, name)
Traverse obj by dot-separated path name, returning the final value or undefined
if any step is missing.
**obj**: The object to traverse.
**name**: A dot-string path (e.g. "foo.bar.baz").
**Returns**: The value at that path, or undefined if missing.
Traverse obj by dot-separated path name, returning the final value or undefined
if any step is missing.
### mergekey(o1, o2, k)
## mergekey(o1, o2, k)
Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are
recursively merged.
**o1**: The target object.
@@ -112,38 +129,44 @@ if any step is missing.
**k**: The key to merge.
**Returns**: None
Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are
recursively merged.
### merge(target, objs)
## merge(target, objs)
Merge all passed objects into target, copying or merging each key as needed.
Arrays are deep-copied, objects are recursively merged, etc.
**target**: The target object.
**objs**: One or more objects to merge into target.
**Returns**: The updated target object.
Merge all passed objects into target, copying or merging each key as needed.
Arrays are deep-copied, objects are recursively merged, etc.
### copy(proto, objs)
## copy(proto, objs)
Create a new object with proto as its prototype, then mix in additional objects’ properties.
**proto**: The prototype object for the new object.
**objs**: One or more objects whose properties will be mixed in.
**Returns**: The newly created object.
Create a new object with proto as its prototype, then mix in additional objects’ properties.
### obj_lerp(a, b, t)
## obj_lerp(a, b, t)
Linearly interpolate between two objects a and b by factor t, assuming each property
supports .lerp().
**a**: The start object (its properties must have .lerp()).
@@ -152,18 +175,18 @@ Create a new object with proto as its prototype, then mix in additional objects
**t**: Interpolation factor (0..1).
**Returns**: A new object with interpolated properties.
Linearly interpolate between two objects a and b by factor t, assuming each property
supports .lerp().
### normalizeSpacing(spacing)
## normalizeSpacing(spacing)
Normalize any spacing input into a {l, r, t, b} object.
**spacing**: A number, an array of length 2 or 4, or an object with l/r/t/b.
**Returns**: An object {l, r, t, b}.
Normalize any spacing input into a {l, r, t, b} object.