[#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‐8 strings, for counting the number of Unicode code points in them, for advancing pointers through UTF‐8 strings by a specified number of Unicode code points, for counting the number of bytes a UTF‐8 leading substring occupies, for counting the number of bytes in a UTF‐8 character, and for appending a Unicode character to a UTF‐8 string.

== Synopsis

Declared in `<bdlde_utf8util.h>`

[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::Types::IntPtr`.
| xref:BloombergLP/bdlde/Utf8Util/Uint64.adoc[`Uint64`] 
| This `typedef` is an alias to `bsls::Types::Uint64`.
| xref:BloombergLP/bdlde/Utf8Util/UintPtr.adoc[`UintPtr`] 
| This `typedef` is an alias to `bsls::Types::UintPtr`.
| xref:BloombergLP/bdlde/Utf8Util/size_type.adoc[`size_type`] 
| This `typedef` is an alias to `bsls::Types::size_type`.
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8Util/_04enum.adoc[`Unnamed enum`] 
| Substitution code point constants.
| 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. Note that some of the functions in this `struct` have a return value that is non‐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 "success" value.
|===


== 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‐8 encoding of the specified Unicode `codePoint` to the specified `output` string. Return 0 on success, and a non‐zero value otherwise.
| xref:BloombergLP/bdlde/Utf8Util/appendUtf8CodePoint-01.adoc[`appendUtf8CodePoint`] 
| `appendUtf8CodePoint` overloads
| xref:BloombergLP/bdlde/Utf8Util/codePointValue.adoc[`codePointValue`] 
| Return the numeric value of the UTF‐8‐encoded code point beginning at the specified `codePoint`. The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF‐8 encoded character.
| xref:BloombergLP/bdlde/Utf8Util/getByteSize.adoc[`getByteSize`] 
| Return the length (in bytes) of the UTF‐8‐encoded code point beginning at the specified `codePoint`. The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF‐8 encoded character. Note that the value returned will be in the range `[1 .. 4]`. Also note that 1 is returned if `0 == *codePoint` since '0' is a valid 1‐byte encoding.
| 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‐8 code point then return `true` and load the specified `status` with the number of bytes in the code‐point; otherwise, if `codePoint` is not a valid code‐point, return `false` and load `status` with one of the (negative) `ErrorStatus` constants. The behavior is undefined unless `numBytes > 0`.
| xref:BloombergLP/bdlde/Utf8Util/numBytesIfValid.adoc[`numBytesIfValid`] 
| Return the length (in bytes) of the specified `numCodePoints` UTF‐8 encodings in the specified `string`, or a value less than 0 if `string` contains less than `numCodePoints` encodings. The behavior is undefined unless `string` refers to valid UTF‐8. Note that `string` may contain more than `numCodePoints` encodings in which case the trailing ones are ignored.
| xref:BloombergLP/bdlde/Utf8Util/numBytesInCodePoint.adoc[`numBytesInCodePoint`] 
| Return the length (in bytes) of the UTF‐8‐encoded code point beginning at the specified `codePoint`. The behavior is undefined unless `codePoint` is the address of the first byte of a valid UTF‐8 encoded character. Note that the value returned will be in the range `[1 .. 4]`. Also note that 1 is returned if `0 == *codePoint` since '0' is a valid 1‐byte encoding.
| xref:BloombergLP/bdlde/Utf8Util/numBytesRaw.adoc[`numBytesRaw`] 
| Return the length (in bytes) of the specified `numCodePoints` UTF‐8 encodings in the specified `string`, or a value less than 0 if `string` contains less than `numCodePoints` encodings. The behavior is undefined unless `string` refers to valid UTF‐8. Note that `string` may contain more than `numCodePoints` encodings in which case the trailing ones are ignored.
| 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‐8 (only) to the specified `outputBuffer` having the specified `outputBufferLength` (in bytes). Load the specified `status` with: * 0 if `input` reached `eof` without encountering any invalid UTF‐8 or prematurely exhausting `outputBuffer`. * A positive value if `input` was not completely read due to `outputBuffer` being filled (or nearly filled) without encountering any invalid UTF‐8. * A negative value from `ErrorStatus` if invalid UTF‐8 was encountered (without having written the invalid sequence to `outputBuffer`). Return the number of bytes of valid UTF‐8 written to 'outputBuffer. If no invalid UTF‐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‐8 read, otherwise, `input` will be left in an unspecified state. The behavior is undefined unless `4 <= outputBufferLength`. 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‐byte UTF‐8 sequence being truncated partway through.
| xref:BloombergLP/bdlde/Utf8Util/replaceErrors-0f.adoc[`replaceErrors`] 
| `replaceErrors` overloads
| xref:BloombergLP/bdlde/Utf8Util/toAscii.adoc[`toAscii`] 
| Return the non‐modifiable string representation of the `ErrorStatus` enumerator matching the specified `value`, if it exists, and "(* unrecognized value *)" otherwise. The string representation of an enumerator that matches `value` is the enumerator name with the "k_" prefix elided. Note that this method may be used to aid in interpreting status values that are returned from some methods in this utility. See `ErrorStatus`.
|===



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