NAME

       Unicode::GCString~[ja] - UAX #29 書記素クラスタの列としての文字列

SYNOPSIS

           use Unicode::GCString;
           $gcstring = Unicode::GCString->new($string);

DESCRIPTION

       Unicode::GCString はUnicode文字列を、Unicode標準附属書29 [UAX #29]
       で定義される「拡張書記素クラスタ」〔extended grapheme cluster〕の列として扱う。

       書記素クラスタ〔grapheme cluster〕は、Unicode文字の列で、ひとつの書記素基底〔grapheme
       base〕と、付加的な書記素エキステンダ〔grapheme
       extender〕および/または「前置」文字〔“prepend”
       character〕から成る。これは人が「文字」とみなすものに近い。

   公開インタフェース
       コンストラクタ

       new (STRING, [KEY => VALUE, ...])
       new (STRING, [LINEBREAK])
           コンストラクタ。 Unicode文字列 STRING から新たに書記素クラスタ文字列
           (Unicode::GCString オブジェクト) を作る。

           KEY => VALUE の対については "オプション" in Unicode::LineBreak~[ja]を参照。
           第二の形式では、 Unicode::LineBreak~[ja] オブジェクト LINEBREAK
           で分節の仕様を決定する。

           注: 最初の形式はリリース 2012.10 で導入された。

       copy
           コピーコンストラクタ。 書記素クラスタ文字列の複製を作る。
           新たな文字列では、次の位置は先頭になる。

       長さ

       chars
           インスタンスメソッド。
           書記素クラスタ文字列に含まれるUnicode文字の数、つまりUnicode文字列としての長さを返す。

       columns
           インスタンスメソッド。
           組み込みの文字データベースで決定される書記素クラスタ文字列の桁数を返す。 詳しくは
           "DESCRIPTION" in Unicode::LineBreak~[ja] を参照。

       length
           インスタンスメソッド。 書記素クラスタ文字列に含まれる書記素クラスタの数を返す。

       文字列としての操作

       as_string
       """OBJECT"""
           インスタンスメソッド。 書記素クラスタ文字列を明示的にUnicode文字列に変換する。

       cmp (STRING)
       STRING "cmp" STRING
           インスタンスメソッド。 文字列を比較する。特に風変わりなところはない。
           文字列のどちらかがUnicode文字列でもよい。

       concat (STRING)
       STRING "." STRING
           インスタンスメソッド。 書記素クラスタ文字列を結合する。 STRING
           のどちらかがUnicode文字列でもよい。 結果の文字列の桁数 (columns() を参照)
           や書記素クラスタの数 (length() を参照)
           は、ふたつの文字列のそれの和になるとはかぎらないことに注意。
           新たな文字列では、次の位置は左辺の文字列にセットされていた位置になる。

       join ([STRING, ...])
           インスタンスメソッド。 STRING を、書記素クラスタ文字列をはさんでつなげる。 STRING
           のうちに Unicode文字列があってもよい。

       substr (OFFSET, [LENGTH, [REPLACEMENT]])
           インスタンスメソッド。 書記素クラスタ文字列の部分文字列を返す。 OFFSET と LENGTH
           は書記素クラスタで数える。 REPLACEMENT を指定すると、部分文字列をそれで置き換える。
           REPLACEMENT は Unicode文字列でもよい。

           Note: このメソッドは組み込み関数 substr() と異なり、左辺値を返すことはない。

       書記素クラスタの列としての操作

       as_array
       "@{"OBJECT"}"
       as_arrayref
           インスタンスメソッド。 書記素クラスタ文字列を、書記素クラスタの情報の配列に変換する。

       eos インスタンスメソッド。 現在の位置が書記素クラスタ文字列の最後かどうか調べる。

       item ([OFFSET])
           インスタンスメソッド。 OFFSET番めの書記素クラスタを返す。 OFFSET
           を指定しないと、次の位置の書記素クラスタの情報を返す。

       next
       "<"OBJECT">"
           インスタンスメソッド、反復的。
           次の位置の書記素クラスタを返し、次の位置をひとつ進める。

       pos ([OFFSET])
           インスタンスメソッド。 OFFSET を指定した場合は、次の位置をそれにする。
           書記素クラスタ文字列の次の位置を返す。

       その他

       lbc インスタンスメソッド。 最初の書記素クラスタの最初の文字の行分割クラス
           (Unicode::LineBreak~[ja] 参照) を返す。

       lbcext
           インスタンスメソッド。 最後の書記素クラスタの最後の書記素エキステンダの行分割クラス
           (Unicode::LineBreak~[ja] 参照) を返す。 書記素エキステンダがないか、またはクラスが CM
           の場合は、 最後の書記素基底の行分割クラスを返す。

CAVEATS

       •   書記素クラスタを「書記素」と呼ぶべきではない (ラリーはそう呼ぶが)。

       •   Perl の 5.10.1 版あたりでは、Unicode::GCString オブジェクトから Unicode
           文字列への暗黙の変換が "utf8_mg_pos_cache_update" キャッシュを混乱させることがある。

           たとえば、つぎのように

               $sub = substr($gcstring, $i, $j);

           するかわりに、つぎのようにするとよい。

               $sub = substr("$gcstring", $i, $j);

               $sub = substr($gcstring->as_string, $i, $j);

       •   このモジュールでは「初期の」書記素クラスタ境界判別アルゴリズムを実装している。
           手直し〔tailoring〕の機構にはまだ対応していない。

VERSION

       $VERSION 変数を参照してほしい。

   非互換な変更
       2013.10
           •   new() メソッドは非Unicode文字列を引数に取れるようになった。
               その場合、文字列をiso-8859-1 (Latin 1) キャラクタセットで復号する。
               以前のリリースでは、このメソッドに非Unicodeを入力すると死ぬようになっていた。

SEE ALSO

       [UAX #29] Mark Davis (ed.) (2009-2013).  Unicode Standard Annex #29: Unicode Text
       Segmentation, Revisions 15-23.  <http://www.unicode.org/reports/tr29/>.

AUTHOR

       Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>

COPYRIGHT

       Copyright (C) 2009-2013 Hatuka*nezumi - IKEDA Soji.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.