附属書B 符号位置境界へのアクセス

B.1　導入

B.1: Introduction

文字は，符号位置 と呼ぶ(スカラ値 とも呼ぶ)数によってUnicodeで表現される。これらの数は，0 ～ 1,114,111 = 10FFFF₁₆を範囲とできる。(ただし，これらの値の幾つかは，文字としては使用できない。)各々の符号位置は，32ビット符号単位で直接に符号化できる。この符号化を，UCS-4(又はUTF-32)と呼ぶ。しかし，DOM規定は，(FFFF₁₆より小さい値をもつ)よく使う文字が，単一の16ビット符号単位によって表現される，UTF-16を使う。一方，FFFF₁₆より大きい文字には，サロゲートペア(surrogate pair) と呼ばれる符号単位の特殊な対を使う。より詳細な情報のためには，[Unicode]，又はUnicode関連のウェブサイトを参照すること。

Characters are represented in Unicode by numbers called code points (also called scalar values). These numbers can range from 0 up to 1,114,111 = 10FFFF₁₆ (although some of these values are illegal). Each code point can be directly encoded with a 32-bit code unit. This encoding is termed UCS-4 (or UTF-32). The DOM specification, however, uses UTF-16, in which the most frequent characters (which have values less than FFFF₁₆) are represented by a single 16-bit code unit, while characters above FFFF₁₆ use a special pair of code units called a surrogate pair. For more information, see [Unicode] or the Unicode Web site.

符号単位とは対照的に符号位置によるインデクス付けは，プログラム間では共通ではないが，XPath(並びにその関係でXSLT及びXPointer)などの規定は，符号位置インデクスを使う。それらフォーマットを用いたインタフェースを使うために，プログラム言語は，符号位置インデクスを符号単位インデクスに変換したり戻したりする文字列処理の方法を提供することが望ましい。これらの関数を，本来的には提供しない言語もある。これら言語のために，DOMStringへと束縛される言語本来のString(文字列)型は，この変換を可能にするように拡張されることが望ましい。それらAPIはどのようなものになるかという例を，B.2で示す。

While indexing by code points as opposed to code units is not common in programs, some specifications such as XPath (and therefore XSLT and XPointer) use code point indices. For interfacing with such formats it is recommended that the programming language provide string processing methods for converting code point indices to code unit indices and back. Some languages do not provide these functions natively; for these it is recommended that the native String type that is bound to DOMString be extended to enable this conversion. An example of how such an API might look is supplied below.

備考　これらのメソッドは，要求された機能性の型の例として示されるので，メソッド，例外及びインタフェースの名前は，この附属書で示すものと異なってもよい。

Note: Since these methods are supplied as an illustrative example of the type of functionality that is required, the names of the methods, exceptions, and interface may differ from those given here.

B.2 メソッド

B.2: Methods

インタフェース StringExtend Interface StringExtend

言語の本来的なStringのクラス又はインタフェースに対する拡張

Extensions to a language's native String class or interface

IDL定義
IDL Definition

interface StringExtend {
  int                findOffset16(in int offset32)
                                        raises(StringIndexOutOfBoundsException);
  int                findOffset32(in int offset16)
                                        raises(StringIndexOutOfBoundsException);
};

メソッド
Methods

findOffset16

UTF-32オフセットに対応するUTF-16オフセットを返す。ランダムアクセスのために使用される。

Returns the UTF-16 offset that corresponds to a UTF-32 offset. Used for random access.

備考　 UTF-32オフセットからUTF-16オフセットへは可逆変換であって，いつでも元に戻すことができる。offset16がサロゲートペアの中間にはない場合及びその場合に限り，UTF-16オフセットからUTF-32オフセットへは可逆変換であって，いつでも元に戻すことができる。対でないサロゲートは，単一のUTF-16値として数える。

Note: You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.

パラメタ

Parameters

int型のoffset32 offset32 of type int: UTF-32オフセット。

UTF-32 offset.

返却値

Return Value

int

UTF-16オフセット。

UTF-16 offset

例外

Exceptions

StringIndexOutOfBoundsException

offset32が境界外である場合。

if offset32 is out of bounds.

findOffset32

UTF-16オフセットに対応するUTF-32オフセットを返す。ランダムアクセスのために使用する。文字列のUTF-32による長さを見つけるためには，次を使用する。

Returns the UTF-32 offset corresponding to a UTF-16 offset. Used for random access. To find the UTF-32 length of a string, use:

len32 = findOffset32(source, source.length());

備考　 UTF-16オフセットがサロゲートペアの中間にある場合に，その対(ペア)のUTF-32オフセットの終端が返される。すなわち，対の終端の後の文字のインデクスが返される。UTF-32オフセットからUTF-16オフセットへは可逆変換であって，いつでも元に戻すことができる。offset16がサロゲートペアの中間にはない場合及びその場合に限り，UTF-16オフセットからUTF-32オフセットへは可逆変換であって，いつでも元に戻すことができる。対でないサロゲートは，単一のUTF-16値として数える。

Note: If the UTF-16 offset is into the middle of a　surrogate pair, then the UTF-32 offset of the end of the pair is returned; that is, the index of the char after the end of the pair. You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.