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

Format XML tags, attributes, and data with indentation and wrapping.

== Synopsis

Declared in `<balxml_formatter.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Formatter;
----

== Description

This class provides a set of XML‐style formatting utilities that enable transparent indentation and wrapping for users attempting to format data with XML tags and attributes. A formatter object is instantiated with a pointer to an output stream or streambuf. Users can then use the provided utilities to write element tags, attributes, data in a valid XML sequence into the underlying stream.

This class has no features that would impair thread safety. However, it does not mediate between two threads attempting to access the same stream.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter/WhitespaceType.adoc[`WhitespaceType`] 
| `WhitespaceType` describes options available when outputting textual data of an element between its pair of opening and closing tags.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter/2constructor-0a.adoc[`Formatter`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/balxml/Formatter/addAttribute.adoc[`addAttribute`] 
| Add an attribute of the specified `name` and `value` to the currently open element.
| xref:BloombergLP/balxml/Formatter/addBlankLine.adoc[`addBlankLine`] 
| Insert newline characters into the output stream such that a blank line results.
| xref:BloombergLP/balxml/Formatter/addComment.adoc[`addComment`] 
| Write the specified `comment` into the stream.
| xref:BloombergLP/balxml/Formatter/addData.adoc[`addData`] 
| Add the specified `value` as the data content of the current element.
| xref:BloombergLP/balxml/Formatter/addElementAndData.adoc[`addElementAndData`] 
| Add an element of the specified `name` containing the specified `value`.
| xref:BloombergLP/balxml/Formatter/addHeader.adoc[`addHeader`] 
| Add an XML declaration header with the optionally specified `encoding`.
| xref:BloombergLP/balxml/Formatter/addListData.adoc[`addListData`] 
| Add the specified `value` as space‐separated list data content.
| xref:BloombergLP/balxml/Formatter/addNewline.adoc[`addNewline`] 
| Insert a literal newline into the XML output. If following a call to `openElement`, or `addAttribute`, add a closing `>` to the opened tag.
| xref:BloombergLP/balxml/Formatter/addValidComment.adoc[`addValidComment`] 
| Write the specified `comment` into the stream.
| xref:BloombergLP/balxml/Formatter/closeElement.adoc[`closeElement`] 
| Close the most recently opened element of the specified `name`.
| xref:BloombergLP/balxml/Formatter/encoderOptions.adoc[`encoderOptions`] 
| Return the encoder options being used.
| xref:BloombergLP/balxml/Formatter/flush.adoc[`flush`] 
| Insert the closing `>` if there is an incomplete tag, and flush the output stream.
| xref:BloombergLP/balxml/Formatter/indentLevel.adoc[`indentLevel`] 
| Return the current level of indentation.
| xref:BloombergLP/balxml/Formatter/openElement.adoc[`openElement`] 
| Open an element of the specified `name`.
| xref:BloombergLP/balxml/Formatter/outputColumn.adoc[`outputColumn`] 
| Return the current column position where the next output starts.
| xref:BloombergLP/balxml/Formatter/rawOutputStream.adoc[`rawOutputStream`] 
| Return a reference to the underlying output stream.
| xref:BloombergLP/balxml/Formatter/reset.adoc[`reset`] 
| Reset the formatter such that it can be used to format a new XML document as if the formatter were just constructed
| xref:BloombergLP/balxml/Formatter/spacesPerLevel.adoc[`spacesPerLevel`] 
| Return the number of spaces per indentation level.
| xref:BloombergLP/balxml/Formatter/status.adoc[`status`] 
| Return 0 if no errors have been detected since construction or since the last call to `reset`, otherwise return a negative value.
| xref:BloombergLP/balxml/Formatter/wrapColumn.adoc[`wrapColumn`] 
| Return the line width where line‐wrapping takes place.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter/BAEXML_NEWLINE_INDENT.adoc[`BAEXML_NEWLINE_INDENT`] 
| Deprecated alias for `e_NEWLINE_INDENT`.
| xref:BloombergLP/balxml/Formatter/e_NEWLINE_INDENT.adoc[`e_NEWLINE_INDENT`] 
| In addition to wrapping and indentation, place tags and data on separate lines.
| xref:BloombergLP/balxml/Formatter/e_PRESERVE_WHITESPACE.adoc[`e_PRESERVE_WHITESPACE`] 
| Preserve whitespace in element text; data is output as‐is.
| xref:BloombergLP/balxml/Formatter/e_WORDWRAP.adoc[`e_WORDWRAP`] 
| Wrap long lines when output would otherwise exceed the wrap column.
| xref:BloombergLP/balxml/Formatter/e_WORDWRAP_INDENT.adoc[`e_WORDWRAP_INDENT`] 
| Wrap long lines and indent continuation lines after wrapping.
|===



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