[#BloombergLP-balxml-Utf8ReaderWrapper]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balxml.adoc[balxml]::Utf8ReaderWrapper
:relfileprefix: ../../
:mrdocs:

This class "has a" pointer to a held and wrapped `Reader` object, and operations on this object are passed to the held reader. The held reader is passed a `Utf8CheckingInStreamBufWrapper`, which holds and wraps a normal `streambuf`. The `Utf8CheckingInStreamBufWrapper` checks input for invalid UTF‐8, and if it detects any, makes the diagnosis of the problem available through the `errorInfo` accessor.

== Synopsis

Declared in `<balxml_utf8readerwrapper.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Utf8ReaderWrapper
    : public xref:BloombergLP/balxml/Reader.adoc[Reader]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/balxml/Reader.adoc[Reader]`
| This abstract class defines an interface for fast, forward‐only access to XML data. An object belonging to a derived‐class implementation of this protocol is required to be re‐usable, such that a new XML document can be parsed using the same reader object by calling `close` followed by another `open`.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Reader/StreamBufPtr.adoc[`StreamBufPtr`] 
| Managed pointer to a `bsl::streambuf` used for external entity input.
| xref:BloombergLP/balxml/Reader/XmlResolverFunctor.adoc[`XmlResolverFunctor`] 
| Type for a user supplied functor that finds and opens an external resource for the specified `location` and/or `namespaceUri` and returns that resource as a managed pointer to a stream. The `location` argument specifies the location of the external resource and is typically a filename or a URI, depending on the context. The `namespaceUri` argument always refers to the XML namespace of the entity to be resolved. A conforming functor returns an empty managed pointer if it cannot resolve the resource. For example, the reader may use a resolver to open an external entity, even if the reader does not do validation (see definition of `<!ENTITY>` in the XML standard). Note that either argument can be NULL in situations where its value is not needed or can be computed from the other argument.
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Reader/NodeType-02.adoc[`NodeType`] 
| Node types returned by `nodeType`, representing XML syntactic constructs within a document. Not every `Reader` implementation distinguishes all node types.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Utf8ReaderWrapper/2constructor.adoc[`Utf8ReaderWrapper`]         [.small]#[constructor]#
| Create a `Utf8ReaderWrapper` that holds the specified `reader`. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. The behavior is undefined unless `reader` has never been opened or closed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/2destructor.adoc[`~Utf8ReaderWrapper`] [.small]#[destructor]# [.small]#[virtual]#
| Close the held reader and destroy this object.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/advanceToNextNode.adoc[`advanceToNextNode`]  [.small]#[virtual]#
| Move to the next node in the data steam created by `open` thus allowing the node's properties to be queried via the `Reader` accessors. Return 0 on successful read, 1 if there are no more nodes to read, and a negative number otherwise. Note that each call to `advanceToNextNode` invalidates strings and data structures returned when `Reader` accessors where call for the "prior node". E.g., the pointer returned from `nodeName` for this node will not be valid once `advanceToNextNode` is called. Note that the reader will not be on a valid node until the first call to `advanceToNextNode` after the reader is opened.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/allocator.adoc[`allocator`] 
| Return the allocator used by this object to allocate memory.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/close.adoc[`close`]  [.small]#[virtual]#
| Close the reader. Most, but not all state is reset. Specifically, the XML resource resolver and the prefix stack remain. The prefix stack shall be returned to the stack depth it had when `setPrefixStack` was called. Call the method `open` to reuse the reader. Note that `close` invalidates all strings and data structures obtained via `Reader` accessors. E.g., the pointer returned from `nodeName` for this node will not be valid once `close` is called.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/documentEncoding.adoc[`documentEncoding`]  [.small]#[virtual]#
| Return the document encoding or NULL on error. The returned poiner is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Reader/dumpNode.adoc[`dumpNode`] 
| Print the information about the current node to the specified output `os` stream.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/errorInfo.adoc[`errorInfo`]  [.small]#[virtual]#
| Return a reference to the non‐modifiable error information for this reader. The returned value becomes invalid when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/getColumnNumber.adoc[`getColumnNumber`]  [.small]#[virtual]#
| Return the current column number within the input stream. The current column number is the number of characters since the last newline was read by the reader plus one, i.e., the first column of each line is column number one. Return 0 if not available. Note that a derived‐class implementation is not required to count columns and may just return 0.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/getLineNumber.adoc[`getLineNumber`]  [.small]#[virtual]#
| Return the current line number within the input stream. The current line is the last line for which the reader has not yet seen a newline. Lines are counted starting at one from the time a stream is provided to `open`. Return 0 if not available. Note that a derived‐class implementation is not required to count lines and may just return 0.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/isEmptyElement.adoc[`isEmptyElement`]  [.small]#[virtual]#
| Return true if the current node is an element (i.e., node type is `BAEXML_NODE_TYPE_ELEMENT`) that ends with `/>`; and false otherwise. Note that  will be considered empty but  will not.
| xref:BloombergLP/balxml/Reader/isError.adoc[`isError`] 
| Return `true` if the derived object encountered a error. This method is equivalent to a call to `errorInfo().isError();`
| xref:BloombergLP/balxml/Reader/isFatalError.adoc[`isFatalError`] 
| Return `true` if the derived object encountered a fatal error. This method is equivalent to a call to `errorInfo().isFatalError();`
| xref:BloombergLP/balxml/Utf8ReaderWrapper/isOpen.adoc[`isOpen`]  [.small]#[virtual]#
| Return true if `open` was called successfully and `close` has not yet been called and false otherwise.
| xref:BloombergLP/balxml/Reader/isWarning.adoc[`isWarning`] 
| Return `true` if the derived object encountered a warning. This method is equivalent to a call to `errorInfo().isWarning();`
| xref:BloombergLP/balxml/Utf8ReaderWrapper/lookupAttribute-05.adoc[`lookupAttribute`] 
| `lookupAttribute` overloads
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeBaseUri.adoc[`nodeBaseUri`]  [.small]#[virtual]#
| Return the base URI name of the current node if the current node has a base URI and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeDepth.adoc[`nodeDepth`]  [.small]#[virtual]#
| Return the nesting depth of the current node in the XML document. The root node has depth 0.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeHasValue.adoc[`nodeHasValue`]  [.small]#[virtual]#
| Return true if the current node has a value and false otherwise.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeLocalName.adoc[`nodeLocalName`]  [.small]#[virtual]#
| Return the local name of the current node if the current node has a local name and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeName.adoc[`nodeName`]  [.small]#[virtual]#
| Return the qualified name of the current node if the current node has a name and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeNamespaceId.adoc[`nodeNamespaceId`]  [.small]#[virtual]#
| Return the namespace ID of the current node if the current node has a namespace id and a negative number otherwise.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeNamespaceUri.adoc[`nodeNamespaceUri`]  [.small]#[virtual]#
| Return the namespace URI name of the current node if the current node has a namespace URI and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodePrefix.adoc[`nodePrefix`]  [.small]#[virtual]#
| Return the prefix name of the current node if the correct node has a prefix name and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeType.adoc[`nodeType`]  [.small]#[virtual]#
| Return the node type of the current node if the reader `isOpen` and has not encounter an error and `Reader::NONE` otherwise.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/nodeValue.adoc[`nodeValue`]  [.small]#[virtual]#
| Return the value of the current node if the current node has a value and NULL otherwise. The returned pointer is owned by this object and must not be modified or deallocated by the caller. The returned pointer becomes invalid upon the next `advanceToNextNode`, when `close` is called or the reader is destroyed.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/numAttributes.adoc[`numAttributes`]  [.small]#[virtual]#
| Return the number of attributes for the current node if that node has attributes and 0 otherwise.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/open-0f.adoc[`open`] 
| `open` overloads
| xref:BloombergLP/balxml/Utf8ReaderWrapper/options.adoc[`options`]  [.small]#[virtual]#
| Return the option flags.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/prefixStack.adoc[`prefixStack`]  [.small]#[virtual]#
| Return a pointer to the modifiable prefix stack that is used by this reader to manage namespace prefixes or 0 if namespace support is disabled. The behavior is undefined if the returned prefix stack is augmented in any way after calling `open` and before calling `close`.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/resolver.adoc[`resolver`]  [.small]#[virtual]#
| Return the external XML resource resolver.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/setOptions.adoc[`setOptions`]  [.small]#[virtual]#
| Set the options of the held reader to the flags in the specified `flags`. The options for the reader are persistent, i.e., the options are not reset by `close`. The behavior is undefined if this method is called after calling `open` and before calling `close`; except that derived classes are permitted to specify valid behavior for calling this function for specific arguments while the reader is open.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/setPrefixStack.adoc[`setPrefixStack`]  [.small]#[virtual]#
| Set the prefix stack to the stack at the optionally specified `prefixes` address or disable prefix stack support if `prefixes` is null. This stack is used to push and pop namespace prefixes as the parse progresses, so that, at any point, the stack will reflect the set of active prefixes for the current node. It is legitimate to pass a stack that already contains prefixes, these prefixes shall be preserved when `close` is called, i.e., the prefix stack shall be returned to the stack depth it had when `setPrefixStack` was called. The behavior is undefined if this method is called after calling `open` and before calling `close`.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/setResolver.adoc[`setResolver`]  [.small]#[virtual]#
| Set the external XML resource resolver to the specified `resolver`. The XML resource resolver is used by the `balxml_reader` to find and open an external resources (See the `XmlResolverFunctor` typedef for more details). The XML resource resolver remains valid; it is not affected by a call to `close` and should be available until the reader is destroyed. The behavior is undefined if this method is called after calling `open` and before calling `close`.
| xref:BloombergLP/balxml/Utf8ReaderWrapper/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Utf8ReaderWrapper, UsesBslmaAllocator>`] 
| `Utf8ReaderWrapper` uses a `bslma` allocator.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Reader/nodeTypeAsString.adoc[`nodeTypeAsString`] 
| Return a string representation for the specified `nodeType` code or "(* UNKNOWN NODE TYPE *)" if nodeType is not one of the values enumerated in `NodeType`.
|===



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