doc/object.html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>amd-utils / object : AMD-Utils</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" href="assets_/css/shCore.css">
        <link rel="stylesheet" href="assets_/css/shThemeDefault.css">
        <link rel="stylesheet" href="assets_/css/main.css">
    </head>
    <body data-root-path="">
        <div id="wrapper">
            <div id="content">

<ul id="topnav">
    <li><a href="index.html">Index</a></li>
    <li><a href="#toc">TOC</a></li>
</ul>
<h1>amd-utils / object</h1>

<p>Object utilities.</p>

<h2>Table of Contents <a href="#toc" name="toc" class="deep-link">#</a></h2>

<ul>
<li><a href="#fillIn">fillIn()</a></li>
<li><a href="#forOwn">forOwn()</a></li>
<li><a href="#get">get()</a></li>
<li><a href="#has">has()</a></li>
<li><a href="#hasOwn">hasOwn()</a></li>
<li><a href="#keys">keys()</a></li>
<li><a href="#mixIn">mixIn()</a></li>
<li><a href="#namespace">namespace()</a></li>
<li><a href="#values">values()</a></li>
<li><a href="#set">set()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="#unset">unset()</a></li>
</ul>

<h2>fillIn(obj, ...default):Object <a href="#fillIn" id="fillIn" class="deep-link">#</a></h2>

<p>Fill in missing properties in object with values from the <em>defaults</em> objects.</p>

<pre><code>var base = {
    foo : 'bar',
    num : 123
};

fillIn({foo:'ipsum'}, base); // {foo:'ipsum', num:123}
</code></pre>

<p>PS: it allows merging multiple objects at once, the first ones will take
precedence.</p>

<h2>forOwn(obj, callback[, thisObj]) <a href="#forOwn" id="forOwn" class="deep-link">#</a></h2>

<p>Iterate over all own properties from an Object, similar to Array/forEach.</p>

<p>It <a href="https://developer.mozilla.org/en/ECMAScript_DontEnum_attribute#JScript_DontEnum_Bug">avoids don't enum bug on IE</a>.
Notice that it won't iterate over properties from the prototype.</p>

<p>See: <a href="#keys"><code>keys()</code></a>, <a href="#values"><code>values()</code></a></p>

<h3>Callback arguments</h3>

<p>Callback will receive the following arguments:</p>

<ol>
<li>Property Value (*)</li>
<li>Key name (String)</li>
<li>Target object (Object)</li>
</ol>

<h3>Example</h3>

<pre class="brush:js">

var obj = {
    foo : 1,
    bar : 2,
    lorem : 3
};

var result = 0;
var keys = [];

forOwn(obj, function(val, key, o){
    result += val;
    keys.push(key);
});

console.log(result); // 6
console.log(keys);   // ['foo', 'bar', 'lorem']
</pre>

<h2>get(obj, propName):* <a href="#get" id="get" class="deep-link">#</a></h2>

<p>Returns nested property value. Will return <code>undefined</code> if property doesn't
exist.</p>

<p>See: <a href="#set"><code>set()</code></a>, <a href="#namespace"><code>namespace()</code></a>, <a href="#has"><code>has()</code></a></p>

<pre class="brush:js">

var lorem = {
        ipsum : {
            dolor : {
                sit : 'amet'
            }
        }
    };

get(lorem, 'ipsum.dolor.sit'); // "amet"
get(lorem, 'foo.bar');         // undefined
</pre>

<h2>has(obj, propName):Boolean <a href="#has" id="has" class="deep-link">#</a></h2>

<p>Checks if object contains a child property. Useful for cases where you need to
check if an object contain a <em>nested</em> property. It will get properties
inherited by the prototype.</p>

<p>see: <a href="#hasOwn"><code>hasOwn()</code></a>, <a href="#get"><code>get()</code></a></p>

<pre class="brush:js">

var a = {
        b : {
            c : 123
        }
    };

has(a, 'b.c');   // true
has(a, 'foo.c'); // false
</pre>

<h3>Common use case</h3>

<pre class="brush:js">

if( has(a, 'foo.c') ){ // false
    // ...
}

if( a.foo.c ){ // ReferenceError: `foo` is not defined
    // ...
}
</pre>

<h2>hasOwn(obj, propName):Boolean <a href="#hasOwn" id="hasOwn" class="deep-link">#</a></h2>

<p>Safer <code>Object.hasOwnProperty</code>. Returns a boolean indicating whether the object
has the specified property.</p>

<p>see: <a href="#has"><code>has()</code></a></p>

<pre class="brush:js">

var obj = {
    foo: 1,
    hasOwnProperty : 'bar'
};

obj.hasOwnProperty('foo'); // ERROR! hasOwnProperty is not a function

