Rename object/defaults to object/fillIn. Add lang/defaults and array/…

…find.

`fillIn` describes better the action and avoids naming conflicts. `find` is
required by `defaults` so "abstract ALL things!".

_build/doc/content/array.mdown

@@ -101,6 +101,18 @@ more info at [MDN Array#filter](https://developer.mozilla.org/en/JavaScript/Refe
 
 
 
+## find(arr, callback, [thisObj]):void
+
+Loops through all the items in the Array and returns the first one that passes
+a truth test (callback).
+
+    var arr = [123, {a:'b'}, 'foo', 'bar'];
+    find(arr, isString); // "foo"
+    find(arr, isNumber); // 123
+    find(arr, isObject); // {a:'b'}
+
+
+
 ## forEach(arr, callback, [thisObj]):void
 
 Crossbrowser ES5 `Array.forEach()`.

_build/doc/content/lang.mdown

@@ -69,6 +69,19 @@ john.walk(); // "John is walking"
 
 
 
+## defaults(val, ...defaults):void
+
+Return first value that isn't `null` or `undefined`.
+
+    function doSomethingAwesome(foo, bar) {
+        // default arguments
+        foo = defaults(foo, 'lorem');
+        bar = defaults(bar, 123);
+        // ...
+    }
+
+
+
 ## inheritPrototype(child, parent):void
 
 Inherit prototype from another Object.

_build/doc/content/object.mdown

@@ -4,7 +4,7 @@ Object utilities.
 
 
 
-## defaults(obj, ...default):Object
+## fillIn(obj, ...default):Object
 
 Fill in missing properties in object with values from the *defaults* objects.
 
@@ -13,7 +13,10 @@ Fill in missing properties in object with values from the *defaults* objects.
         num : 123
     };
 
-    defaults({foo:'ipsum'}, base); // {foo:'ipsum', num:123}
+    fillIn({foo:'ipsum'}, base); // {foo:'ipsum', num:123}
+
+PS: it allows merging multiple objects at once, the first ones will take
+precedence.
 
 
 

doc/array.html

@@ -30,6 +30,7 @@ <h2>Table of Contents <a href="#toc" name="toc" class="deep-link">#</a></h2>
 <li><a href="#difference">difference()</a></li>
 <li><a href="#every">every()</a></li>
 <li><a href="#filter">filter()</a></li>
+<li><a href="#find">find()</a></li>
 <li><a href="#forEach">forEach()</a></li>
 <li><a href="#indexOf">indexOf()</a></li>
 <li><a href="#insert">insert()</a></li>
@@ -137,6 +138,17 @@ <h2>filter(arr, callback, [thisObj]):Array <a href="#filter" id="filter" class="
 
 <p>more info at <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/filter">MDN Array#filter</a></p>
 
+<h2>find(arr, callback, [thisObj]):void <a href="#find" id="find" class="deep-link">#</a></h2>
+
+<p>Loops through all the items in the Array and returns the first one that passes
+a truth test (callback).</p>
+
+<pre><code>var arr = [123, {a:'b'}, 'foo', 'bar'];
+find(arr, isString); // "foo"
+find(arr, isNumber); // 123
+find(arr, isObject); // {a:'b'}
+</code></pre>
+
 <h2>forEach(arr, callback, [thisObj]):void <a href="#forEach" id="forEach" class="deep-link">#</a></h2>
 
 <p>Crossbrowser ES5 <code>Array.forEach()</code>.</p>

doc/lang.html

@@ -26,6 +26,7 @@ <h2>Table of Contents <a href="#toc" name="toc" class="deep-link">#</a></h2>
 <li><a href="#bind">bind()</a></li>
 <li><a href="#createObject">createObject()</a></li>
 <li><a href="#ctorApply">ctorApply()</a></li>
+<li><a href="#defaults">defaults()</a></li>
 <li><a href="#inheritPrototype">inheritPrototype()</a></li>
 <li><a href="#isArguments">isArguments()</a></li>
 <li><a href="#isArray">isArray()</a></li>
@@ -108,6 +109,18 @@ <h2>ctorApply(constructor, args):Object <a href="#ctorApply" id="ctorApply" clas
 john.walk(); // "John is walking"
 </pre>
 
+<h2>defaults(val, ...defaults):void <a href="#defaults" id="defaults" class="deep-link">#</a></h2>
+
+<p>Return first value that isn't <code>null</code> or <code>undefined</code>.</p>
+
+<pre><code>function doSomethingAwesome(foo, bar) {
+    // default arguments
+    foo = defaults(foo, 'lorem');
+    bar = defaults(bar, 123);
+    // ...
+}
+</code></pre>
+
 <h2>inheritPrototype(child, parent):void <a href="#inheritPrototype" id="inheritPrototype" class="deep-link">#</a></h2>
 
 <p>Inherit prototype from another Object.</p>

