Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Documentation clarifications #592

Closed
wants to merge 10 commits into from

3 participants

@cederberg

Clarified the documentation for the isX() functions. In particular their handling of primitive vs. wrapper objects, null values and such.

index.html
((5 lines not shown))
</p>
<pre>
_.isEmpty([1, 2, 3]);
=&gt; false
-_.isEmpty({});
-=&gt; true
+
+_.map([null, {}, [], ""], _.isEmpty)
+=&gt; [true, true, true, true]
@braddunbar Collaborator

How about this instead? It's a bit more succinct.

_.all([null, {}, [], ""], _.isEmpty);
=&gt; true
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
index.html
@@ -1148,13 +1158,18 @@ <h2 id="objects">Object Functions</h2>
<p id="isObject">
<b class="header">isObject</b><code>_.isObject(value)</code>
<br />
- Returns <i>true</i> if <b>value</b> is an Object.
+ Returns <i>true</i> if <b>value</b> is an Object. Returns
+ <i>false</i> for primitive types and <tt>null</tt>.
@braddunbar Collaborator

null is a primitive value itself so I think this could just be "Returns false for primitive types."

Technically yes, but since typeof null == 'object' I think this clarification is needed. :-(

@braddunbar Collaborator

Fair enough, how about "Returns false for primitive types, including null." That way we clarify but don't imply that null is not a primitive.

Agreed & fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
index.html
((12 lines not shown))
_.isObject(1);
=&gt; false
+
+_.map([null, 0, true, ""], _.isObject)
+=&gt; [false, false, false, false]
</pre>
@braddunbar Collaborator

Same as above.

_.any([null, 0, true, ""], _.isObject);
=&gt; false
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
index.html
((8 lines not shown))
</p>
<pre>
_.isNumber(8.4 * 5);
=&gt; true
+
+_.isNumber(1 / 0);
+=&gt; true
@braddunbar Collaborator

I think this is clearer as _.isNumber(Infinity);.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
index.html
((22 lines not shown))
</p>
<pre>
_.isFinite(-101);
=&gt; true
-_.isFinite(-Infinity);
+_.isFinite(42 / 0);
@braddunbar Collaborator

Same as above.

Yeah, you're probably right. Got a bit carried away by my random test cases... ;-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jashkenas
Owner

Thanks, but I'm of the opinion that many of these changes are unnecessarily pedantic. We don't need to discuss wrapped primitive types, because the use of wrapped primitive types in JS is an antipattern.

I think our documentation should describe what a function is for ... not necessarily list its output for every possible type of input.

@jashkenas jashkenas closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 49 additions and 15 deletions.
  1. +49 −15 index.html
View
64 index.html
@@ -352,6 +352,7 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
<pre>
_.each([1, 2, 3], function(num){ alert(num); });
=&gt; alerts each number in turn...
+
_.each({one : 1, two : 2, three : 3}, function(num, key){ alert(num); });
=&gt; alerts each number in turn...</pre>
@@ -367,6 +368,7 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
<pre>
_.map([1, 2, 3], function(num){ return num * 3; });
=&gt; [3, 6, 9]
+
_.map({one : 1, two : 2, three : 3}, function(num, key){ return num * 3; });
=&gt; [3, 6, 9]</pre>
@@ -378,7 +380,7 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
<b>list</b> of values into a single value. <b>Memo</b> is the initial state
of the reduction, and each successive step of it should be returned by
<b>iterator</b>. The iterator is passed four arguments: the <tt>memo</tt>,
- then the <tt>value</tt> and <tt>index</tt> (or key) of the iteration,
+ then the <tt>value</tt> and <tt>index</tt> (or key) of the iteration,
and finally a reference to the entire <tt>list</tt>.
</p>
<pre>
@@ -791,12 +793,16 @@ <h2 id="arrays">Array Functions</h2>
<pre>
_.range(10);
=&gt; [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
_.range(1, 11);
=&gt; [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
_.range(0, 30, 5);
=&gt; [0, 5, 10, 15, 20, 25]
+
_.range(0, -10, -1);
=&gt; [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
+
_.range(0);
=&gt; []
</pre>
@@ -907,7 +913,7 @@ <h2 id="functions">Function (uh, ahem) Functions</h2>
preview of a Markdown comment, recalculating a layout after the window
has stopped being resized, and so on.
</p>
-
+
<p>
Pass <tt>true</tt> for the <b>immediate</b> parameter to cause
<b>debounce</b> to trigger the function on the leading instead of the
@@ -915,7 +921,7 @@ <h2 id="functions">Function (uh, ahem) Functions</h2>
preventing accidental double-clicks on a "submit" button from firing a
second time.
</p>
-
+
<pre>
var lazyLayout = _.debounce(calculateLayout, 300);
$(window).resize(lazyLayout);
@@ -1107,6 +1113,7 @@ <h2 id="objects">Object Functions</h2>
var clone = {name : 'moe', luckyNumbers : [13, 27, 34]};
moe == clone;
=&gt; false
+
_.isEqual(moe, clone);
=&gt; true
</pre>
@@ -1115,11 +1122,13 @@ <h2 id="objects">Object Functions</h2>
<b class="header">isEmpty</b><code>_.isEmpty(object)</code>
<br />
Returns <i>true</i> if <b>object</b> contains no values.
+ Handles arrays, objects and strings.
</p>
<pre>
_.isEmpty([1, 2, 3]);
=&gt; false
-_.isEmpty({});
+
+_.all([null, {}, [], ""], _.isEmpty)
=&gt; true
</pre>
@@ -1141,6 +1150,7 @@ <h2 id="objects">Object Functions</h2>
<pre>
(function(){ return _.isArray(arguments); })();
=&gt; false
+
_.isArray([1,2,3]);
=&gt; true
</pre>
@@ -1148,13 +1158,18 @@ <h2 id="objects">Object Functions</h2>
<p id="isObject">
<b class="header">isObject</b><code>_.isObject(value)</code>
<br />
- Returns <i>true</i> if <b>value</b> is an Object.
+ Returns <i>true</i> if <b>value</b> is an Object. Returns
+ <i>false</i> for primitive types, including <tt>null</tt>.
</p>
<pre>
_.isObject({});
=&gt; true
+
_.isObject(1);
=&gt; false
+
+_.any([null, 0, true, ""], _.isObject)
+=&gt; false
</pre>
<p id="isArguments">
@@ -1165,6 +1180,7 @@ <h2 id="objects">Object Functions</h2>
<pre>
(function(){ return _.isArguments(arguments); })(1, 2, 3);
=&gt; true
+
_.isArguments([1,2,3]);
=&gt; false
</pre>
@@ -1183,6 +1199,7 @@ <h2 id="objects">Object Functions</h2>
<b class="header">isString</b><code>_.isString(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is a String.
+ Handles both primitive strings and <tt>String</tt> instances.
</p>
<pre>
_.isString("moe");
@@ -1192,17 +1209,23 @@ <h2 id="objects">Object Functions</h2>
<p id="isNumber">
<b class="header">isNumber</b><code>_.isNumber(object)</code>
<br />
- Returns <i>true</i> if <b>object</b> is a Number (including <tt>NaN</tt>).
+ Returns <i>true</i> if <b>object</b> is a Number (including <tt>NaN</tt>
+ and <tt>Infinity</tt>). Handles both primitive numbers and
+ <tt>Number</tt> instances.
</p>
<pre>
_.isNumber(8.4 * 5);
=&gt; true
+
+_.isNumber(NaN);
+=&gt; true
</pre>
<p id="isFinite">
<b class="header">isFinite</b><code>_.isFinite(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is a finite Number.
+ Implies that <tt>_.isNumber(object)</tt> is also true.
</p>
<pre>
_.isFinite(-101);
@@ -1216,10 +1239,14 @@ <h2 id="objects">Object Functions</h2>
<b class="header">isBoolean</b><code>_.isBoolean(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is either <i>true</i> or <i>false</i>.
+ Handles both primitive values and <tt>Boolean</tt> instances.
</p>
<pre>
_.isBoolean(null);
=&gt; false
+
+_.isBoolean(true || false);
+=&gt; true
</pre>
<p id="isDate">
@@ -1246,14 +1273,16 @@ <h2 id="objects">Object Functions</h2>
<b class="header">isNaN</b><code>_.isNaN(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is <i>NaN</i>.<br /> Note: this is not
- the same as the native <b>isNaN</b> function, which will also return
+ the same as the native <tt>isNaN</tt> function, which will also return
true if the variable is <i>undefined</i>.
</p>
<pre>
_.isNaN(NaN);
=&gt; true
+
isNaN(undefined);
=&gt; true
+
_.isNaN(undefined);
=&gt; false
</pre>
@@ -1266,6 +1295,7 @@ <h2 id="objects">Object Functions</h2>
<pre>
_.isNull(null);
=&gt; true
+
_.isNull(undefined);
=&gt; false
</pre>
@@ -1278,6 +1308,9 @@ <h2 id="objects">Object Functions</h2>
<pre>
_.isUndefined(window.missingVariable);
=&gt; true
+
+_.isUndefined(null);
+=&gt; false
</pre>
<h2 id="utility">Utility Functions</h2>
@@ -1359,6 +1392,7 @@ <h2 id="utility">Utility Functions</h2>
var object = {cheese: 'crumpets', stuff: function(){ return 'nonsense'; }};
_.result(object, 'cheese');
=&gt; "crumpets"
+
_.result(object, 'stuff');
=&gt; "nonsense"</pre>
@@ -1576,21 +1610,21 @@ <h2 id="links">Links &amp; Suggested Reading</h2>
</p>
<h2 id="changelog">Change Log</h2>
-
+
<p>
<b class="header">1.3.3</b> &mdash; <small><i>April 10, 2012</i></small><br />
<ul>
<li>
- Many improvements to <tt>_.template</tt>, which now provides the
+ Many improvements to <tt>_.template</tt>, which now provides the
<tt>source</tt> of the template function as a property, for potentially
even more efficient pre-compilation on the server-side. You may now
- also set the <tt>variable</tt> option when creating a template,
- which will cause your passed-in data to be made available under the
+ also set the <tt>variable</tt> option when creating a template,
+ which will cause your passed-in data to be made available under the
variable you named, instead of using a <tt>with</tt> statement &mdash;
significantly improving the speed of rendering the template.
</li>
<li>
- Added the <tt>pick</tt> function, which allows you to filter an
+ Added the <tt>pick</tt> function, which allows you to filter an
object literal with a whitelist of allowed property names.
</li>
<li>
@@ -1614,7 +1648,7 @@ <h2 id="changelog">Change Log</h2>
</li>
<li>
The <tt>debounce</tt> function now takes an <tt>immediate</tt>
- parameter, which will cause the callback to fire on the leading
+ parameter, which will cause the callback to fire on the leading
instead of the trailing edge.
</li>
</ul>
@@ -1654,8 +1688,8 @@ <h2 id="changelog">Change Log</h2>
<b class="header">1.2.4</b> &mdash; <small><i>Jan. 4, 2012</i></small><br />
<ul>
<li>
- You now can (and probably should, as it's simpler)
- write <tt>_.chain(list)</tt>
+ You now can (and probably should, as it's simpler)
+ write <tt>_.chain(list)</tt>
instead of <tt>_(list).chain()</tt>.
</li>
<li>
Something went wrong with that request. Please try again.