Truncate a UTF-8 string to a some maximum number of bytes, codepoints, or glyphs.

This class takes some UTF-8 string as input, and emits a valid UTF-8 string which is no longer than given byte, codepoint, or glyph limits.

$short = id(new PhutilUTF8StringTruncator())
  ->setMaximumGlyphs(80)
  ->truncateString($long);

Byte limits restrict the number of bytes the result may contain. They are appropriate when you care about how much storage a string requires.

Codepoint limits restrict the number of codepoints the result may contain. Since codepoints may have up to 4 bytes, the resulting strings may require have more than this many bytes. This kind of limit is appropriate when you are using UTF-8 storage.

Glyph limits restrict the display size of the string. Because a single glyph may have an arbitrary number of combining characters, this does not impose a storage size limit on the string: a string with only one glyph may require an arbitrarily large number of bytes.

You can set more than one limit; the smallest limit will be used.