doc/object.html

@@ -23,7 +23,7 @@ <h1>amd-utils / object</h1>
 <h2>Table of Contents <a href="#toc" name="toc" class="deep-link">#</a></h2>
 
 <ul>
-<li><a href="#defaults">defaults()</a></li>
+<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>
@@ -37,7 +37,7 @@ <h2>Table of Contents <a href="#toc" name="toc" class="deep-link">#</a></h2>
 <li><a href="#unset">unset()</a></li>
 </ul>
 
-<h2>defaults(obj, ...default):Object <a href="#defaults" id="defaults" class="deep-link">#</a></h2>
+<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>
 
@@ -46,9 +46,12 @@ <h2>defaults(obj, ...default):Object <a href="#defaults" id="defaults" class="de
     num : 123
 };
 
-defaults({foo:'ipsum'}, base); // {foo:'ipsum', 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>

doc/sidebar_.html

@@ -44,6 +44,11 @@ <h4>filter(arr, callback, [thisObj]):Array</h4>
                     <span class="desc">Crossbrowser ES5 <code>Array.filter()</code>.</span>
                 </a>
 
+                <a class="toc-item" href="array.html#find">
+                    <h4>find(arr, callback, [thisObj]):void</h4>
+                    <span class="desc">Loops through all the items in the Array and returns the first one that passes a truth test (callback).</span>
+                </a>
+
                 <a class="toc-item" href="array.html#forEach">
                     <h4>forEach(arr, callback, [thisObj]):void</h4>
                     <span class="desc">Crossbrowser ES5 <code>Array.forEach()</code>.</span>
@@ -182,6 +187,11 @@ <h4>ctorApply(constructor, args):Object</h4>
                     <span class="desc">Do <code>Function.prototype.apply()</code> on a constructor while maintaining prototype chain.</span>
                 </a>
 
+                <a class="toc-item" href="lang.html#defaults">
+                    <h4>defaults(val, ...defaults):void</h4>
+                    <span class="desc">Return first value that isn't <code>null</code> or <code>undefined</code>.</span>
+                </a>
+
                 <a class="toc-item" href="lang.html#inheritPrototype">
                     <h4>inheritPrototype(child, parent):void</h4>
                     <span class="desc">Inherit prototype from another Object.</span>
@@ -377,8 +387,8 @@ <h4>toUInt31(val):Number</h4>
             <h3 class="toc-mod-title"><a href="object.html">object</a></h3>
             <div class="toc-list">
 
-                <a class="toc-item" href="object.html#defaults">
-                    <h4>defaults(obj, ...default):Object</h4>
+                <a class="toc-item" href="object.html#fillIn">
+                    <h4>fillIn(obj, ...default):Object</h4>
                     <span class="desc">Fill in missing properties in object with values from the <em>defaults</em> objects.</span>
                 </a>
 

src/array.js

