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

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

== Synopsis

Declared in `<bdlde_utf8checkinginstreambufwrapper.h>`

[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.
|===


== 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`. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0 or not specified, the currently installed default allocator is used.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2constructor-0d.adoc[`Utf8CheckingInStreamBufWrapper`]         [.small]#[constructor]#
| Create an empty UTF‐8 checking streambuf wrapper using the specified `basicAllocator` to supply memory.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2constructor-05f.adoc[`Utf8CheckingInStreamBufWrapper`]         [.small]#[constructor]#
| Create a `Utf8StreamBufInputWrapper` associated with the specified `streamBuf`. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2destructor.adoc[`~Utf8CheckingInStreamBufWrapper`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this object.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/errorStatus.adoc[`errorStatus`] 
| Return the current error mode of this object. This will be either 0 (no errors or end of data), `k_SEEK_FAIL`, which is positive, or a value from `Utf8Util::ErrorStatus`, which are all negative.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/isValid.adoc[`isValid`] 
| Return `true` if this wrapper currently holds a `streambuf` and is not in a failed seek state.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/reset.adoc[`reset`] 
| Associate this object with the specified `streamBuf`, releasing any previously held `streambuf`.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Utf8CheckingInStreamBufWrapper, UsesBslmaAllocator>`] 
| `Utf8CheckingInStreamBufWrapper` uses a `bslma` allocator.
|===


== Static Member Functions

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


== 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.pubimbue(locale)` had been called. If this object does not hold a `streambuf`, this method has no effect. Note that this function is forwarded to by the public method `pubimbue` in the base class.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/overflow.adoc[`overflow`]  [.small]#[virtual]#
| Unconditionally return `traits_type::eof()`. The optionally specified argument is ignored.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/pbackfail.adoc[`pbackfail`]  [.small]#[virtual]#
| Back up input one byte. Return the byte at the new position, or `eof` with the state of this object unchanged on failure. If the optionally specified `c` is not `eof`, substitute `c` for the previous byte and return that value. 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. If values of `c` that are not `eof` are specified, this function will succeed for at least 8 successive calls, possibly many more times. The behavior is undefined unless `c` is either `eof` or a value representable as a `char_type`. Note that this is forwarded to with a `char_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.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/seekoff.adoc[`seekoff`]  [.small]#[virtual]#
| Move the position associated with this object according to the specified `offset` and `whence`:
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/seekpos.adoc[`seekpos`]  [.small]#[virtual]#
| Set the position of this object to the specified absolute `offset`. If a seek on the held `streambuf` occurs, the specified `mode` is passed to it. This function delegates to `seekoff(offset, bsl::ios_base::beg, mode)`, see that function for further detail. The behavior is undefined unless `bsl::ios_base::in` is set in `mode`. Note that this function is forwarded to by the public method `pubseekpos` in the base class.
| 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`. If the object is not in a valid state, ‐1 will be returned. Note that often, the actual number of bytes that can be read will be much greater than the value returned by this function.
| 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). This function assumes that either the input buffer is empty or that the end of it has been reached. If this object is not in a valid state, `eof` will be returned.
| 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. A return value of 0 means that either a UTF‐8 error or end of file has been encountered (`errorStatus` must be called to distinguish between the two), but a non‐zero return value less than `numBytes` will usually be returned when neither end of file nor a UTF‐8 error has been encountered. The behavior is undefined unless `4 <= numBytes`. Note that this function is forwarded to by the public method `sgetn` in the base class.
| xref:BloombergLP/bdlde/Utf8CheckingInStreamBufWrapper/xsputn.adoc[`xsputn`]  [.small]#[virtual]#
| Output function, not supported in this input‐only implementation; stubbed out, arguments ignored, returns 0. Note that this function is forwarded to by `sputn` in the base class.
|===



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