The iconv-lite
module supports more encodings than this module (singlebyte
).
Consider using iconv-lite
instead of this module.
A single-byte encoding means that each byte corresponds to a character.
Node's Buffer
supports 'ascii'
and 'binary'
, but sometimes you need more single-byte encodings.
This module (singlebyte
) provides such support for several known encodings (see below).
This module can also be used to define more single-byte encodings.
Node.js v0.10 (or newer) is required.
-
Latest packaged version:
npm install singlebyte
-
Latest githubbed version:
npm install https://github.com/Mithgol/node-singlebyte/tarball/master
You may visit https://github.com/Mithgol/node-singlebyte#readme occasionally to read the latest README
because the package's version is not planned to grow after changes when they happen in README
only. (And npm publish --force
is forbidden nowadays.)
Require the installed module:
var sb = require('singlebyte');
You get an object that has the following methods:
Returns true
if the given encoding is known to the module, false
otherwise.
Works almost like Node.js Buffer's isEncoding
.
-
Node.js Buffer's encodings are known.
-
Additionally, the following encodings are defined in the module:
'cp437'
for code page 437'cp808'
for code page 808'cp850'
for code page 850'cp858'
for code page 858'cp866'
for code page 866'cp1125'
for code page 1125'cp1252'
for code page Windows-1252'koi8-r'
for KOI8-R'koi8-u'
for KOI8-U'koi8-ru'
for KOI8-RU'latin-1'
for ISO/IEC 8859-1:1998
-
More encodings can be defined using
learnEncoding
method (see below).
Defines an encoding.
Expects encodingName
to be a string and encodingTable
to be an array of exactly 256 elements.
A single-byte encoding means that each byte corresponds to a character. The value of a byte is always in the 0…255
range, and encodingTable[i]
defines the character that corresponds to the i
value of that byte.
Each value of the encodingTable
array is a number (a Unicode code of the corresponding character). If that code is outside of the 0…0x10FFFF
range, an error is thrown.
The encodings defined in Node.js Buffer cannot be redefined. (When such an attempt is made, an error is thrown.)
Returns an array of 256 elements previously given as encodingTable
for the encoding.
If an encoding was never defined with learnEncoding
, returns null
.
Note: for the encodings defined in Node.js Buffer, isEncoding
returns true
but getEncodingTable
returns null
.
Returns an array containing an encoding table of an extended ASCII encoding.
The first 128 codes (0…127) are numbers from 0 through 127.
The next 128 codes (128…255) are taken from extensionTable
(that must have exactly 128 elements).
Then you may feed the returned array to learnEncoding
as its second (encodingTable
) parameter.
For example, that's how 'cp866'
encoding is defined in the module's constructor:
this.learnEncoding('cp866', this.extendASCII([
0x410, 0x411, 0x412, 0x413, 0x414, 0x415, 0x416, 0x417,
0x418, 0x419, 0x41A, 0x41B, 0x41C, 0x41D, 0x41E, 0x41F,
0x420, 0x421, 0x422, 0x423, 0x424, 0x425, 0x426, 0x427,
0x428, 0x429, 0x42A, 0x42B, 0x42C, 0x42D, 0x42E, 0x42F,
0x430, 0x431, 0x432, 0x433, 0x434, 0x435, 0x436, 0x437,
0x438, 0x439, 0x43A, 0x43B, 0x43C, 0x43D, 0x43E, 0x43F,
0x2591, 0x2592, 0x2593, 0x2502, 0x2524, 0x2561, 0x2562, 0x2556,
0x2555, 0x2563, 0x2551, 0x2557, 0x255D, 0x255C, 0x255B, 0x2510,
0x2514, 0x2534, 0x252C, 0x251C, 0x2500, 0x253C, 0x255E, 0x255F,
0x255A, 0x2554, 0x2569, 0x2566, 0x2560, 0x2550, 0x256C, 0x2567,
0x2568, 0x2564, 0x2565, 0x2559, 0x2558, 0x2552, 0x2553, 0x256B,
0x256A, 0x2518, 0x250C, 0x2588, 0x2584, 0x258C, 0x2590, 0x2580,
0x440, 0x441, 0x442, 0x443, 0x444, 0x445, 0x446, 0x447,
0x448, 0x449, 0x44A, 0x44B, 0x44C, 0x44D, 0x44E, 0x44F,
0x401, 0x451, 0x404, 0x454, 0x407, 0x457, 0x40E, 0x45E,
0xB0, 0x2219, 0xB7, 0x221A, 0x2116, 0xA4, 0x25A0, 0xA0
]));
Works almost like Node's buf.toString
, converting a Buffer to a string.
Takes the following parameters:
-
buf
is a source Buffer. -
encoding
is either a Node's Buffer encoding or a previously defined single-byte encoding. -
start
(optional, defaults to0
) andend
(optional, defaults tobuf.length
) define the starting byte and the ending byte of the source byte sequence in the given Buffer. Theend
th byte is not included; for example,start == 0
andend == 1
means that only one (0th) byte is decoded.
If a Node.js Buffer's encoding is given, buf.toString
is called and its result is returned.
Otherwise, a string is built of Unicode characters (the codes of these characters are found for each single byte of the source according to the encoding table for the given encoding
) and returned.
Note: if the encoding table contains a value in the 0x10000…0x10FFFF
range, the Unicode character for such a byte corresponds to a UTF-16 surrogate pair and thus becomes two “characters” in the returned JavaScript string. (In JavaScript the “characters” of a string are actually UTF-16 hexadecets.)
Works almost like Node's new Buffer(str, encoding)
, converting a string to a Buffer.
Takes the following parameters:
-
str
is a source string. -
encoding
is either a Node's Buffer encoding or a previously defined single-byte encoding. -
encodingOptions
(optional) is an object.encodingOptions.defaultCode
contains an integer code that is used for characters ofstr
that are not present in the encoding table. Defaults to0x3F
(ASCII code of a question mark,'?'
).
If a Node.js Buffer's encoding is given, new Buffer(str, encoding)
is called and its result is returned.
Otherwise, characters are taken sequentially from str
and a Buffer is built of (single byte) character codes found in the encoding table. (When the table does not contain a byte value corresponding to the Unicode of some character, encodingOptions.defaultCode
is used.) That Buffer is returned.
If an error is encountered, the module throws new Error('…')
with one of the predefined strings (error descriptions). You may see these strings in the bottom of singlebyte.js
.
It is necessary to install Mocha and JSHint for testing.
-
You may install Mocha globally (
npm install mocha -g
) or locally (npm install mocha
in the directory ofsinglebyte
). -
You may install JSHint globally (
npm install jshint -g
) or locally (npm install jshint
in the directory ofsinglebyte
).
After that you may run npm test
(in the directory of singlebyte
) for testing.
MIT License, see the LICENSE
file.