@@ -10,6 +10,7 @@ return {
     'difference' : require('./array/difference'),
     'every' : require('./array/every'),
     'filter' : require('./array/filter'),
+    'find' : require('./array/find'),
     'forEach' : require('./array/forEach'),
     'indexOf' : require('./array/indexOf'),
     'insert' : require('./array/insert'),

src/array/find.js

@@ -0,0 +1,20 @@
+define(['./some'], function (some) {
+
+    /**
+     * Returns first item that matches criteria
+     * @version 0.1.0 (2012/02/28)
+     */
+    function find(arr, iterator, thisObj){
+        var needle;
+        some(arr, function(val, i, arr){
+            if (iterator.call(thisObj, val, i, arr)) {
+                needle = val;
+                return true; // stop loop
+            }
+        });
+        return needle;
+    }
+
+    return find;
+
+});

src/lang.js

@@ -6,6 +6,7 @@ return {
     'bind' : require('./lang/bind'),
     'createObject' : require('./lang/createObject'),
     'ctorApply' : require('./lang/ctorApply'),
+    'defaults' : require('./lang/defaults'),
     'inheritPrototype' : require('./lang/inheritPrototype'),
     'isArguments' : require('./lang/isArguments'),
     'isArray' : require('./lang/isArray'),

src/lang/defaults.js

@@ -0,0 +1,17 @@
+define(['./toArray', '../array/find'], function (toArray, find) {
+
+    /**
+     * Return first non void argument
+     * @version 0.1.0 (2012/02/28)
+     */
+    function defaults(var_args){
+        return find(toArray(arguments), nonVoid);
+    }
+
+    function nonVoid(val){
+        return val != null;
+    }
+
+    return defaults;
+
+});

src/object.js

@@ -3,7 +3,7 @@ define(function(require){
 //automatically generated, do not edit!
 //run `node build` instead
 return {
-    'defaults' : require('./object/defaults'),
+    'fillIn' : require('./object/fillIn'),
     'forOwn' : require('./object/forOwn'),
     'get' : require('./object/get'),
     'has' : require('./object/has'),

src/object/defaults.js → src/object/fillIn.js

@@ -4,7 +4,7 @@ define(['../array/forEach', './forOwn'], function (forEach, forOwn) {
      * Copy missing properties in the obj from the defaults.
      * @version 0.1.0 (2012/02/25)
      */
-    function defaults(obj, var_defaults){
+    function fillIn(obj, var_defaults){
         forEach(Array.prototype.slice.call(arguments, 1), function(base){
             forOwn(base, function(val, key){
                 if (obj[key] == null) {
@@ -15,6 +15,6 @@ define(['../array/forEach', './forOwn'], function (forEach, forOwn) {
         return obj;
     }
 
-    return defaults;
+    return fillIn;
 
 });

tests/spec/array/spec-find.js

@@ -0,0 +1,18 @@
+define(['src/array/find'], function (find) {
+
+    describe('array/find', function () {
+
+        it('should return first match', function () {
+
+            var obj = {a : 'b'},
+                arr = [123, 'foo', 'bar', obj];
+
+            expect( find(arr, function(val){ return val === 123; }) ).toEqual( 123 );
+            expect( find(arr, function(val){ return typeof val === 'string'; }) ).toEqual( 'foo' );
+            expect( find(arr, function(val){ return val.a === 'b'; }) ).toEqual( obj );
+
+        });
+
+    });
+
+});

tests/spec/lang/spec-defaults.js

@@ -0,0 +1,25 @@
+define(['src/lang/defaults'], function (defaults) {
+
+    describe('lang/defaults', function () {
+
+        it('should return first non void value', function () {
+
+            var a,
+                b = null;
+
+            expect( defaults(a, 'foo') ).toEqual( 'foo' );
+            expect( defaults(b, 'bar') ).toEqual( 'bar' );
+            expect( defaults(a, b, 123) ).toEqual( 123 );
+            expect( defaults(a, b, 123, 'dolor') ).toEqual( 123 );
+            expect( defaults(a, false, b, 123, 'dolor') ).toEqual( false );
+            expect( defaults(a, true, b, 123, 'dolor') ).toEqual( true );
+
+            var obj = {};
+            expect( defaults(obj, a, b, 123, 'dolor') ).toEqual( obj );
+            expect( defaults(a, b, obj, 123, 'dolor') ).toEqual( obj );
+
+        });
+
+    });
+
+});

tests/spec/object/spec-defaults.js → tests/spec/object/spec-fillIn.js

@@ -1,6 +1,6 @@
-define(['src/object/defaults'], function (defaults) {
+define(['src/object/fillIn'], function (fillIn) {
 
-    describe('object/defaults', function () {
+    describe('object/fillIn', function () {
 
         it('should copy missing properties', function () {
 
@@ -12,7 +12,7 @@ define(['src/object/defaults'], function (defaults) {
                 }
             };
 
-            var obj = defaults({lorem : 'ipsum'}, a);
+            var obj = fillIn({lorem : 'ipsum'}, a);
 
             expect( obj.foo ).toEqual( 'bar' );
             expect( obj.lorem ).toEqual( 'ipsum' );
@@ -23,7 +23,7 @@ define(['src/object/defaults'], function (defaults) {
 
         it('should allow copying properties from multiple objects', function () {
 
-            var obj = defaults({lorem : 'ipsum'},
+            var obj = fillIn({lorem : 'ipsum'},
                                {foo : 'bar', lorem : 'dolor'},
                                {num : 123});
 

tests/spec/spec-array.js

@@ -8,6 +8,7 @@ define([
     'array/spec-difference',
     'array/spec-every',
     'array/spec-filter',
+    'array/spec-find',
     'array/spec-forEach',
     'array/spec-indexOf',
     'array/spec-insert',

tests/spec/spec-lang.js

@@ -4,6 +4,7 @@ define([
     'lang/spec-bind',
     'lang/spec-createObject',
     'lang/spec-ctorApply',
+    'lang/spec-defaults',
     'lang/spec-inheritPrototype',
     'lang/spec-isArguments',
     'lang/spec-isArray',

tests/spec/spec-object.js

@@ -1,7 +1,7 @@
 //automatically generated, do not edit!
 //run `node build` instead
 define([
-    'object/spec-defaults',
+    'object/spec-fillIn',
     'object/spec-forOwn',
     'object/spec-get',
     'object/spec-has',