Node.js v0.10.18 手册 & 文档

utils#

稳定度: 4 - 冻结

These functions are in the module 'util'. Use require('util') to access them.

如果你想使用模块 'util'中已定义的方法. 只需 require('util') 即可使用.

The util module is primarily designed to support the needs of Node's internal APIs. Many of these utilities are useful for your own programs. If you find that these functions are lacking for your purposes, however, you are encouraged to write your own utilities. We are not interested in any future additions to the util module that are unnecessary for Node's internal functionality.

util模块设计的主要目的是为了满足Node内部API的需求。这个模块中的很多方法在你编写Node程序的时候都是很有帮助的。如果你觉得提供的这些方法满足不了你的需求，那么我们鼓励你编写自己的实用工具方法。我们不希望util模块中添加任何对于Node的内部功能非必要的扩展。

util.debuglog(section)#

section String The section of the program to be debugged
Returns: Function The logging function
section String 被调试的程序节点部分
返回值: Function 日志处理函数

This is used to create a function which conditionally writes to stderr based on the existence of a NODE_DEBUG environment variable. If the section name appears in that environment variable, then the returned function will be similar to console.error(). If not, then the returned function is a no-op.

这个方法是在存在NODE_DEBUG环境变量的基础上，创建一个有条件写到stderr里的函数。如果“节点”的名字出现在这个环境变量里,那么就返回一个功能类似于console.error()的函数.如果不是,那么返回一个空函数.

For example:

例如：

var bar = 123; debuglog('hello from foo [%d]', bar); ```

If this program is run with NODE_DEBUG=foo in the environment, then it will output something like:

如果这个程序以NODE_DEBUG=foo 的环境运行，那么它将会输出：

FOO 3245: hello from foo [123]

where 3245 is the process id. If it is not run with that environment variable set, then it will not print anything.

3245是进程的ID, 如果程序不以刚才那样设置的环境变量运行，那么将不会输出任何东西。

You may separate multiple NODE_DEBUG environment variables with a comma. For example, NODE_DEBUG=fs,net,tls.

多个NODE_DEBUG环境变量,你可以用逗号进行分割。例如，NODE_DEBUG= fs, net, tls。

util.format(format, [...])#

Returns a formatted string using the first argument as a printf-like format.

根据第一个参数，返回一个格式化字符串，类似printf的格式化输出。

The first argument is a string that contains zero or more placeholders. Each placeholder is replaced with the converted value from its corresponding argument. Supported placeholders are:

第一个参数是一个字符串，包含零个或多个占位符。每一个占位符被替换为与其对应的转换后的值。支持的占位符有:

%s - String.
%d - Number (both integer and float).
%j - JSON. Replaced with the string '[Circular]' if the argument
```
   contains circular references.
