# 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}.