JSDoc: Module: undermore

undermore fills in the gaps where standards lag behind by providing a lot of tiny functions that really should just already be there--these are tiny, unit tested additions to underscore.js, which reside in _.* -- e.g. _.uuid()

Copyright:

2013 Adam Eivy (@antic)

License:

Source:

all.js, line 54

Methods

<static> alphabetize(obj) → {mixed}

sort the keys in an object alphabetically, recursively

Parameters:

Name	Type	Description
`obj`	object	The object to traverse

Source:

all.js, line 87

Returns:

the object with alphabetized keys

Type: mixed

Example

var obj = {
   b: 1,
   a: 2
};
JSON.stringify(_.alphabetize(obj)) === '{"a":2,"b":1}'

<static> base64_decode(str) → {string}

base64_decode decode a string. This is not a strict polyfill for window.atob because it handles unicode characters

Parameters:

Name	Type	Description
`str`	string	The string to decode

Source:

all.js, line 126

Returns:

Type: string

Example

_.base64_decode('4pyI') => '✈'

<static> base64_encode(str) → {string}

base64_encode encode a string. This is not a strict window.btoa polyfill because it handles utf8 strings (unlike the window.btoa spec) Note: it might be work including an urlsafe flag (see https://github.com/knowledgecode/base64.js)

Parameters:

Name	Type	Description
`str`	string	The string to encode

Source:

all.js, line 168

Returns:

Type: string

Example

_.base64_decode('✈') => '4pyI'

<static> eFn()

empty event handler function, which simply prevents default handling

Source:

all.js, line 210

Example

$('#thing').on('click',this.conf.onClick||_.eFn)

<static> fn() → {boolean}

Generic empty function to speed up supplying anon empty functions. If you are using jQuery, you could use $.noop if returning undefined is desireable but this one is useful for anything requiring a boolean true return

Source:

all.js, line 220

Returns:

true

Type: boolean

Example

this.onComplete = conf.onComplete||_.fn;

<static> fnMore(originalFn, moreFn, scope) → {function}

get a new function, which runs two functions serially within a given context

Parameters:

Name	Type	Description
`originalFn`	function	The original function to run
`moreFn`	function	The extra function to run in the same context after the first
`scope`	object	The context in which to run the fn

Source:

all.js, line 234

Returns:

the new function which will serially call the given functions in the given scope

Type: function

Example

var fn = _.fnMore(oldFn,newFn,someObj);
fn();
// runs oldFn, then newFn in the context of someObj

<static> get(obj, chain, defaultValue) → {mixed}

Get a deep value on an Object safely (optionally with a default value). Run jsperf test

Parameters:

Name	Type	Description
`obj`	object	The object to traverse
`chain`	mixed	A string/array path to use for finding the end item (e.g. 'prop.child.end' or ['prop','child','end'])
`defaultValue`	mixed	The object to traverse

Source:

all.js, line 257

Returns:

the last item in the ks or the defaultValue

Type: mixed

Example

var obj = {
   prop: 1
};
_.get(obj,'prop','blarg') === 1
_.get(obj,'prop.child','blarg') === 'blarg'
_.get(obj,'thing','blarg') === 'blarg'
_.get(obj) === obj

<static> getQuery(key, defaultValue) → {mixed}

Get the requested key from the query string. If no key is provided, return a map of all query string values. Run jsperf test

Parameters:

Name	Type	Description
`key`	string	The key to retrieve from the query string
`defaultValue`	mixed	The default value to return if key does not exist

Source:

all.js, line 298

Returns:

the query value or the defaultValue

Type: mixed

<static> isValidDate(value) → {bool}

test if a value is a valid Date instance, with a valid date

Parameters:

Name	Type	Description
`value`	object	Something to test

Source:

all.js, line 343

Returns:

Whether or not the date is valid

Type: bool

Example

var d = new Date('foobar') => Invalid Date
d.getTime() => NaN 
_.isDate(d) => true
// even though this is a Date object instance, 
// it isn't a valid date... so:
_.isValidDate(d) => false

<static> ord(n) → {string}

Get the english ordinal suffix for any number

Parameters:

Name	Type	Description
`n`	number	number The number to evaluate

Source:

all.js, line 360

Returns:

The ordinal for that number

Type: string

Example

_.ord(1) === 'st'
_.ord(345) === 'th'

<static> set(obj, chain, value) → {mixed}

Set a deep value on an object (even if the key path doesn't exist) this is a shorthand for _.extend(), which is useful in cases where you can't easily build the extension object e.g. if you are building a path from variable names: _.set(obj, 'prop.'+varName+'.key', value); // 1 line vs: 3 lines with _.extend var extendObj = {prop:{}}; extendObj.prop[varName] = {key:value}; _.extend(obj, extendObj);

Parameters:

Name	Type	Description
`obj`	object	The object to traverse
`chain`	mixed	A string/array path to use for finding the end item (e.g. 'prop.child.end' or ['prop','child','end'])
`value`	mixed	The value to set the end key to

Source:

all.js, line 375

Returns:

The full new extended object

Type: mixed

Example

var data = {
        prop: {}
    };

deepEqual(_.set(data, 'prop', 1), _.extend(data, {prop:1}) );
deepEqual(_.set(data, 'prop.foo', 'fooVal'),  _.extend(data, {prop:{foo:'fooVal'}}) );
deepEqual(_.set(data, 'newKey', 'newVal'),  _.extend(data, {newKey:'newVal'}) );
deepEqual(_.set(data, 'deep.key.that.does.not.exist', 'deepVal'),  _.extend(data, {
    deep: {
         key:{
             that:{
                 does:{
                     not:{
                         exist:'deepVal'
                     }
                 }
             }
         }
     }
}));

<static> utf8_decode(str) → {string}

utf8 decode a string

Parameters:

Name	Type	Description
`str`	string	The string to decode

Source:

all.js, line 431

Returns:

Type: string

Example

_.utf8_decode('asdf') === 'asdf';
_.utf8_decode('è¤é') === '複雜';
_.utf8_decode('â') === '✈';

<static> utf8_encode(str) → {string}

utf8 encode a string

Parameters:

Name	Type	Description
`str`	string	The string to encode

Source:

all.js, line 448

Returns:

Type: string

Example

_.utf8_encode('asdf') === 'asdf';
_.utf8_encode('✈') === 'â';
_.utf8_encode('複雜') === 'è¤é';

<static> uuid() → {string}

generate a random v4 UUID of the form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, where each x is replaced with a random hexadecimal digit from 0 to f, and y is replaced with a random hexadecimal digit from 8 to b.

Source:

all.js, line 464

Returns:

random uuid

Type: string

Example

var uuid = _.uuid();

<static> version(left, oper, right) → {bool}

Compare a semantic version number string to another: 1.2.3-alpha < 1.2.3-alpha.1 < 1.2.3-alpha.beta < 1.2.3-beta < 1.2.3-beta.2 < 1.2.3-beta.11 < 1.2.3-rc.1 < 1.2.3

Parameters:

Name	Type	Description
`left`	string	The left version
`oper`	string	The operator to use for comparison ('==','>=','<=','<','>')
`right`	string	The right version

Source:

all.js, line 483

See:

Semantic Versioning Standard

Returns:

whether or not the versions resolved true with the comparitor

Type: bool

Example

ok(_.version('1.2.3','<','2.0.0'), 'major version is smaller');
ok(_.version('1.1.0','<','1.2.0'), 'minor version is smaller');
ok(!_.version('1.1.0','>','1.2.0'), 'minor version is smaller');
ok(_.version('1.0.10','>=','1.0.2'), 'patch version 10 is greater than or equal to 2');
ok(_.version('1.2.3-alpha','<','1.2.3-alpha.1'));
ok(_.version('1.2.3-alpha.1','<','1.2.3-alpha.beta'));
ok(_.version('1.2.3-alpha.beta','<','1.2.3-beta'));
ok(_.version('1.2.3-beta','<','1.2.3-beta.2'));
ok(_.version('1.2.3-beta.2','<','1.2.3-beta.11'));
ok(_.version('1.2.3-beta.11','<','1.2.3-rc.1'));
ok(_.version('1.2.3-rc.1','<','1.2.3'));