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

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;

== Synopsis

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

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

== Description

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 specified `value` to the currently open element&period; `value` can be of the following types&colon; `char`, `short`, `int`, `bsls&colon;&colon;Types&colon;&colon;Int64`, `float`, `double`, `bsl&colon;&colon;string`, `bdlt&colon;&colon;Datetime`, `bdlt&colon;&colon;Date`, and `bdlt&colon;&colon;Time`&period; Precede this name&equals;&quot;value&quot; pair with a single space&period; Wrap line (write the attribute on next line with proper indentation), if the length of name&equals;&quot;value&quot; is too long&period; Optionally specify a `formattingMode` used to control the formatting of the `value`&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, the presence of invalid input stops the transfer of data to the output specified on construction (see &lcub;Valid Strings&rcub;)&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, any special characters in `value` are escaped (see &lcub;Special Characters&rcub;)&period; If `value` is of type `char`, it is cast to a signed byte value with a range `&lsqb; &hyphen;128 &period;&period; 127 &rsqb;`&period; The behavior is undefined unless the last manipulator was `openElement` or `addAttribute`&period;
| xref:BloombergLP/balxml/Formatter/addBlankLine.adoc[`addBlankLine`] 
| Insert one or two newline characters into the output stream such that a blank line results&period; If the last output was a newline, then only one newline is added, otherwise two newlines are added&period; If following a call to `openElement`, or `addAttribute`, add a closing `&gt;` to the opened tag&period;
| xref:BloombergLP/balxml/Formatter/addComment.adoc[`addComment`] 
| Write the specified `comment` into the stream&period; The optionally specified `forceNewline`, if true, forces to start a new line solely for the comment if it&apos;s not on a new line already&period; Otherwise, comments continue on current line&period; If an element&hyphen;opening tag is not completed with a `&gt;`, `addComment` will add `&gt;`&period;
| xref:BloombergLP/balxml/Formatter/addData.adoc[`addData`] 
| Add the specified `value` as the data content, where `value` can be of the following types&colon; `char`, `short`, `int`, `bsls&colon;&colon;Types&colon;&colon;Int64`, `float`, `double`, `bsl&colon;&colon;string`, `bdlt&colon;&colon;Datetime`, `bdlt&colon;&colon;Date`, and `bdlt&colon;&colon;Time`&period; Perform no line&hyphen;wrapping or indentation as if the whitespace constraint were always `BAEXML&lowbar;PRESERVE&lowbar;WHITESPACE` in `openElement`, with the only exception that an initial newline and an initial indent is added when `openElement` specifies `BAEXML&lowbar;NEWLINE&lowbar;INDENT` option&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, the presence of invalid input stops the transfer of data to the output specified on construction (see &lcub;Valid Strings&rcub;)&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, characters in `value` are escaped (see &lcub;Special Characters&rcub;)&period; If `value` is of type `char`, it is cast to a signed byte value with a range of `&lsqb; &hyphen;128 &period;&period; 127 &rsqb;`&period; Optionally specify the `formattingMode` to specify the format used to encode `value`&period; The behavior is undefined if the call is made when there are no opened elements&period;
| xref:BloombergLP/balxml/Formatter/addElementAndData.adoc[`addElementAndData`] 
| Add element of the specified `name` and the specified `value` as the data content&period; This has the same effect as calling the following sequence&colon; `openElement(name)&semi; addData(value), closeElement(name)&semi;`&period; Optionally specify the `formattingMode`&period;
| xref:BloombergLP/balxml/Formatter/addHeader.adoc[`addHeader`] 
| Add XML header with optionally specified `encoding`&period; Version is always &quot;1&period;0&quot;&period; The behavior is undefined unless `addHeader` is the first manipulator (with the exception of `rawOutputStream`) after construction or `reset`&period;
| xref:BloombergLP/balxml/Formatter/addListData.adoc[`addListData`] 
| Add the specified `value` as the data content, where `value` can be of the following types&colon; `char`, `short`, `int`, `bsls&colon;&colon;Types&colon;&colon;Int64`, `float`, `double`, `bsl&colon;&colon;string`, `bdlt&colon;&colon;Datetime`, `bdlt&colon;&colon;Date`, and `bdlt&colon;&colon;Time`&period; Prefix the `value` with a space(`0x20`) unless the data being added is the first data on a line&period; When adding the data makes the line too long, perform line&hyphen;wrapping and indentation as determined by the whitespace constraint used when the current element is opened with `openElement`&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, the presence of invalid input stops the transfer of data to the output specified on construction (see &lcub;Valid Strings&rcub;)&period; If `value` is of type `bsl&colon;&colon;string` or convertible to `bsl&colon;&colon;string&lowbar;view`, any special characters in `value` are escaped (see &lcub;Special Characters&rcub;)&period; If `value` is of type `char`, it is cast to a signed byte value with a range of `&lsqb; &hyphen;128 &period;&period; 127 &rsqb;`&period; Optionally specify the `formattingMode` to specify the format used to encode `value`&period; The behavior is undefined if the call is made when there are no opened elements&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; Optionally specify `forceNewline` that specifies if a new line should be added before the comment if it is not already on a new line&period; If `forceNewline` is not specified then a new line is inserted for comments not already on a new line&period; Also optionally specify an `omitEnclosingWhitespace` that specifies if a space character should be omitted before and after `comment`&period; If `omitEnclosingWhitespace` is not specified then a space character is inserted before and after `comment`&period; Return 0 on success, and non&hyphen;zero value otherwise&period; Note that a non&hyphen;zero return value is returned if either `comment` contains `&hyphen;&hyphen;` or if `omitEnclosingWhitespace` is `true` and `comment` ends with `&hyphen;`&period; Also note that if an element&hyphen;opening tag is not completed with a `&gt;`, `addValidComment` will add `&gt;`&period;
| xref:BloombergLP/balxml/Formatter/closeElement.adoc[`closeElement`] 
| Decrement the indent level and add the closing tag for the element of the specified `name`&period; If the element does not have content, write `&sol;&gt;` and a newline into stream&period; Otherwise, write `&lt;&sol;name&gt;` and a newline&period; If this `&lt;&sol;name&gt;` does not share the same line with data, or it follows another element&apos;s closing tag, indent properly before writing `&lt;&sol;name&gt;` and the newline&period; If `name` is root element, flush the output stream&period; The behavior is undefined if `name` is not the most recently opened element that&apos;s yet to be closed&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` at current indent level with the optionally specified whitespace constraint `whitespaceMode` for its textual data and increment indent level&period; `whitespaceMode` constrains how textual data is written with `addListData` for the current element, but not its nested elements&period; The behavior is undefined if `openElement` is called after the root element is closed and there is no subsequent call to `reset`&period;
| xref:BloombergLP/balxml/Formatter/outputColumn.adoc[`outputColumn`] 
| Return the current column position at a line where next output starts&period; This is unreliable if called after free&hyphen;lance information is written onto the stream returned by `rawOutputStream`
| xref:BloombergLP/balxml/Formatter/rawOutputStream.adoc[`rawOutputStream`] 
| Return a reference to the underlining output stream&period; This method is provided in order to enable user to temporarily jump out of the formatter and write user&apos;s own free&hyphen;lance content directly to the 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]#
