lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: minor improvements to util.md 

PR-URL: https://github.com/nodejs/node/pull/6932
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
v7.x
Sakthipriyan Vairamani 9 years ago
parent
ead6c2d5bb
commit
435e673efd
1 changed files with 79 additions and 77 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 156
      doc/api/util.md

156
doc/api/util.md
View File

@ -19,12 +19,13 @@ const util = require('util');
The `util.debuglog()` method is used to create a function that conditionally
writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`
environment variable. If the `section` name appears within the value of that
environment variable, then the returned function operate similar to
environment variable, then the returned function operates similar to
`console.error()`. If not, then the returned function is a no-op.
For example:
```js
const util = require('util');
const debuglog = util.debuglog('foo');
debuglog('hello from foo [%d]', 123);
@ -46,7 +47,7 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`.
## util.deprecate(function, string)
The `util.deprecate()` method wraps the given `function` in such a way that
marks it as being deprecated.
it is marked as deprecated.
```js
const util = require('util');
@ -58,10 +59,10 @@ exports.puts = util.deprecate(() => {
}, 'util.puts: Use console.log instead');
```
When called, `util.deprecated()` will return a function that will emit a
When called, `util.deprecate()` will return a function that will emit a
`DeprecationWarning` using the `process.on('warning')` event. By default,
this warning will be emitted and printed to `stderr` exactly once the first
time that it is called. After the warning is emitted, the wrapped `function`
this warning will be emitted and printed to `stderr` exactly once, the first
time it is called. After the warning is emitted, the wrapped `function`
is called.
If either the `--no-deprecation` or `--no-warnings` command line flags are
@ -106,10 +107,10 @@ util.format('%s:%s', 'foo');
// Returns 'foo:%s'
```
If there are more arguments passed to the `util.format()` method than there are
placeholders, the extra arguments are coerced into strings (for objects and
symbols, `util.inspect()` is used) then concatenated to the returned string,
delimited by a space.
If there are more arguments passed to the `util.format()` method than the
number of placeholders, the extra arguments are coerced into strings (for
objects and symbols, `util.inspect()` is used) then concatenated to the
returned string, each delimited by a space.
```js
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
@ -125,7 +126,7 @@ util.format(1, 2, 3); // '1 2 3'
## util.inherits(constructor, superConstructor)
_Note: usage of util.inherits() is discouraged. Please use the ES6 `class` and
_Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
`extends` keywords to get language level inheritance support. Also note that
the two styles are [semantically incompatible][]._
@ -153,7 +154,7 @@ MyStream.prototype.write = function(data) {
this.emit('data', data);
}
var stream = new MyStream();
const stream = new MyStream();
console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true
@ -168,12 +169,11 @@ stream.write('It works!'); // Received data: "It works!"
* `object` {any} Any JavaScript primitive or Object.
* `options` {Object}
* `showHidden` {boolean} If `true`, the `object`'s non-enumerable and
symbol properties will be included in the formatted result. Defaults to
`false`.
* `depth` (number) Specifies how many times to recurse while formatting the
`object`. This is useful for inspecting large complicated objects. Defaults
to `2`. To make it recurse indefinitely pass `null`.
* `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and
properties will be included in the formatted result. Defaults to `false`.
* `depth` {number} Specifies the number of times to recurse while formatting
the `object`. This is useful for inspecting large complicated objects.
Defaults to `2`. To make it recurse indefinitely pass `null`.
* `colors` {boolean} If `true`, the output will be styled with ANSI color
codes. Defaults to `false`. Colors are customizable, see
[Customizing `util.inspect` colors][].
@ -181,7 +181,7 @@ stream.write('It works!'); // Received data: "It works!"
functions exported on the `object` being inspected will not be called.
Defaults to `true`.
* `showProxy` {boolean} If `true`, then objects and functions that are
`Proxy` objects will be introspected to show their `target` and `hander`
`Proxy` objects will be introspected to show their `target` and `handler`
objects. Defaults to `false`.
* `maxArrayLength` {number} Specifies the maximum number of array and
`TypedArray` elements to include when formatting. Defaults to `100`. Set to
@ -243,7 +243,7 @@ Objects may also define their own `inspect(depth, opts)` function that
```js
const util = require('util');
var obj = { name: 'nate' };
const obj = { name: 'nate' };
obj.inspect = function(depth) {
return `{${this.name}}`;
};
@ -257,7 +257,9 @@ return a value of any type that will be formatted accordingly by
`util.inspect()`.
```js
var obj = { foo: 'this will not show up in the inspect() output' };
const util = require('util');
const obj = { foo: 'this will not show up in the inspect() output' };
obj.inspect = function(depth) {
return { bar: 'baz' };
};
@ -300,11 +302,11 @@ Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.
```js
const util = require('util');
util.isArray([])
util.isArray([]);
// true
util.isArray(new Array)
util.isArray(new Array);
// true
util.isArray({})
util.isArray({});
// false
```
@ -319,11 +321,11 @@ Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`.
```js
const util = require('util');
util.isBoolean(1)
util.isBoolean(1);
// false
util.isBoolean(0)
util.isBoolean(0);
// false
util.isBoolean(false)
util.isBoolean(false);
// true
```
@ -338,11 +340,11 @@ Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`.
```js
const util = require('util');
util.isBuffer({ length: 0 })
util.isBuffer({ length: 0 });
// false
util.isBuffer([])
util.isBuffer([]);
// false
util.isBuffer(Buffer.from('hello world'))
util.isBuffer(Buffer.from('hello world'));
// true
```
@ -357,11 +359,11 @@ Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`.
```js
const util = require('util');
util.isDate(new Date())
util.isDate(new Date());
// true
util.isDate(Date())
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({})
util.isDate({});
// false
```
@ -377,11 +379,11 @@ Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns
```js
const util = require('util');
util.isError(new Error())
util.isError(new Error());
// true
util.isError(new TypeError())
util.isError(new TypeError());
// true
util.isError({ name: 'Error', message: 'an error occurred' })
util.isError({ name: 'Error', message: 'an error occurred' });
// false
```
@ -413,13 +415,13 @@ Returns `true` if the given `object` is a `Function`. Otherwise, returns
const util = require('util');
function Foo() {}
var Bar = function() {};
const Bar = function() {};
util.isFunction({})
util.isFunction({});
// false
util.isFunction(Foo)
util.isFunction(Foo);
// true
util.isFunction(Bar)
util.isFunction(Bar);
// true
```
@ -435,11 +437,11 @@ Returns `true` if the given `object` is strictly `null`. Otherwise, returns
```js
const util = require('util');
util.isNull(0)
util.isNull(0);
// false
util.isNull(undefined)
util.isNull(undefined);
// false
util.isNull(null)
util.isNull(null);
// true
```
@ -455,11 +457,11 @@ returns `false`.
```js
const util = require('util');
util.isNullOrUndefined(0)
util.isNullOrUndefined(0);
// false
util.isNullOrUndefined(undefined)
util.isNullOrUndefined(undefined);
// true
util.isNullOrUndefined(null)
util.isNullOrUndefined(null);
// true
```
@ -474,13 +476,13 @@ Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`.
```js
const util = require('util');
util.isNumber(false)
util.isNumber(false);
// false
util.isNumber(Infinity)
util.isNumber(Infinity);
// true
util.isNumber(0)
util.isNumber(0);
// true
util.isNumber(NaN)
util.isNumber(NaN);
// true
```
@ -496,13 +498,13 @@ Returns `true` if the given `object` is strictly an `Object` __and__ not a
```js
const util = require('util');
util.isObject(5)
util.isObject(5);
// false
util.isObject(null)
util.isObject(null);
// false
util.isObject({})
util.isObject({});
// true
util.isObject(function(){})
util.isObject(function(){});
// false
```
@ -518,23 +520,23 @@ Returns `true` if the given `object` is a primitive type. Otherwise, returns
```js
const util = require('util');
util.isPrimitive(5)
util.isPrimitive(5);
// true
util.isPrimitive('foo')
util.isPrimitive('foo');
// true
util.isPrimitive(false)
util.isPrimitive(false);
// true
util.isPrimitive(null)
util.isPrimitive(null);
// true
util.isPrimitive(undefined)
util.isPrimitive(undefined);
// true
util.isPrimitive({})
util.isPrimitive({});
// false
util.isPrimitive(function() {})
util.isPrimitive(function() {});
// false
util.isPrimitive(/^$/)
util.isPrimitive(/^$/);
// false
util.isPrimitive(new Date())
util.isPrimitive(new Date());
// false
```
@ -549,11 +551,11 @@ Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`.
```js
const util = require('util');
util.isRegExp(/some regexp/)
util.isRegExp(/some regexp/);
// true
util.isRegExp(new RegExp('another regexp'))
util.isRegExp(new RegExp('another regexp'));
// true
util.isRegExp({})
util.isRegExp({});
// false
```
@ -568,13 +570,13 @@ Returns `true` if the given `object` is a `string`. Otherwise, returns `false`.
```js
const util = require('util');
util.isString('')
util.isString('');
// true
util.isString('foo')
util.isString('foo');
// true
util.isString(String('foo'))
util.isString(String('foo'));
// true
util.isString(5)
util.isString(5);
// false
```
@ -589,11 +591,11 @@ Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`.
```js
const util = require('util');
util.isSymbol(5)
util.isSymbol(5);
// false
util.isSymbol('foo')
util.isSymbol('foo');
// false
util.isSymbol(Symbol('foo'))
util.isSymbol(Symbol('foo'));
// true
```
@ -608,12 +610,12 @@ Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`.
```js
const util = require('util');
var foo;
util.isUndefined(5)
const foo = undefined;
util.isUndefined(5);
// false
util.isUndefined(foo)
util.isUndefined(foo);
// true
util.isUndefined(null)
util.isUndefined(null);
// false
```
@ -627,7 +629,7 @@ The `util.log()` method prints the given `string` to `stdout` with an included
timestamp.
```js
const util = require('util')
const util = require('util');
util.log('Timestamped message.');
```

Write Preview
Loading…
Cancel
Save