hasOwn(obj, 'foo');            // true
hasOwn(obj, 'hasOwnProperty'); // true
hasOwn(obj, 'toString');       // false
</pre>

<h2>keys(obj):Array <a href="#keys" id="keys" class="deep-link">#</a></h2>

<p>Returns an array of all own enumerable properties found upon a given object.
It will use the native <code>Object.keys</code> if present.</p>

<p>PS: it won't return properties from the prototype.</p>

<p>See: <a href="#forOwn"><code>forOwn()</code></a>, <a href="#values"><code>values()</code></a></p>

<pre class="brush:js">

var obj = {
    foo : 1,
    bar : 2,
    lorem : 3
};
keys(obj); // ['foo', 'bar', 'lorem']
</pre>

<h2>mixIn(target, ...objects):Object <a href="#mixIn" id="mixIn" class="deep-link">#</a></h2>

<p>Combine properties from all the objects into first one.</p>

<p>This method affects target object in place, if you want to create a new Object
pass an empty object as first parameter.</p>

<h3>Arguments</h3>

<ol>
<li><code>target</code> (Object)        : Target Object.</li>
<li><code>...objects</code> (...Object) : Objects to be combined (0...n objects).</li>
</ol>

<h3>Example</h3>

<pre class="brush:js">

var a = {foo: "bar"};
var b = {lorem: 123};

mixIn({}, a, b); // {foo: "bar", lorem: 123}
console.log(a);  // {foo: "bar"}

mixIn(a, b);     // {foo: "bar", lorem: 123}
console.log(a);  // {foo: "bar", lorem: 123}
</pre>

<h2>namespace(obj, propName):Object <a href="#namespace" id="namespace" class="deep-link">#</a></h2>

<p>Creates an empty object inside namespace if not existent. Will return created
object or existing object.</p>

<p>See: <a href="#get"><code>get()</code></a>, <a href="#set"><code>set()</code></a></p>

<pre class="brush:js">

var obj = {};
namespace(obj, 'foo.bar'); // {}
console.log(obj);          // {foo:{bar:{}}}
</pre>

<h2>values(obj):Array <a href="#values" id="values" class="deep-link">#</a></h2>

<p>Returns an array of all own enumerable properties values found upon a given object.</p>

<p>PS: it won't return properties from the prototype.</p>

<p>See: <a href="#forOwn"><code>forOwn()</code></a>, <a href="#keys"><code>keys()</code></a></p>

<pre class="brush:js">

var obj = {
    foo : 1,
    bar : 2,
    lorem : 3
};
values(obj); // [1, 2, 3]
</pre>

<h2>set(obj, propName, value) <a href="#set" id="set" class="deep-link">#</a></h2>

<p>Sets a nested property value.</p>

<p>See: <a href="#get"><code>get()</code></a>, <a href="#namespace"><code>namespace()</code></a></p>

<pre class="brush:js">

var obj = {};
set(obj, 'foo.bar', 123);
console.log(obj.foo.bar); // 123
console.log(obj);         // {foo:{bar:123}}
</pre>

<h2>size(obj):Number <a href="#size" id="size" class="deep-link">#</a></h2>

<p>Returns the count of own enumerable properties found upon a given object.</p>

<p>PS: it won't return properties from the prototype.</p>

<p>See: <a href="#forOwn"><code>forOwn()</code></a>, <a href="#keys"><code>keys()</code></a></p>

<pre class="brush:js">

var obj = {
    foo : 1,
    bar : 2,
    lorem : 3
};
size(obj); // 3
</pre>

<h2>unset(obj, propName):Boolean <a href="#unset" id="unset" class="deep-link">#</a></h2>

<p>Delete object property if existent and returns a boolean indicating succes. It
will also return <code>true</code> if property doesn't exist.</p>

<p>Some properties can't be deleted, to understand why <a href="http://perfectionkills.com/understanding-delete/">check this
article</a>.</p>

<p>See: <a href="#set"><code>set()</code></a></p>

<pre class="brush:js">

var lorem = {
        ipsum : {
            dolor : {
                sit : 'amet'
            }
        }
    };

unset(lorem, 'ipsum.dolor.sit'); // true
console.log(lorem.ipsum.dolor);  // {}
unset(lorem, 'foo.bar');         // true
</pre>
                <hr />
                <small>Documentation generated by <a href="https://github.com/millermedeiros/mdoc">mdoc</a>.</small>
            </div>
        </div>
        <script src="assets_/js/lib/jquery.js"></script>
        <script src="assets_/js/lib/syntax-highlighter/shCore.js"></script>
        <script src="assets_/js/lib/syntax-highlighter/shAutoloader.js"></script>
        <script src="assets_/js/main.js"></script>
    </body>
</html>