node/doc/api/util.markdown

util

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

util.format()

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

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.
• %% - single percent sign ('%'). This does not consume an argument.

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.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(1, 2, 3); // '1 2 3'

util.debug(string)

A synchronous output function. Will block the process and output string immediately to stderr.

require('util').debug('message on stderr');

util.log(string)

Output with timestamp on stdout.

require('util').log('Timestamped message.');

util.inspect(object, showHidden=false, depth=2)

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

If showHidden is true, then the object's non-enumerable properties will be shown too.

If depth is provided, it tells inspect how many times to recurse while formatting the object. This is useful for inspecting large complicated objects.

The default is to only recurse twice. To make it recurse indefinitely, pass in null for depth.

Example of inspecting all properties of the util object:

var util = require('util');

console.log(util.inspect(util, true, null));

util.pump(readableStream, writableStream, [callback])

Experimental

Read the data from readableStream and send it to the writableStream. When writableStream.write(data) returns false readableStream will be paused until the drain event occurs on the writableStream. callback gets an error as its only argument and is called when writableStream is closed or when an error occurs.

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.

var util = require("util");
var events = require("events");

function MyStream() {
    events.EventEmitter.call(this);
}

util.inherits(MyStream, events.EventEmitter);

MyStream.prototype.write = function(data) {
    this.emit("data", data);
}

var stream = new MyStream();

console.log(stream instanceof events.EventEmitter); // true
console.log(MyStream.super_ === events.EventEmitter); // true

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