D 2.0
About Japanese Translation

www.digitalmars.com
Last update Thu Aug 7 22:02:32 2008

std.encoding

さまざまな文字コード (※訳注: 以下では "encoding" を "文字コード" と訳しました) やその間の変換を扱うクラスと関数です。

コンパイル時に文字コードがわかっている場合用に、 文字の任意のエンコードやデコード、 別の型の文字列間の変換、バリデーションやサニタイズの関数が提供されています。

現在サポートされている文字コードは UTF-8, UTF-16, UTF-32, ASCII, ISO-8859-1 (別名 LATIN-1), WINDOWS-1252 です。 型 AsciiChar は ASCII 文字を表します。 型 AsciiString は ASCII 文字を表します。 型 Latin1Char は ISO-8859-1 文字を表します。 型 Latin1String は ISO-8859-1 文字を表します。 型 Windows1252Char は Windows-1252 文字を表します。 型 Windows1252String は Windows-1252 文字を表します。

コンパイル時に文字コードが決まらない場合用には、 抽象クラス EncodingScheme とその派生クラスを提供しています。 実行時にエンコーダ/デコーダを構築するには、次のようにします。 

    auto e = EncodingScheme.create("utf-8");
ライブラリの提供する EncodingScheme の派生クラスは ASCII, ISO-8859-1 (別名 LATIN-1), WINDOWS-1252, UTF-8, (リトルエンディアン環境では) UTF-16LE と UTF-32LE (ビッグエンディアン環境では) UTF-16BE と UTF-32BE に対応するものです。

このライブラリは、別の文字コードに対応する EncodingScheme を他のモジュールから追加するメカニズムを提供しています。

Authors:
Janice Caron

Date:
2008.02.27 - 2008.05.07

License:
Public Domain



dchar INVALID_SEQUENCE;
safeDecode の返す特殊な値

typedef AsciiChar;


alias AsciiString;


typedef Latin1Char;


alias Latin1String;


typedef Windows1252Char;


alias Windows1252String;


bool isValidCodePoint(dchar c);
c が有効なコードポイントなら true を返します

これには、文字を表さないコードポイント U+FFFE と U+FFFF も、 (有効な文字ではないにしろ) 有効なコードポイントなので 含まれることに注意してください。

Supercedes:
std.utf.startsValidDchar() の上位版です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
dchar c テストするコードポイント

string encodingName(T)();
文字コードの名前を返します。

文字コードの型を推論することはできません。 文字コード型は明示的に指定する必要があります。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Examples:
 writefln(encodingName!(Latin1Char));
     // ISO-8859-1 を出力


bool canEncode(E)(dchar c);
指定されたコードポイントをその文字コードで表現できるときにのみ、 true を返します。

文字コードの型を推論することはできません。 文字コード型は明示的に指定する必要があります。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Examples:
 writefln(canEncode!(Latin1Char)('A'));
     // true を出力


bool isValidCodeUnit(E)(E c);
コード単位が正当なものであれば true を返します。例えば、バイト 0x80 は ASCII では不正です。なぜなら、ASCII のコード単位は 0x00 から 0x7F の範囲でなければならないからです。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c テストするコード単位

bool isValid(E)(const(E)[] s);
文字列が正しくエンコードされていれば true を返します。

Supercedes:
この関数は std.utf.validate() の上位版ですが、こちらは 入力が正当か不正かを示す真偽値を返すのに対して、 旧関数は例外を投げていたことに注意してください。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s テストする文字列

uint validLength(E)(const(E)[] s);
最初のコードから始めてできるだけ長い正しくエンコードされた部分文字列の 長さを返します。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s テストする文字列

invariant(E)[] sanitize(E)(invariant(E)[] s);
不正なコード単位を有効なコード単位に置き換えることで文字列をサニタイズします。 結果は指定の文字コードにおいて正しい文字列となることが保証されています。

