[#BloombergLP-bdlde-Utf8Util]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::Utf8Util
:relfileprefix: ../../
:mrdocs:

This struct provides a namespace for static methods used for validating UTF&hyphen;8 strings, for counting the number of Unicode code points in them, for advancing pointers through UTF&hyphen;8 strings by a specified number of Unicode code points, for counting the number of bytes a UTF&hyphen;8 leading substring occupies, for counting the number of bytes in a UTF&hyphen;8 character, and for appending a Unicode character to a UTF&hyphen;8 string&period;

== Synopsis

Declared in `&lt;bdlde&lowbar;utf8util&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct Utf8Util;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8Util/IntPtr.adoc[`IntPtr`] 
| This `typedef` is an alias to `bsls&colon;&colon;Types&colon;&colon;IntPtr`&period;
| xref:BloombergLP/bdlde/Utf8Util/Uint64.adoc[`Uint64`] 
| This `typedef` is an alias to `bsls&colon;&colon;Types&colon;&colon;Uint64`&period;
| xref:BloombergLP/bdlde/Utf8Util/UintPtr.adoc[`UintPtr`] 
| This `typedef` is an alias to `bsls&colon;&colon;Types&colon;&colon;UintPtr`&period;
| xref:BloombergLP/bdlde/Utf8Util/size_type.adoc[`size&lowbar;type`] 
| This `typedef` is an alias to `bsls&colon;&colon;Types&colon;&colon;size&lowbar;type`&period;
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8Util/_04enum.adoc[`Unnamed enum`] 
| Substitution code point constants&period;
| xref:BloombergLP/bdlde/Utf8Util/ErrorStatus.adoc[`ErrorStatus`] 
| Enumerate the error status values that are returned (possibly through an out parameter) from some methods in this utility&period; Note that some of the functions in this `struct` have a return value that is non&hyphen;negative on success, and one of these values when an error occurs, so all of these values must be negative to distinguish them from a &quot;success&quot; value&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8Util/advanceIfValid-0a.adoc[`advanceIfValid`] 
| `advanceIfValid` overloads
| xref:BloombergLP/bdlde/Utf8Util/advanceRaw-06d.adoc[`advanceRaw`] 
| `advanceRaw` overloads
| xref:BloombergLP/bdlde/Utf8Util/appendUtf8Character.adoc[`appendUtf8Character`] 
| Append the UTF&hyphen;8 encoding of the specified Unicode `codePoint` to the specified `output` string&period; Return 0 on success, and a non&hyphen;zero value otherwise&period;
| xref:BloombergLP/bdlde/Utf8Util/appendUtf8CodePoint-01.adoc[`appendUtf8CodePoint`] 
| `appendUtf8CodePoint` overloads
| xref:BloombergLP/bdlde/Utf8Util/codePointValue.adoc[`codePointValue`] 
| Return the numeric value of the UTF&hyphen;8&hyphen;encoded code point beginning at the specified `codePoint`&period; The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF&hyphen;8 encoded character&period;
| xref:BloombergLP/bdlde/Utf8Util/getByteSize.adoc[`getByteSize`] 
| Return the length (in bytes) of the UTF&hyphen;8&hyphen;encoded code point beginning at the specified `codePoint`&period; The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF&hyphen;8 encoded character&period; Note that the value returned will be in the range `&lsqb;1 &period;&period; 4&rsqb;`&period; Also note that 1 is returned if `0 &equals;&equals; &ast;codePoint` since &apos;0&apos; is a valid 1&hyphen;byte encoding&period;
| xref:BloombergLP/bdlde/Utf8Util/getLineAndColumnNumber-0d.adoc[`getLineAndColumnNumber`] 
| `getLineAndColumnNumber` overloads
| xref:BloombergLP/bdlde/Utf8Util/isValid-02.adoc[`isValid`] 
| `isValid` overloads
| xref:BloombergLP/bdlde/Utf8Util/isValidCodePoint.adoc[`isValidCodePoint`] 
| If the specified `codePoint` (having at least the specified `numBytes`) refers to a valid UTF&hyphen;8 code point then return `true` and load the specified `status` with the number of bytes in the code&hyphen;point&semi; otherwise, if `codePoint` is not a valid code&hyphen;point, return `false` and load `status` with one of the (negative) `ErrorStatus` constants&period; The behavior is undefined unless `numBytes &gt; 0`&period;
| xref:BloombergLP/bdlde/Utf8Util/numBytesIfValid.adoc[`numBytesIfValid`] 
| Return the length (in bytes) of the specified `numCodePoints` UTF&hyphen;8 encodings in the specified `string`, or a value less than 0 if `string` contains less than `numCodePoints` encodings&period; The behavior is undefined unless `string` refers to valid UTF&hyphen;8&period; Note that `string` may contain more than `numCodePoints` encodings in which case the trailing ones are ignored&period;
| xref:BloombergLP/bdlde/Utf8Util/numBytesInCodePoint.adoc[`numBytesInCodePoint`] 
| Return the length (in bytes) of the UTF&hyphen;8&hyphen;encoded code point beginning at the specified `codePoint`&period; The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF&hyphen;8 encoded character&period; Note that the value returned will be in the range `&lsqb;1 &period;&period; 4&rsqb;`&period; Also note that 1 is returned if `0 &equals;&equals; &ast;codePoint` since &apos;0&apos; is a valid 1&hyphen;byte encoding&period;
| xref:BloombergLP/bdlde/Utf8Util/numBytesRaw.adoc[`numBytesRaw`] 
| Return the length (in bytes) of the specified `numCodePoints` UTF&hyphen;8 encodings in the specified `string`, or a value less than 0 if `string` contains less than `numCodePoints` encodings&period; The behavior is undefined unless `string` refers to valid UTF&hyphen;8&period; Note that `string` may contain more than `numCodePoints` encodings in which case the trailing ones are ignored&period;
| xref:BloombergLP/bdlde/Utf8Util/numCharacters-01.adoc[`numCharacters`] 
| `numCharacters` overloads
| xref:BloombergLP/bdlde/Utf8Util/numCharactersIfValid-06.adoc[`numCharactersIfValid`] 
| `numCharactersIfValid` overloads
| xref:BloombergLP/bdlde/Utf8Util/numCharactersRaw-0b.adoc[`numCharactersRaw`] 
| `numCharactersRaw` overloads
| xref:BloombergLP/bdlde/Utf8Util/numCodePointsIfValid-088.adoc[`numCodePointsIfValid`] 
| `numCodePointsIfValid` overloads
| xref:BloombergLP/bdlde/Utf8Util/numCodePointsRaw-0c.adoc[`numCodePointsRaw`] 
| `numCodePointsRaw` overloads
| xref:BloombergLP/bdlde/Utf8Util/readIfValid.adoc[`readIfValid`] 
| Read from the specified `input` and copy _valid_ UTF&hyphen;8 (only) to the specified `outputBuffer` having the specified `outputBufferLength` (in bytes)&period; Load the specified `status` with&colon; &ast; 0 if `input` reached `eof` without encountering any invalid UTF&hyphen;8 or prematurely exhausting `outputBuffer`&period; &ast; A positive value if `input` was not completely read due to `outputBuffer` being filled (or nearly filled) without encountering any invalid UTF&hyphen;8&period; &ast; A negative value from `ErrorStatus` if invalid UTF&hyphen;8 was encountered (without having written the invalid sequence to `outputBuffer`)&period; Return the number of bytes of valid UTF&hyphen;8 written to &apos;outputBuffer&period; If no invalid UTF&hyphen;8 is encountered, or if `input` supports `sputbackc` with a putback buffer capacity of at least 4 bytes, `input` will be left positioned at the end of the valid UTF&hyphen;8 read, otherwise, `input` will be left in an unspecified state&period; The behavior is undefined unless `4 &lt;&equals; outputBufferLength`&period; Note that this function will stop reading `input` when less than 4 bytes of space remain in `outputBuffer` to prevent the possibility of a 4&hyphen;byte UTF&hyphen;8 sequence being truncated partway through&period;
| xref:BloombergLP/bdlde/Utf8Util/replaceErrors-0f.adoc[`replaceErrors`] 
| `replaceErrors` overloads
| xref:BloombergLP/bdlde/Utf8Util/toAscii.adoc[`toAscii`] 
| Return the non&hyphen;modifiable string representation of the `ErrorStatus` enumerator matching the specified `value`, if it exists, and &quot;(&ast; unrecognized value &ast;)&quot; otherwise&period; The string representation of an enumerator that matches `value` is the enumerator name with the &quot;k&lowbar;&quot; prefix elided&period; Note that this method may be used to aid in interpreting status values that are returned from some methods in this utility&period; See `ErrorStatus`&period;
|===



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