(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)
grapheme_extract — Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8
Procedural style
$haystack,$size,$type = GRAPHEME_EXTR_COUNT,$offset = 0,&$next = nullFunction to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8.
haystackString to search.
size
Maximum number items - based on the type - to return.
type
Defines the type of units referred to by the size parameter:
GRAPHEME_EXTR_COUNT (default) - size is the number of default
grapheme clusters to extract.GRAPHEME_EXTR_MAXBYTES - size is the maximum number of bytes
returned.GRAPHEME_EXTR_MAXCHARS - size is the maximum number of UTF-8
characters returned.
GRAPHEME_EXTR_COUNT limits the number of grapheme clusters (visual
units), not the number of bytes. A single grapheme cluster can span many bytes โ for
example, a family emoji with ZWJ sequences (๐จโ๐ฉโ๐งโ๐ฆ) is
one grapheme cluster but 25 bytes. When the extracted string must fit within a byte budget,
use GRAPHEME_EXTR_MAXBYTES instead.
GRAPHEME_EXTR_MAXBYTES always returns complete grapheme clusters
within the byte budget, but returns an empty string if the budget is smaller than the
first grapheme cluster.
offset
Starting position in haystack in bytes - if given, it must be zero or a
positive value that is less than or equal to the length of haystack in
bytes, or a negative value that counts from the end of haystack.
If offset does not point to the first byte of a UTF-8
character, the start position is moved to the next character boundary.
nextReference to a value that will be set to the next starting position. When the call returns, this may point to the first byte position past the end of the string.
A string starting at offset offset and ending on a default grapheme cluster
boundary that conforms to the size and type specified,
or false on failure.
| Version | Description |
|---|---|
| 7.1.0 |
Support for negative offsets has been added.
|
Example #1 grapheme_extract() example
<?php
$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));
?>The above example will output:
o%CC%88