入力文字列がすでに正当なものならば元の文字列をそのまま返し、 そうでなければ全ての不正なコード単位を その文字コードの置き換え文字に替えた新しい文字列を作って返します。 不正な部分は、Unicode の置き換え文字 (U+FFFD) に対応する文字が あればそれで、なければ '?' で 置き換えられます。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s サニタイズする文字列

uint firstSequence(E)(const(E)[] s);
先頭の文字に対応するエンコードされたシーケンスの長さを返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s スライスする文字列

uint lastSequence(E)(const(E)[] s);
末尾の文字に対応するエンコードされたシーケンスの長さを返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s スライスする文字列

uint count(E)(const(E)[] s);
文字列中にエンコードされたコードポイントの総数を返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Supercedes:
この関数は std.utf.toUCSindex() の上位版です

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s カウント対象の文字列

int index(E)(const(E)[] s, int n);
n+1 番目のコードポイントが始まる配列のインデックスを返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Supercedes:
この関数は supercedes std.utf.toUTFindex() の上位版です

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s カウント対象の文字列

dchar decode(E)(ref const(E)[] s);
コードポイントを先頭から一つデコードします。

この関数は文字列の先頭から１つ以上のコード単位を取り除き、 それに対応するコードポイントを１つ返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Supercedes:
この関数は std.utf.decode() の上位版です。ただし、 関数 codePoints() の方がもっと便利です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s 先頭のコードポイントをデコードする文字列

dchar decodeReverse(E)(ref const(E)[] s);
コードポイントを末尾から一つデコードします。

この関数は文字列の末尾から１つ以上のコード単位を取り除き、 それに対応するコードポイントを１つ返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s 末尾のコードポイントをデコードする文字列

dchar safeDecode(E)(ref const(E)[] s);
先頭のコードポイントをデコードします。入力が正当でない場合にも対応しています。

この関数は文字列の末尾から１つ以上のコード単位を取り除き、 それに対応するコードポイントを１つ返します。

この関数は、エンコードが不正な文字列を入力として受け取ることも可能です。 文字列の先頭に不正なシーケンスが見つかった場合、 その部分が取り除かれ、INVALID_SEQUENCE を返します。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s 先頭のコードポイントをデコードする文字列

uint encodedLength(E)(dchar c);
コードポイント１つを取り出すのに必要なコード単位の個数を返します。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c エンコードされるコードポイント

E[] encode(E)(dchar c);
コードポイント１つをエンコードします。

この関数は、単一のコードポイントを１つ以上のコード単位からなる配列へとエンコードします。 返値はエンコードされたコード単位を含む文字列です。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Supercedes:
この関数は std.utf.encode() の上位版ですが、 関数 codeUnits() の方がより便利です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c エンコードされるコードポイント

uint encode(E)(dchar c, E[] array);
コードポイント１つを配列 array へエンコードします。

この関数は、単一のコードポイントを１つ以上のコード単位からなる配列へとエンコードします。 結果は、 ユーザーから参照で渡される固定サイズの配列に格納されます。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Supercedes:
この関数は std.utf.encode() の上位版ですが、 関数 codeUnits() の方がより便利です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c エンコードされるコードポイント

Returns:
array に書き込まれたコード単位の個数

void encode(E)(dchar c, ref Buffer!(E) buffer);
コードポイント１つを Buffer へエンコードします。

この関数は、単一のコードポイントを１つ以上のコード単位へとエンコードします。 結果は、拡張可能 Buffer に格納されます。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Supercedes:
この関数は std.utf.encode() の上位版ですが、 関数 codeUnits() の方がより便利です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c エンコードされるコードポイント

void encode(E)(dchar c, void delegate(E) dg);
コードポイント１つを delegate へエンコードします。

この関数は、単一のコードポイントを１つ以上のコード単位へとエンコードします。 結果は、一つ一つ delegate に渡されます。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Supercedes:
この関数は std.utf.encode() の上位版ですが、 関数 codeUnits() の方がより便利です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
c エンコードされるコードポイント

CodePoints!(E) codePoints(E)(invariant(E)[] s);
文字列内のコードポイントを双方向に foreach ループ可能な構造体を返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

