POD2::J...GCString(3)

✨ NAME ✨

okay bestie, welcome to the user-contributed Perl docs page for POD2::J...GCString(3) — the Unicode::GCString~[ja] page. It's literally a string treated as a sequence of UAX #29 grapheme clusters. That's the whole vibe: a “character” the way humans mean it. 💅

---

🦋 SYNOPSIS 🦋

Use it like this, no cap:

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

---

🌸 DESCRIPTION 🌸

Unicode::GCString treats a Unicode string as a sequence of “extended grapheme clusters” as defined by Unicode Standard Annex #29 [UAX #29].

A grapheme cluster is a sequence of Unicode characters made of one grapheme base plus additional grapheme extenders and/or “prepend” characters. It's close to what people think of as a “character”. iconic.

🛠️ 公開インタフェース 🛠️

コンストラクタ

new (STRING, [KEY => VALUE, ...])
new (STRING, [LINEBREAK])

This is the constructor. It builds a brand-new grapheme cluster string (a Unicode::GCString object) from the Unicode string STRING.

For the KEY => VALUE pairs, go see "オプション" in Unicode::LineBreak~[ja]. In the second form, the Unicode::LineBreak~[ja] object LINEBREAK decides the segmentation spec.

Note: the first form was introduced in release 2012.10.

長さ

• chars — Instance method. Returns the number of Unicode characters in the grapheme cluster string, i.e. its length as a Unicode string.
• columns — Instance method. Returns the number of columns of the grapheme cluster string, as determined by the built-in character database. More detail lives in "DESCRIPTION" in Unicode::LineBreak~[ja].
• length — Instance method. Returns the number of grapheme clusters in the grapheme cluster string.

文字列としての操作

• as_string, """OBJECT""" — Instance method. Explicitly converts the grapheme cluster string into a Unicode string.
• cmp (STRING), STRING "cmp" STRING — Instance method. Compares strings. Nothing especially quirky here. Either string can be a Unicode string.
• concat (STRING), STRING "." STRING — Instance method. Concatenates grapheme cluster strings. Either STRING can be a Unicode string. Heads up: the resulting string's columns (see columns()) and grapheme cluster count (see length()) are not necessarily the sum of the two strings' values. In the new string, the next position is set to the position that was set on the left-hand string.
• join ([STRING, ...]) — Instance method. Joins STRINGs with the grapheme cluster string in between. The STRINGs may include Unicode strings.
• substr (OFFSET, [LENGTH, [REPLACEMENT]]) — Instance method. Returns a substring of the grapheme cluster string. OFFSET and LENGTH are counted in grapheme clusters. If REPLACEMENT is given, it replaces the substring. REPLACEMENT may be a Unicode string.

Note: unlike the built-in substr(), this method does not return an lvalue.

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

• as_array, "@{OBJECT}", as_arrayref — Instance method. Converts the grapheme cluster string into an array of grapheme cluster info.
• eos — Instance method. Checks whether the current position is the end of the grapheme cluster string.
• item ([OFFSET]) — Instance method. Returns the OFFSET-th grapheme cluster. If OFFSET is omitted, returns the info for the grapheme cluster at the next position.
• next, "<"OBJECT">" — Instance method, iterative. Returns the grapheme cluster at the next position and advances the next position by one.
• pos ([OFFSET]) — Instance method. If OFFSET is given, sets the next position to it. Returns the next position of the grapheme cluster string.

その他

• lbc — Instance method. Returns the line breaking class (see Unicode::LineBreak~[ja]) of the first character of the first grapheme cluster.
• lbcext — Instance method. Returns the line breaking class (see Unicode::LineBreak~[ja]) of the last grapheme extender of the last grapheme cluster. If there is no grapheme extender, or if the class is CM, returns the line breaking class of the last grapheme base.

---

💀 CAVEATS 💀

• Don't call grapheme clusters “graphemes” (Larry calls them that, but still).
• Around Perl 5.10.1, implicit conversion from a Unicode::GCString object to a Unicode string can confuse the "utf8_mg_pos_cache_update" cache.

For example, instead of doing $sub = substr($gcstring, $i, $j);, do $sub = substr("$gcstring", $i, $j); or $sub = substr($gcstring->as_string, $i, $j);.

• This module implements the “early” grapheme cluster boundary detection algorithm. It does not yet support the tailoring mechanism.

---

🌈 VERSION 🌈

Check the $VERSION variable, bestie.

非互換な変更

2013.10

• new() can now take a non-Unicode string argument. In that case, the string is decoded using the iso-8859-1 (Latin 1) character set. In earlier releases, passing non-Unicode input to this method would die.

---

🔥 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.

---

mwah 💋 — source/version/date check: POD2::J...GCString(3), perl v5.42.2, 2025-06-30. periodt. 🎀