Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

Fix #3242 Actually deprecate 'binary' buffer encoding

  • Loading branch information...
isaacs committed May 9, 2012
1 parent e859271 commit 5979f096d1b702ca2ba95664a0bbc8210109775b
Showing with 30 additions and 12 deletions.
  1. +6 −5 doc/api/buffer.markdown
  2. +15 −0 lib/buffer.js
  3. +9 −7 src/node.cc
@@ -33,13 +33,14 @@ encoding method. Here are the different string encodings.

* `'base64'` - Base64 string encoding.

* `'binary'` - A way of encoding raw binary data into strings by using only
the first 8 bits of each character. This encoding method is deprecated and
should be avoided in favor of `Buffer` objects where possible. This encoding
will be removed in future versions of Node.

* `'hex'` - Encode each byte as two hexadecimal characters.

If you need direct access to the bytes, then the best way is to use a
Buffer object directly, rather than any string encoding. In the past,
there were options for `'binary'`, `'raw'`, and others, but these all
involve unnecessary copying. Just use Buffers directly if you need
access to the actual bytes.

## Class: Buffer

The Buffer class is a global type for dealing with binary data directly.
@@ -22,6 +22,15 @@
var SlowBuffer = process.binding('buffer').SlowBuffer;
var assert = require('assert');

// Deprecate the 'binary' encoding.
// TODO: Remove it entirely in v0.9.
var binaryWarned = false;
function binaryWarn() {
if (binaryWarned) return;
binaryWarned = true;
console.error('The binary buffer encoding is deprecated.');
}

exports.INSPECT_MAX_BYTES = 50;


@@ -82,6 +91,7 @@ SlowBuffer.prototype.toString = function(encoding, start, end) {
return this.asciiSlice(start, end);

case 'binary':
binaryWarn();
return this.binarySlice(start, end);

case 'base64':
@@ -168,6 +178,7 @@ SlowBuffer.prototype.write = function(string, offset, length, encoding) {
return this.asciiWrite(string, offset, length);

case 'binary':
binaryWarn();
return this.binaryWrite(string, offset, length);

case 'base64':
@@ -368,6 +379,7 @@ Buffer.prototype.write = function(string, offset, length, encoding) {
break;

case 'binary':
binaryWarn();
ret = this.parent.binaryWrite(string, this.offset + offset, length);
break;

@@ -424,6 +436,7 @@ Buffer.prototype.toString = function(encoding, start, end) {
return this.parent.asciiSlice(start, end);

case 'binary':
binaryWarn();
return this.parent.binarySlice(start, end);

case 'base64':
@@ -536,6 +549,7 @@ Buffer.prototype.utf8Slice = function(start, end) {
};

Buffer.prototype.binarySlice = function(start, end) {
binaryWarn();
return this.toString('binary', start, end);
};

@@ -548,6 +562,7 @@ Buffer.prototype.utf8Write = function(string, offset) {
};

Buffer.prototype.binaryWrite = function(string, offset) {
binaryWarn();
return this.write(string, offset, 'binary');
};

@@ -1104,16 +1104,18 @@ enum encoding ParseEncoding(Handle<Value> encoding_v, enum encoding _default) {
} else if (strcasecmp(*encoding, "ucs-2") == 0) {
return UCS2;
} else if (strcasecmp(*encoding, "binary") == 0) {
fprintf(stderr, "The 'binary' buffer encoding is deprecated. "
"Use a Buffer object directly.\n");
return BINARY;
} else if (strcasecmp(*encoding, "hex") == 0) {
return HEX;
} else if (strcasecmp(*encoding, "raw") == 0) {
fprintf(stderr, "'raw' (array of integers) has been removed. "
"Use 'binary'.\n");
"Use a Buffer object directly.\n");
return BINARY;
} else if (strcasecmp(*encoding, "raws") == 0) {
fprintf(stderr, "'raws' encoding has been renamed to 'binary'. "
"Please update your code.\n");
fprintf(stderr, "'raws' (array of integers) has been removed. "
"Use a Buffer object directly.\n");
return BINARY;
} else {
return _default;
@@ -1147,8 +1149,8 @@ ssize_t DecodeBytes(v8::Handle<v8::Value> val, enum encoding encoding) {
HandleScope scope;

if (val->IsArray()) {
fprintf(stderr, "'raw' encoding (array of integers) has been removed. "
"Use 'binary'.\n");
fprintf(stderr, "'raw' (array of integers) has been removed. "
"Use a Buffer object directly.\n");
assert(0);
return -1;
}
@@ -1184,8 +1186,8 @@ ssize_t DecodeWrite(char *buf,
// http://groups.google.com/group/v8-users/browse_thread/thread/1f83b0ba1f0a611

if (val->IsArray()) {
fprintf(stderr, "'raw' encoding (array of integers) has been removed. "
"Use 'binary'.\n");
fprintf(stderr, "'raw' (array of integers) has been removed. "
"Use a Buffer object directly.\n");
assert(0);
return -1;
}

4 comments on commit 5979f09

@mscdex

This comment has been minimized.

Copy link

replied May 9, 2012

As much as I am for using Buffers, the nice thing about the 'binary' strings is that you have all of the useful (built-in) string methods available, such as indexOf, split, match, etc. Is it possible to see some of these methods implemented for Buffer in core or no?

@gmxyb

This comment has been minimized.

Copy link

replied May 10, 2012

Agree above.

I hope have a "Powerful Buffer" like String.

@Mithgol

This comment has been minimized.

Copy link

replied May 10, 2012

I feel compelled to add that you may compare binary strings with operators (< and >, >= and <=), and with Buffer instances you don't even have methods for that.

As well as methods for concat (strings also have an operator for that: +), indexOf, lastIndexOf, match (with regular expressions), replace (with regular expressions), search (with regular expressions), split (with regular expressions).

@Mithgol

This comment has been minimized.

Copy link

replied May 10, 2012

I am opening #3246 to express these counter-arguments.

Please sign in to comment.
You can’t perform that action at this time.