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

This `class` inherits from `bsl&colon;&colon;streambuf`, and holds and wraps another `streambuf`&period; It forwards input through the held streambuf, and checks for invalid UTF&hyphen;8&period; The wrapping object does not support ouput, only input&period; If the held `streambuf` supports seeking, seeks are supported, though not forward seeks, and `pubseekoff(0, bsl&colon;&colon;ios&lowbar;base&colon;&colon;cur)` is supported whether the wrapped `streambuf` supports seeking or not&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Utf8CheckingInStreamBufWrapper
    : public std::streambuf
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `std::streambuf`
| 
|===

== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/_04enum.adoc[`Unnamed enum`] 
| Error status values for seek failures&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2constructor-059.adoc[`Utf8CheckingInStreamBufWrapper`]         [.small]#[constructor]#
| Create a `Utf8StreamBufInputWrapper` object having no associated `streambuf`&period; Optionally specify a `basicAllocator` used to supply memory&period; If `basicAllocator` is 0 or not specified, the currently installed default allocator is used&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2constructor-0d.adoc[`Utf8CheckingInStreamBufWrapper`]         [.small]#[constructor]#
| Create an empty UTF&hyphen;8 checking streambuf wrapper using the specified `basicAllocator` to supply memory&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2constructor-05f.adoc[`Utf8CheckingInStreamBufWrapper`]         [.small]#[constructor]#
| Create a `Utf8StreamBufInputWrapper` associated with the specified `streamBuf`&period; Optionally specify a `basicAllocator` used to supply memory&period; If `basicAllocator` is 0, the currently installed default allocator is used&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2destructor.adoc[`&#126;Utf8CheckingInStreamBufWrapper`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this object&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/errorStatus.adoc[`errorStatus`] 
| Return the current error mode of this object&period; This will be either 0 (no errors or end of data), `k&lowbar;SEEK&lowbar;FAIL`, which is positive, or a value from `Utf8Util&colon;&colon;ErrorStatus`, which are all negative&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/isValid.adoc[`isValid`] 
| Return `true` if this wrapper currently holds a `streambuf` and is not in a failed seek state&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/reset.adoc[`reset`] 
| Associate this object with the specified `streamBuf`, releasing any previously held `streambuf`&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;Utf8CheckingInStreamBufWrapper, UsesBslmaAllocator&gt;`] 
| `Utf8CheckingInStreamBufWrapper` uses a `bslma` allocator&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/toAscii.adoc[`toAscii`] 
| Return a description of the specified `errorStatus`&period; Note that `errorStatus` is either&colon; &ast; `k&lowbar;SEEK&lowbar;FAIL` &ast; A value from `Utf8Util&colon;&colon;ErrorStatus`, which are all negative, in the case of invalid UTF&hyphen;8&period; &ast; 0 if no errors have occurred, in which case `NO&lowbar;ERROR` will be returned&period; Note that this includes the case where end of file has been reached without any error occurring&period; &ast; If `errorStatus` is an invalid value, &quot;(&ast; unrecognized value &ast;)&quot; will be returned&period;
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/imbue.adoc[`imbue`]  [.small]#[virtual]#
| If `sb` is the name of the `streambuf` held by this object, set `sb` to the specified `locale` as though `sb&period;pubimbue(locale)` had been called&period; If this object does not hold a `streambuf`, this method has no effect&period; Note that this function is forwarded to by the public method `pubimbue` in the base class&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/overflow.adoc[`overflow`]  [.small]#[virtual]#
| Unconditionally return `traits&lowbar;type&colon;&colon;eof()`&period; The optionally specified argument is ignored&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/pbackfail.adoc[`pbackfail`]  [.small]#[virtual]#
| Back up input one byte&period; Return the byte at the new position, or `eof` with the state of this object unchanged on failure&period; If the optionally specified `c` is not `eof`, substitute `c` for the previous byte and return that value&period; If `c` is `eof`, do not substitute it for the previous byte and return the byte was there, or if the previous byte is unknown, fail&period; If values of `c` that are not `eof` are specified, this function will succeed for at least 8 successive calls, possibly many more times&period; The behavior is undefined unless `c` is either `eof` or a value representable as a `char&lowbar;type`&period; Note that this is forwarded to with a `char&lowbar;type` passed to `c` by the public method `sputbackc` in the base class, and called with `eof` passed to `c` by the public method `sungetc` in the base class&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/seekoff.adoc[`seekoff`]  [.small]#[virtual]#
| Move the position associated with this object according to the specified `offset` and `whence`&colon;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/seekpos.adoc[`seekpos`]  [.small]#[virtual]#
| Set the position of this object to the specified absolute `offset`&period; If a seek on the held `streambuf` occurs, the specified `mode` is passed to it&period; This function delegates to `seekoff(offset, bsl&colon;&colon;ios&lowbar;base&colon;&colon;beg, mode)`, see that function for further detail&period; The behavior is undefined unless `bsl&colon;&colon;ios&lowbar;base&colon;&colon;in` is set in `mode`&period; Note that this function is forwarded to by the public method `pubseekpos` in the base class&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/showmanyc.adoc[`showmanyc`]  [.small]#[virtual]#
| Return the number of bytes that are guaranteed that can be read before `underflow` returns `eof`&period; If the object is not in a valid state, &hyphen;1 will be returned&period; Note that often, the actual number of bytes that can be read will be much greater than the value returned by this function&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/underflow.adoc[`underflow`]  [.small]#[virtual]#
| Replenish the input buffer with data obtained from the held `streambuf`, and return the next byte of input (or `eof` if no input is available)&period; This function assumes that either the input buffer is empty or that the end of it has been reached&period; If this object is not in a valid state, `eof` will be returned&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/xsgetn.adoc[`xsgetn`]  [.small]#[virtual]#
| Read up to the specified `numBytes` characters from this object to the specified `buffer` and return the number of characters successfully read&period; A return value of 0 means that either a UTF&hyphen;8 error or end of file has been encountered (`errorStatus` must be called to distinguish between the two), but a non&hyphen;zero return value less than `numBytes` will usually be returned when neither end of file nor a UTF&hyphen;8 error has been encountered&period; The behavior is undefined unless `4 &lt;&equals; numBytes`&period; Note that this function is forwarded to by the public method `sgetn` in the base class&period;
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/xsputn.adoc[`xsputn`]  [.small]#[virtual]#
| Output function, not supported in this input&hyphen;only implementation&semi; stubbed out, arguments ignored, returns 0&period; Note that this function is forwarded to by `sputn` in the base class&period;
|===



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