インデックスあり/なしのどちらの foreach ループも可能です。 インデックスが指定された場合、 文字列中での、 コードポイントが始まるインデックスに設定されます。

Supercedes:
この関数は std.utf.decode() の上位版です

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s デコード対象の文字列

Examples:
 string s = "hello world";
 foreach(c;codePoints(s))
 {
     // c (常に dchar) で何かする
 }
現在のところ foreach(c; codePoints(s)) の方が、 U+FFFF で引っかかってしまう foreach(c;s) よりも優れています。

CodeUnits!(E) codeUnits(E)(dchar c);
文字に対応するコード単位の列を双方向に foreach ループ可能な構造体を返します。

この関数への入力は有効なコードポイントでなければなりません。 これは関数の事前条件で強制されます。

出力の型は自動推論されません。 テンプレート引数で明示的に文字コード型を指定する必要があります。

Supercedes:
この関数は std.utf.encode() の上位版です。

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
d エンコードされるコードポイント

Examples:
 dchar d = '\u20AC';
 foreach(c;codeUnits!(char)(d))
 {
     writefln("%X",c)
 }
 // 出力は
 // E2
 // 82
 // AC


void transcode(Src, Dst)(invariant(Src)[] s, out invariant(Dst)[] r);
ある文字コードの文字列を別の文字コードに変換します。 (下記の to!() もご参照ください)

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Supercedes:
この関数は std.utf.toUTF8(), std.utf.toUTF16(), std.utf.toUTF32() の上位版です。 (ただし、to!() の方が便利です。)

Standards:
Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

Params:
s 変換元文字列
r 変換先文字列

Examples:
 wstring ws;
 transcode("hello world",ws);
     // UTF-8 から UTF-16 へ変換

 Latin1String ls;
 transcode(ws, ls);
     // UTF-16 から ISO-8859-1 へ変換


class EncodingException: object.Exception;
このモジュールが投げる例外の基底クラス

class EncodingScheme;
全ての文字コードスキームの抽象基底クラス

static void register(string className);
EncodingScheme の派生クラスを登録

この関数によって、他のモジュールで宣言された EncodingScheme の派生クラスを登録することができます。

Examples:
 class Amiga1251 : EncodingScheme
 {
     static this()
     {
         EncodingScheme.register("path.to.Amiga1251");
     }
 }


static EncodingScheme create(string encodingName);
指定された名前の文字コードのエンコード／デコードができる EncodingScheme の派生クラスのインスタンスを取得

この関数は、register() で登録された EncodingScheme のみを扱います。

Examples:
 auto scheme = EncodingScheme.create("Amiga-1251");


abstract const string toString();
文字コードスキームの標準的な名前を返します。

abstract const string[] names();
使用できる文字コードスキーム名全ての配列を返します。

abstract const bool canEncode(dchar c);
文字 c がこの文字コードスキームで表現できるなら true を返します。

abstract const uint encodedLength(dchar c);
指定されたコードポイントを表現するのに必要なバイト数を返します。

入力は有効なコードポイントでなければなりません。

Params:
dchar c エンコード対象のコードポイント

Returns:
必要なバイト数

abstract const uint encode(dchar c, ubyte[] buffer);
指定されたコードポイントをエンコードして、ユーザの渡した固定サイズ buffer に格納。

この関数は、単一のコードポイントを１つ以上のubyteへとエンコードします。 指定する buffer はコード単位にalignされている必要があります。 (例えば、UTF-16LE や UTF-16BE は wchar-align、 UTF-32LE や UTF-32BE は dchar-aligne など)

入力は有効なコードポイントでなければなりません。

Params:
dchar c the code point to be encoded

Returns:
書き込まれたバイト数

abstract const dchar decode(ref const(ubyte)[] s);
先頭のコードポイントをデコードします。

この関数は配列の先頭から１バイト以上取り除き、 その部分が表現するコードポイントをデコードして返します。

この関数の入力は正常にエンコードされている必要があります。

