[#BloombergLP-bslfmt-FormatterString_GraphemeCluster-extract]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslfmt.adoc[bslfmt]::xref:BloombergLP/bslfmt/FormatterString_GraphemeCluster.adoc[FormatterString&lowbar;GraphemeCluster]::extract
:relfileprefix: ../../../
:mrdocs:

Extract a grapheme cluster into this object from an encoded byte stream&period;

== Synopsis

Declared in `&lt;bslfmt&lowbar;formatterstring&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
void
extract(
    xref:BloombergLP/bslfmt/UnicodeCodePoint/UtfEncoding.adoc[UnicodeCodePoint::UtfEncoding] encoding,
    void const* bytes,
    size&lowbar;t maxBytes);
----

== Description

Extract a grapheme cluster from no more than the specified `maxBytes` of the byte stream at the specified `bytes` location in the specified `encoding`&period; Behavior is undefined if the input bytes are not in the specified encoding&period; Unicode Byte Order Markers are not supported and behavior is undefined if the input data contains an embedded BOM&period; Endianness is assumed to be that of the type pointed to by `bytes`&period;

For UTF&hyphen;8, behavior is undefined if `bytes` is not a valid pointer to an array of `numBytes` `unsigned char` types in contiguous memory&period;

For UTF&hyphen;16, behavior is undefined if `bytes` is not a valid pointer to an array of `numBytes&sol;2` `wchar&lowbar;t` types in contiguous memory&period; Behavior is undefined if `2 !&equals; sizeof(wchar&lowbar;t)`&period; Endianness is assumed to be the same as for the `wchar&lowbar;t` type and Byte Order Markers are not supported&period;

For UTF&hyphen;32, behavior is undefined if `bytes` is not a valid pointer to an array of `numBytes&sol;4` `wchar&lowbar;t` types in contiguous memory&period; Behavior is undefined if `4 !&equals; sizeof(wchar&lowbar;t)`&period; Endianness is assumed to be the same as for the `wchar&lowbar;t` type and Byte Order Markers are not supported&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *encoding*
| UTF encoding of the byte stream
| *bytes*
| pointer to the encoded byte stream
| *maxBytes*
| maximum number of bytes to read from `bytes`
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
