=encoding utf-8

=head1 NAME

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

=head1 SYNOPSIS

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

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

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

=head2 公開インタフェース

=head3 コンストラクタ

=over 4

=item new (STRING, [LINEBREAK])

I<コンストラクタ>。
Unicode文字列 STRING から新たに書記素クラスタ文字列
(Unicode::GCString オブジェクト) を作る。
オプションの L<Unicode::LineBreak> オブジェクト LINEBREAK は分割の仕様を制御する。

=item copy

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

=back

=head3 長さ

=over 4

=item chars

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

=item columns

I<インスタンスメソッド>。
組み込みの文字データベースで決定される書記素クラスタ文字列の桁数を返す。
詳しくは L<Unicode::LineBreak::JA_JP/DESCRIPTION> を参照。

=item length

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

=back

=head3 文字列としての操作

=over 4

=item as_string

=item C<">OBJECTC<">

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

=item cmp (STRING)

=item STRING C<cmp> STRING

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

=item concat (STRING)

=item STRING C<.> STRING

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

=item join ([STRING, ...])

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

=item substr (OFFSET, [LENGTH, [REPLACEMENT]])

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

=back

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

=over 4

=item as_array

=item C<@{>OBJECTC<}>

=item as_arrayref

I<インスタンスメソッド>。
書記素クラスタ文字列を、書記素クラスタの情報の配列に変換する。

=item eos

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

=item flag ([OFFSET, [VALUE]])

I<インスタンスメソッド>。
OFFSET番めの書記素クラスタのフラグ値を取得、設定する。
OFFSET を指定しないと、次の位置の書記素クラスタのフラグ値を返す。
フラグ値は 255 を超えない非負整数で、はじめは 0。

定義ずみのフラグには次のものがある。

=over 4

=item Unicode::LineBreak::ALLOW_BEFORE

この書記素クラスタの直前で行分割を許す。

=item Unicode::LineBreak::PROHIBIT_BEFORE

この書記素クラスタの直前での行分割を禁ずる。

=back

=item item ([OFFSET])

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

=item lbclass ([OFFSET])

OFFSET番めの書記素クラスタの最初の文字の行分割クラス
(L<Unicode::LineBreak::JA_JP> 参照) を返す。
OFFSET を指定しないと、次の位置の書記素クラスタの情報を返す。

=item lbclass_ext ([OFFSET])

OFFSET番めの書記素クラスタの最後の書記素エキステンダの行分割クラス
(L<Unicode::LineBreak> 参照) を返す。
書記素エキステンダがないか、またはクラスが CM の場合は、lbclass() の値を返す。

=item next

=item C<E<lt>>OBJECTC<E<gt>>

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

=item pos ([OFFSET])

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

=back

=head1 CAVEAT

=over 4

=item *

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

たとえば、つぎのように

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

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

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

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

=item *

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

=back

=head1 VERSION

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

このモジュールの開発版が
L<http://hatuka.nezumi.nu/repos/Unicode-LineBreak/>
にある。

=head1 SEE ALSO

[UAX #29]
Mark Davis (2009-2010).
I<Unicode Standard Annex #29: Unicode Text Segmentation>, Revision 15-17.
L<http://www.unicode.org/reports/tr29/>.

=head1 AUTHOR

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

=head1 COPYRIGHT

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

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