Params:
const(ubyte)[] s コードポイントのデコード元文字列

abstract const dchar safeDecode(ref const(ubyte)[] s);
先頭のコードポイントをデコードします。入力が正当でない場合にも対応しています。

この関数は配列の末尾から１バイト以上のデータを取り除き、 それに対応するコードポイントを１つ返します。

この関数は、エンコードが不正な配列を入力として受け取ることも可能です。 配列の先頭に不正なシーケンスが見つかった場合、 その部分が取り除かれ、INVALID_SEQUENCE を返します。

Params:
const(ubyte)[] s 先頭の文字をデコードする対象の文字列

abstract const invariant(ubyte)[] replacementSequence();
現在の文字コードスキームで表現できない文字に対する 代替バイト列を返します。

通常、これは U+FFFD や '?' のような代替文字になります。

bool isValid(const(ubyte)[] s);
配列が正しくエンコードされていると true を返します。

Params:
const(ubyte)[] s チェック対象の配列

uint validLength(const(ubyte)[] s);
配列の先頭から始まってできるだけ長い正当なエンコードの文字列の長さを 返します。

Params:
const(ubyte)[] s チェック対象の配列

invariant(ubyte)[] sanitize(invariant(ubyte)[] s);
不正なバイト列を有効なバイト列に置き換えることで文字列をサニタイズします。 結果は指定の文字コードにおいて 正しいバイト列となることが保証されています。

入力バイト列がすでに正当なものならば元のバイト列をそのまま返し、 そうでなければ全ての不正なバイト列を その文字コードの置き換え文字に替えた新しい文字列を作って返します。

Params:
invariant(ubyte)[] s サニタイズ対象の文字列

uint firstSequence(const(ubyte)[] s);
先頭の文字に対応するエンコードされたシーケンスの長さを返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Params:
const(ubyte)[] s スライスする文字列

uint count(const(ubyte)[] s);
バイト列中にエンコードされたコードポイントの総数を返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Params:
const(ubyte)[] s カウント対象の文字列

int index(const(ubyte)[] s, int n);
n+1 番目のコードポイントが始まる配列のインデックスを返します。

この関数の入力は正常にエンコードされている必要があります。 この条件は関数の事前条件で強制されます。

Params:
const(ubyte)[] s カウント対象の文字列

class EncodingSchemeASCII: std.encoding.EncodingScheme;
ASCII を扱う文字コードスキーム

このスキームの別名は以下の通りです。 "ANSI_X3.4-1968", "ANSI_X3.4-1986", "ASCII", "IBM367", "ISO646-US", "ISO_646.irv:1991", "US-ASCII", "cp367", "csASCII" "iso-ir-6", "us"

class EncodingSchemeLatin1: std.encoding.EncodingScheme;
Latin-1 を扱う文字コードスキーム

このスキームの別名は以下の通りです。 "CP819", "IBM819", "ISO-8859-1", "ISO_8859-1", "ISO_8859-1:1987", "csISOLatin1", "iso-ir-100", "l1", "latin1"

class EncodingSchemeWindows1252: std.encoding.EncodingScheme;
Windows-1252 を扱う文字コードスキーム

このスキームの別名は以下の通りです。 "windows-1252"

class EncodingSchemeUtf8: std.encoding.EncodingScheme;
UTF-8 を扱う文字コードスキーム

このスキームの別名は以下の通りです。 "UTF-8"

class EncodingSchemeUtf16Native: std.encoding.EncodingScheme;
UTF-16 をネイティブのバイト順で扱う文字コードスキーム

このスキームの別名は以下の通りです。 "UTF-16LE" (リトルエンディアン環境のみ) "UTF-16BE" (ビッグエンディアン環境のみ)

class EncodingSchemeUtf32Native: std.encoding.EncodingScheme;
UTF-32 をネイティブのバイト順で扱う文字コードスキーム

このスキームの別名は以下の通りです。 "UTF-32LE" (リトルエンディアン環境のみ) "UTF-32BE" (ビッグエンディアン環境のみ)