[#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&period;

== Synopsis

Declared in `&lt;balxml&lowbar;formatter&period;h&gt;`

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

== Description

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

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

== 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&period;
|===


== 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&period;
| xref:BloombergLP/balxml/Formatter/addBlankLine.adoc[`addBlankLine`] 
| Insert newline characters into the output stream such that a blank line results&period;
| xref:BloombergLP/balxml/Formatter/addComment.adoc[`addComment`] 
| Write the specified `comment` into the stream&period;
| xref:BloombergLP/balxml/Formatter/addData.adoc[`addData`] 
| Add the specified `value` as the data content of the current element&period;
| xref:BloombergLP/balxml/Formatter/addElementAndData.adoc[`addElementAndData`] 
| Add an element of the specified `name` containing the specified `value`&period;
| xref:BloombergLP/balxml/Formatter/addHeader.adoc[`addHeader`] 
| Add an XML declaration header with the optionally specified `encoding`&period;
| xref:BloombergLP/balxml/Formatter/addListData.adoc[`addListData`] 
| Add the specified `value` as space&hyphen;separated list data content&period;
| xref:BloombergLP/balxml/Formatter/addNewline.adoc[`addNewline`] 
| Insert a literal newline into the XML output&period; If following a call to `openElement`, or `addAttribute`, add a closing `&gt;` to the opened tag&period;
| xref:BloombergLP/balxml/Formatter/addValidComment.adoc[`addValidComment`] 
| Write the specified `comment` into the stream&period;
| xref:BloombergLP/balxml/Formatter/closeElement.adoc[`closeElement`] 
| Close the most recently opened element of the specified `name`&period;
| xref:BloombergLP/balxml/Formatter/encoderOptions.adoc[`encoderOptions`] 
| Return the encoder options being used&period;
| xref:BloombergLP/balxml/Formatter/flush.adoc[`flush`] 
| Insert the closing `&gt;` if there is an incomplete tag, and flush the output stream&period;
| xref:BloombergLP/balxml/Formatter/indentLevel.adoc[`indentLevel`] 
| Return the current level of indentation&period;
| xref:BloombergLP/balxml/Formatter/openElement.adoc[`openElement`] 
| Open an element of the specified `name`&period;
| xref:BloombergLP/balxml/Formatter/outputColumn.adoc[`outputColumn`] 
| Return the current column position where the next output starts&period;
| xref:BloombergLP/balxml/Formatter/rawOutputStream.adoc[`rawOutputStream`] 
| Return a reference to the underlying output stream&period;
| 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&period;
| 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&period;
| xref:BloombergLP/balxml/Formatter/wrapColumn.adoc[`wrapColumn`] 
| Return the line width where line&hyphen;wrapping takes place&period;
|===


== Static Data Members

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



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