Skip to content

Commit

Permalink
Add English/Japanese README.
Browse files Browse the repository at this point in the history
  • Loading branch information
@polygonplanet
polygonplanet committed Dec 13, 2014
1 parent 2518876 commit 372e74f
Show file tree
Hide file tree
Showing 2 changed files with 328 additions and 50 deletions.
102 changes: 52 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ encoding.js
[![Build Status](https://travis-ci.org/polygonplanet/encoding.js.svg?branch=master)](https://travis-ci.org/polygonplanet/encoding.js)

Converts character encoding in JavaScript.
JavaScript で文字コード変換をします

**[README(Japanese)](https://github.com/polygonplanet/encoding.js/blob/master/README_ja.md)**

### Installation

Expand All @@ -20,14 +21,13 @@ or
<script src="encoding.min.js"></script>
```

**Encoding** というオブジェクトがグローバルに定義されます

配列に対して変換または判別します
Object **Encoding** will defined in the global scope.

Conversion and detection for the Array (like Array object).

#### In Node.js:

`encoding-japanese` というモジュール名になっています
encoding.js is published by module name of `encoding-japanese` in npm.

```bash
npm install encoding-japanese
Expand All @@ -37,29 +37,30 @@ npm install encoding-japanese
var encoding = require('encoding-japanese');
```

encoding.js の各メソッドは Node.js の Buffer に対しても使えます
Each methods are also available for the *Buffer* in Node.js.

#### 文字コード変換 (convert):
#### Convert character encoding (convert):

* {_Array.<number>_} Encoding.**convert** ( data, to\_encoding [, from\_encoding ] )
文字コードを変換します
@param {_Array.<number>_|_TypedArray_|_Buffer_} _data_ 対象のデータ
@param {_(string|Object)_} _to\_encoding_ 変換先の文字コード
@param {_(string|Array.<string>)=_} [_from\_encoding_] 変換元の文字コード or 'AUTO'
@return {_Array_} 変換した配列が返ります
Converts character encoding.
@param {_Array.<number>_|_TypedArray_|_Buffer_} _data_ Target data.
@param {_(string|Object)_} _to\_encoding_ The encoding name of conversion destination.
@param {_(string|Array.<string>)=_} [_from\_encoding_] The encoding name of source or 'AUTO'.
@return {_Array_} Return the converted array.


```javascript
// UTF-8のデータをShift_JISに変換
// Convert character encoding to Shift_JIS from UTF-8.
var utf8Array = new Uint8Array(...) or [...] or Array(...) or Buffer(...);
var sjisArray = Encoding.convert(utf8Array, 'SJIS', 'UTF8');

// 自動判別で変換 (AUTO detect)
// Convert character encoding by automatic detection (AUTO detect).
var sjisArray = Encoding.convert(utf8Array, 'SJIS');
// or
var sjisArray = Encoding.convert(utf8Array, 'SJIS', 'AUTO');

// 文字コード判別 (戻り値は下の"Available Encodings"のいずれか)
// Detect the character encoding.
// The return value be one of the "Available Encodings" below.
var detected = Encoding.detect(utf8Array);
if (detected === 'UTF8') {
console.log('Encoding is UTF-8');
Expand All @@ -80,11 +81,11 @@ if (detected === 'UTF8') {
* '**SJIS**'
* '**UNICODE**' (JavaScript Unicode Array)

※ UNICODE は JavaScript の String.charCodeAt() の値を持つ配列です
　　(配列の各値は 256 を超える数値になり得ます)
Note: UNICODE is an array that has a value of String.charCodeAt() in JavaScript.
　　(Each value in the array possibly has a number of more than 256.)


##### 引数に Object を指定する
##### Specify the Object argument

```javascript
var sjisArray = Encoding.convert(utf8Array, {
Expand All @@ -93,33 +94,33 @@ var sjisArray = Encoding.convert(utf8Array, {
});
```

第二引数にオブジェクトで渡すことで可読性が上がります
Readability goes up by passing an object to the second argument.

##### UTF16 に BOM をつける
##### Specify BOM in UTF-16

UTF16 に変換する際に bom オプションを指定すると BOM が付加できます
It's can add the UTF16 BOM with specify the bom option on convert.

```javascript
var utf16Array = Encoding.convert(utf8Array, {
to: 'UTF16', // to_encoding
from: 'UTF8', // from_encoding
bom: true // BOMをつける
bom: true // With BOM
});
```

UTF16 のバイトオーダーはデフォルトで big-endian になります
The byte order of UTF16 is big-endian by default.

little-endian として変換したい場合は bom オプションに 'LE' を指定します
Specify the 'LE' in bom options if you want to convert as little-endian.

```javascript
var utf16leArray = Encoding.convert(utf8Array, {
to: 'UTF16', // to_encoding
from: 'UTF8', // from_encoding
bom: 'LE' // BOM (little-endian) をつける
bom: 'LE' // With BOM (little-endian)
});
```

BOM が不要な場合は UTF16LE または UTF16BE を使用します
Convert with specifying the UTF16LE or UTF16BE if BOM is not required.

```javascript
var utf16beArray = Encoding.convert(utf8Array, {
Expand All @@ -128,24 +129,25 @@ var utf16beArray = Encoding.convert(utf8Array, {
});
```

※ UTF16, UTF16BE, UTF16LE は、JavaScript の内部コードではなく各バイトを持つ配列です
Note: UTF16, UTF16BE and UTF16LE is not JavaScript internal encoding, that is an byte array.

#### 文字コード検出 (detect):
#### Detect character encoding (detect):

* {_Array_} Encoding.**detect** ( data [, encodings ] )
文字コードを検出します
@param {_Array.<number>_|_TypedArray_} _data_ 対象のデータ
@param {_(string|Array.<string>)_} [_encodings_] 検出を絞り込む際の文字コード
@return {_string|boolean_} 検出された文字コード、または false が返ります
Detect character encoding.
@param {_Array.<number>_|_TypedArray_} _data_ Target data
@param {_(string|Array.<string>)_} [_encodings_] The encoding name that to specify the detection.
@return {_string|boolean_} Return the detected character encoding, or false.


```javascript
// 自動判別 (AUTO detect)
// Detect character encoding by automatic. (AUTO detect).
var detected = Encoding.detect(utf8Array);
if (detected === 'UTF8') {
console.log('Encoding is UTF-8');
}

// 文字コード指定判別
// Detect character encoding by specific encoding name.
var isSJIS = Encoding.detect(sjisArray, 'SJIS');
if (isSJIS) {
console.log('Encoding is SJIS');
Expand All @@ -156,17 +158,17 @@ if (isSJIS) {
##### URL Encode/Decode:

* {_Array_} Encoding.**urlEncode** ( data )
URL(percent) エンコードします
@param {_Array.<number>_|_TypedArray_} _data_ 対象のデータ
@return {_string_} エンコードされた文字列が返ります
URL(percent) encode.
@param {_Array.<number>_|_TypedArray_} _data_ Target data.
@return {_string_} Return the encoded string.

* {_Array_} Encoding.**urlDecode** ( string )
URL(percent) デコードします
@param {_string_} _string_ 対象の文字列
@return {_Array.<number>_} デコードされた文字コード配列が返ります
URL(percent) decode.
@param {_string_} _string_ Target data.
@return {_Array.<number>_} Return the decoded array.

```javascript
// 文字コードの配列をURLエンコード/デコード
// URL encode to an array that has character code.
var sjisArray = [
130, 177, 130, 241, 130, 201, 130, 191, 130, 205, 129,
65, 130, 217, 130, 176, 129, 153, 130, 210, 130, 230
Expand All @@ -187,9 +189,10 @@ console.log(decoded);

#### Example:

##### XMLHttpRequest と Typed arrays (Uint8Array) を使用した例:
##### Example using the XMLHttpRequest and Typed arrays (Uint8Array):

このサンプルでは Shift_JIS で書かれたテキストファイルをバイナリデータとして読み込み、Encoding.convert によって Unicode に変換して表示します
In this sample, reads the text file written in Shift_JIS as binary data.
And displays string that is converted to Unicode by Encoding.convert.

```javascript
var req = new XMLHttpRequest();
Expand Down Expand Up @@ -217,7 +220,7 @@ req.onload = function (event) {
req.send(null);
```

##### 文字コード変換例:
##### Example of the character encoding conversion:

```javascript
var eucjpArray = [
Expand All @@ -239,7 +242,7 @@ console.log( utf8Array );
// => 'こんにちは、ほげ☆ぴよ'
```

##### 文字コード自動検出での変換例 (Auto detect):
##### Example of convert a character code by automatic detection (Auto detect):

```javascript
var sjisArray = [
Expand All @@ -250,27 +253,26 @@ var unicodeArray = Encoding.convert(sjisArray, {
to: 'UNICODE',
from: 'AUTO'
});
// codeToStringは文字コード配列を文字列に変換(連結)して返します
// codeToString is a utility method that Joins a character code array to string.
console.log( Encoding.codeToString(unicodeArray) );
// output: 'こんにちは、ほげ☆ぴよ'
```

### Utilities

* {_string_} Encoding.**codeToString** ( {_Array.<number>_|_TypedArray_} data )
文字コード配列を文字列に変換(連結)して返します
Joins a character code array to string.

* {_Array.<number>_} Encoding.**stringToCode** ( {_string_} string )
文字列を文字コード配列に分割して返します
Splits string to an array of character codes.


### Demo

[文字コード変換テスト(Demo)](http://polygonplanet.github.io/encoding.js/tests/encoding-test.html)
[Test for character encoding conversion (Demo)](http://polygonplanet.github.io/encoding.js/tests/encoding-test.html)

### License

MIT



Loading

0 comments on commit 372e74f

Please sign in to comment.