```
%% - single percent sign ('%'). This does not consume an argument.
%s - 字符串.
%d - 数字 (整型和浮点型).
%j - JSON. 如果这个参数包含循环对象的引用，将会被替换成字符串 '[Circular]'。
%% - 单独一个百分号('%')。不会消耗一个参数。

If the placeholder does not have a corresponding argument, the placeholder is not replaced.

如果占位符没有相对应的参数，占位符将不会被替换。

util.format('%s:%s', 'foo'); // 'foo:%s'

If there are more arguments than placeholders, the extra arguments are converted to strings with util.inspect() and these strings are concatenated, delimited by a space.

如果有多个参数占位符，额外的参数将会调用util.inspect()转换为字符串。这些字符串被连接在一起，并且以空格分隔。

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

If the first argument is not a format string then util.format() returns a string that is the concatenation of all its arguments separated by spaces. Each argument is converted to a string with util.inspect().

如果第一个参数是一个非格式化字符串，那么util.format()将会把所有的参数转成字符串，以空格隔开，拼接在一块，并返回该字符串。util.inspect()会把每个参数都转成一个字符串。

util.format(1, 2, 3); // '1 2 3'

util.log(string)#

Output with timestamp on stdout.

在控制台进行输出，并带有时间戳。

示例：require('util').log('Timestamped message.');

util.inspect(object, [options])#

Return a string representation of object, which is useful for debugging.

返回一个对象的字符串表现形式, 在代码调试的时候非常有用.

An optional options object may be passed that alters certain aspects of the formatted string:

可以通过加入一些可选选项，来改变对象的格式化输出形式：

showHidden - if true then the object's non-enumerable properties will be shown too. Defaults to false.
showHidden - 如果设为 true，那么该对象的不可枚举的属性将会被显示出来。默认为false.
depth - tells inspect 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.
depth - 告诉 inspect 格式化对象的时候递归多少次。这个选项在格式化复杂对象的时候比较有用。默认为 2。如果想无穷递归下去，则赋值为null即可。
colors - if true, then the output will be styled with ANSI color codes. Defaults to false. Colors are customizable, see below.
colors - 如果设为true，将会以ANSI颜色代码风格进行输出. 默认是false。颜色是可定制的，请看下面：
customInspect - if false, then custom inspect(depth, opts) functions defined on the objects being inspected won't be called. Defaults to true.
customInspect - 如果设为 false，那么定义在被检查对象上的inspect(depth, opts) 方法将不会被调用。默认为true。

Example of inspecting all properties of the util object:

示例：检查util对象上的所有属性

console.log(util.inspect(util, { showHidden: true, depth: null }));

Values may supply their own custom inspect(depth, opts) functions, when called they receive the current depth in the recursive inspection, as well as the options object passed to util.inspect().

当被调用的时候，参数值可以提供自己的自定义inspect(depth, opts)方法。该方法会接收当前的递归检查深度，以及传入util.inspect()的其他参数。

自定义 `util.inspect` 颜色#

Color output (if enabled) of util.inspect is customizable globally via util.inspect.styles and util.inspect.colors objects.

util.inspect彩色输出(如果启用的话) ，可以通过util.inspect.styles 和 util.inspect.colors 来全局定义。

util.inspect.styles is a map assigning each style a color from util.inspect.colors. Highlighted styles and their default values are: number (yellow) boolean (yellow) string (green) date (magenta) regexp (red) null (bold) undefined (grey) special - only function at this time (cyan) * name (intentionally no styling)

util.inspect.styles是通过util.inspect.colors分配给每个风格颜色的一个映射。高亮风格和它们的默认值: number (黄色) boolean (黄色) string (绿色) date (洋红色) regexp (红色) null (粗体) undefined (灰色) special - 在这个时候的唯一方法 (青绿色) * name (无风格)

Predefined color codes are: white, grey, black, blue, cyan, green, magenta, red and yellow. There are also bold, italic, underline and inverse codes.

预定义的颜色代码: white, grey, black, blue, cyan, green, magenta, red 和 yellow。还有 bold, italic, underline 和 inverse 代码。

自定义对象的`inspect()`方法#

Objects also may define their own inspect(depth) function which util.inspect() will invoke and use the result of when inspecting the object:

对象可以定义自己的 inspect(depth)方法；当使用util.inspect()检查该对象的时候，将会执行对象自定义的检查方法。

util.inspect(obj);
  // "{nate}"

You may also return another Object entirely, and the returned String will be formatted according to the returned Object. This is similar to how JSON.stringify() works:

您也可以返回完全不同的另一个对象，而且返回的字符串将被根据返回的对象格式化。它和JSON.stringify()工作原理类似:

util.inspect(obj);
  // "{ bar: 'baz' }"

util.isArray(object)#

Returns true if the given "object" is an Array. false otherwise.

如果给定的对象是数组类型，就返回true，否则返回false

util.isArray([])
  // true
util.isArray(new Array)
  // true
util.isArray({})
  // false

util.isRegExp(object)#

Returns true if the given "object" is a RegExp. false otherwise.

如果给定的对象是RegExp类型，就返回true，否则返回false。

util.isRegExp(/some regexp/)
  // true
util.isRegExp(new RegExp('another regexp'))
  // true
util.isRegExp({})
  // false

util.isDate(object)#

Returns true if the given "object" is a Date. false otherwise.

如果给定的对象是Date类型，就返回true，否则返回false。

util.isDate(new Date())
  // true
util.isDate(Date())
  // false (没有关键字 'new' 返回一个字符串)
util.isDate({})
  // false

util.isError(object)#

Returns true if the given "object" is an Error. false otherwise.

如果给定的对象是Error类型，就返回true，否则返回false。

util.isError(new Error())
  // true
util.isError(new TypeError())
  // true
util.isError({ name: 'Error', message: 'an error occurred' })
  // false

util.inherits(constructor, superConstructor)#

Inherit the prototype methods from one constructor into another. The prototype of constructor will be set to a new object created from superConstructor.

通过构造函数，继承原型对象上的方法。构造函数的原型将被设置为一个新的从超类创建的对象。

As an additional convenience, superConstructor will be accessible through the constructor.super_ property.

你可以很方便的通过 constructor.super_来访问到superConstructor

stream.on("data", function(data) {
    console.log('Received data: "' + data + '"');
})
stream.write("It works!"); // 输出结果：Received data: "It works!"

util.debug(string)#

稳定度: 0 - 已过时: 请使用 console.error() 代替

Deprecated predecessor of console.error.

console.error的已过时的前身

util.error([...])#

稳定度: 0 - 已过时: 请使用 console.error() 代替

Deprecated predecessor of console.error.

console.error的已过时的前身

util.puts([...])#

稳定度: 0 - 已过时: 请使用 console.log() 代替

Deprecated predecessor of console.log.

console.log的已过时的前身

util.print([...])#