1 | ## iconv-lite: Pure JS character encoding conversion
|
2 |
|
3 | * No need for native code compilation. Quick to install, works on Windows and in sandboxed environments like [Cloud9](http://c9.io).
|
4 | * Used in popular projects like [Express.js (body_parser)](https://github.com/expressjs/body-parser),
|
5 | [Grunt](http://gruntjs.com/), [Nodemailer](http://www.nodemailer.com/), [Yeoman](http://yeoman.io/) and others.
|
6 | * Faster than [node-iconv](https://github.com/bnoordhuis/node-iconv) (see below for performance comparison).
|
7 | * Intuitive encode/decode API, including Streaming support.
|
8 | * In-browser usage via [browserify](https://github.com/substack/node-browserify) or [webpack](https://webpack.js.org/) (~180kb gzip compressed with Buffer shim included).
|
9 | * Typescript [type definition file](https://github.com/ashtuchkin/iconv-lite/blob/master/lib/index.d.ts) included.
|
10 | * React Native is supported (need to install `stream` module to enable Streaming API).
|
11 | * License: MIT.
|
12 |
|
13 | [![NPM Stats](https://nodei.co/npm/iconv-lite.png)](https://npmjs.org/package/iconv-lite/)
|
14 | [![Build Status](https://travis-ci.org/ashtuchkin/iconv-lite.svg?branch=master)](https://travis-ci.org/ashtuchkin/iconv-lite)
|
15 | [![npm](https://img.shields.io/npm/v/iconv-lite.svg)](https://npmjs.org/package/iconv-lite/)
|
16 | [![npm downloads](https://img.shields.io/npm/dm/iconv-lite.svg)](https://npmjs.org/package/iconv-lite/)
|
17 | [![npm bundle size](https://img.shields.io/bundlephobia/min/iconv-lite.svg)](https://npmjs.org/package/iconv-lite/)
|
18 |
|
19 | ## Usage
|
20 | ### Basic API
|
21 | ```javascript
|
22 | var iconv = require('iconv-lite');
|
23 |
|
24 | // Convert from an encoded buffer to a js string.
|
25 | str = iconv.decode(Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f]), 'win1251');
|
26 |
|
27 | // Convert from a js string to an encoded buffer.
|
28 | buf = iconv.encode("Sample input string", 'win1251');
|
29 |
|
30 | // Check if encoding is supported
|
31 | iconv.encodingExists("us-ascii")
|
32 | ```
|
33 |
|
34 | ### Streaming API
|
35 | ```javascript
|
36 |
|
37 | // Decode stream (from binary data stream to js strings)
|
38 | http.createServer(function(req, res) {
|
39 | var converterStream = iconv.decodeStream('win1251');
|
40 | req.pipe(converterStream);
|
41 |
|
42 | converterStream.on('data', function(str) {
|
43 | console.log(str); // Do something with decoded strings, chunk-by-chunk.
|
44 | });
|
45 | });
|
46 |
|
47 | // Convert encoding streaming example
|
48 | fs.createReadStream('file-in-win1251.txt')
|
49 | .pipe(iconv.decodeStream('win1251'))
|
50 | .pipe(iconv.encodeStream('ucs2'))
|
51 | .pipe(fs.createWriteStream('file-in-ucs2.txt'));
|
52 |
|
53 | // Sugar: all encode/decode streams have .collect(cb) method to accumulate data.
|
54 | http.createServer(function(req, res) {
|
55 | req.pipe(iconv.decodeStream('win1251')).collect(function(err, body) {
|
56 | assert(typeof body == 'string');
|
57 | console.log(body); // full request body string
|
58 | });
|
59 | });
|
60 | ```
|
61 |
|
62 | ## Supported encodings
|
63 |
|
64 | * All node.js native encodings: utf8, ucs2 / utf16-le, ascii, binary, base64, hex.
|
65 | * Additional unicode encodings: utf16, utf16-be, utf-7, utf-7-imap, utf32, utf32-le, and utf32-be.
|
66 | * All widespread singlebyte encodings: Windows 125x family, ISO-8859 family,
|
67 | IBM/DOS codepages, Macintosh family, KOI8 family, all others supported by iconv library.
|
68 | Aliases like 'latin1', 'us-ascii' also supported.
|
69 | * All widespread multibyte encodings: CP932, CP936, CP949, CP950, GB2312, GBK, GB18030, Big5, Shift_JIS, EUC-JP.
|
70 |
|
71 | See [all supported encodings on wiki](https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings).
|
72 |
|
73 | Most singlebyte encodings are generated automatically from [node-iconv](https://github.com/bnoordhuis/node-iconv). Thank you Ben Noordhuis and libiconv authors!
|
74 |
|
75 | Multibyte encodings are generated from [Unicode.org mappings](http://www.unicode.org/Public/MAPPINGS/) and [WHATWG Encoding Standard mappings](http://encoding.spec.whatwg.org/). Thank you, respective authors!
|
76 |
|
77 |
|
78 | ## Encoding/decoding speed
|
79 |
|
80 | Comparison with node-iconv module (1000x256kb, on MacBook Pro, Core i5/2.6 GHz, Node v0.12.0).
|
81 | Note: your results may vary, so please always check on your hardware.
|
82 |
|
83 | operation iconv@2.1.4 iconv-lite@0.4.7
|
84 | ----------------------------------------------------------
|
85 | encode('win1251') ~96 Mb/s ~320 Mb/s
|
86 | decode('win1251') ~95 Mb/s ~246 Mb/s
|
87 |
|
88 | ## BOM handling
|
89 |
|
90 | * Decoding: BOM is stripped by default, unless overridden by passing `stripBOM: false` in options
|
91 | (f.ex. `iconv.decode(buf, enc, {stripBOM: false})`).
|
92 | A callback might also be given as a `stripBOM` parameter - it'll be called if BOM character was actually found.
|
93 | * If you want to detect UTF-8 BOM when decoding other encodings, use [node-autodetect-decoder-stream](https://github.com/danielgindi/node-autodetect-decoder-stream) module.
|
94 | * Encoding: No BOM added, unless overridden by `addBOM: true` option.
|
95 |
|
96 | ## UTF-16 Encodings
|
97 |
|
98 | This library supports UTF-16LE, UTF-16BE and UTF-16 encodings. First two are straightforward, but UTF-16 is trying to be
|
99 | smart about endianness in the following ways:
|
100 | * Decoding: uses BOM and 'spaces heuristic' to determine input endianness. Default is UTF-16LE, but can be
|
101 | overridden with `defaultEncoding: 'utf-16be'` option. Strips BOM unless `stripBOM: false`.
|
102 | * Encoding: uses UTF-16LE and writes BOM by default. Use `addBOM: false` to override.
|
103 |
|
104 | ## UTF-32 Encodings
|
105 |
|
106 | This library supports UTF-32LE, UTF-32BE and UTF-32 encodings. Like the UTF-16 encoding above, UTF-32 defaults to UTF-32LE, but uses BOM and 'spaces heuristics' to determine input endianness.
|
107 | * The default of UTF-32LE can be overridden with the `defaultEncoding: 'utf-32be'` option. Strips BOM unless `stripBOM: false`.
|
108 | * Encoding: uses UTF-32LE and writes BOM by default. Use `addBOM: false` to override. (`defaultEncoding: 'utf-32be'` can also be used here to change encoding.)
|
109 |
|
110 | ## Other notes
|
111 |
|
112 | When decoding, be sure to supply a Buffer to decode() method, otherwise [bad things usually happen](https://github.com/ashtuchkin/iconv-lite/wiki/Use-Buffers-when-decoding).
|
113 | Untranslatable characters are set to � or ?. No transliteration is currently supported.
|
114 | Node versions 0.10.31 and 0.11.13 are buggy, don't use them (see #65, #77).
|
115 |
|
116 | ## Testing
|
117 |
|
118 | ```bash
|
119 | $ git clone git@github.com:ashtuchkin/iconv-lite.git
|
120 | $ cd iconv-lite
|
121 | $ npm install
|
122 | $ npm test
|
123 |
|
124 | $ # To view performance:
|
125 | $ node test/performance.js
|
126 |
|
127 | $ # To view test coverage:
|
128 | $ npm run coverage
|
129 | $ open coverage/lcov-report/index.html
|
130 | ```
|