193 lines
3.8 KiB
Markdown
193 lines
3.8 KiB
Markdown
# util
|
||
|
||
|
||
A collection of general-purpose utility functions for object manipulation, merging,
|
||
deep copying, safe property access, etc.
|
||
|
||
|
||
### guid() <sub>function</sub>
|
||
|
||
|
||
Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant).
|
||
|
||
|
||
**Returns**: A random 32-character string (hex).
|
||
|
||
|
||
### insertion_sort(arr, cmp) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
|
||
### deepfreeze(obj) <sub>function</sub>
|
||
|
||
|
||
Recursively freeze an object and all of its nested objects so they cannot be modified.
|
||
|
||
|
||
**obj**: The object to recursively freeze.
|
||
|
||
|
||
**Returns**: None
|
||
|
||
|
||
### dainty_assign(target, source) <sub>function</sub>
|
||
|
||
|
||
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
|
||
|
||
|
||
### get(obj, path, defValue) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
**path**: A string like "a.b.c" or an array of path segments.
|
||
|
||
**defValue**: The default value if the property is undefined.
|
||
|
||
|
||
**Returns**: The nested property or defValue.
|
||
|
||
|
||
### isEmpty(o) <sub>function</sub>
|
||
|
||
|
||
Return true if the object has no own properties, otherwise false.
|
||
|
||
|
||
**o**: The object to check.
|
||
|
||
|
||
**Returns**: Boolean indicating if the object is empty.
|
||
|
||
|
||
### dig(obj, path, def) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
**path**: A dot-string specifying nested objects to create.
|
||
|
||
**def**: The value to store in the final path component, default {}.
|
||
|
||
|
||
**Returns**: The assigned final value.
|
||
|
||
|
||
### access(obj, name) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
|
||
### mergekey(o1, o2, k) <sub>function</sub>
|
||
|
||
|
||
Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are
|
||
recursively merged.
|
||
|
||
|
||
**o1**: The target object.
|
||
|
||
**o2**: The source object.
|
||
|
||
**k**: The key to merge.
|
||
|
||
|
||
**Returns**: None
|
||
|
||
|
||
### merge(target, objs) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
|
||
### copy(proto, objs) <sub>function</sub>
|
||
|
||
|
||
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.
|
||
|
||
|
||
### obj_lerp(a, b, t) <sub>function</sub>
|
||
|
||
|
||
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()).
|
||
|
||
**b**: The end object (matching properties).
|
||
|
||
**t**: Interpolation factor (0..1).
|
||
|
||
|
||
**Returns**: A new object with interpolated properties.
|
||
|
||
|
||
### normalizeSpacing(spacing) <sub>function</sub>
|
||
|
||
|
||
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}.
|
||
|