[#BloombergLP-balxml-Formatter_PrettyImplUtil]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balxml.adoc[balxml]::Formatter&lowbar;PrettyImplUtil
:relfileprefix: ../../
:mrdocs:

This utility `struct` provides a namespace for a suite of operations used to pretty&hyphen;print XML documents given a sequence of tokens to emit&period; Together with `Formatter&lowbar;PrettyImplState`, this `struct` provides an implementation of a state machine for such pretty&hyphen;printing&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct Formatter&lowbar;PrettyImplUtil;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/State.adoc[`State`] 
| State type used by pretty&hyphen;formatter utilities&period;
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/StateId.adoc[`StateId`] 
| State&hyphen;id type used by pretty&hyphen;formatter utilities&period;
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/WhitespaceType.adoc[`WhitespaceType`] 
| Alias for `FormatterWhitespaceType`&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/addAttribute.adoc[`addAttribute`] 
| Add an attribute of the specified `name` and specified `value` to the currently open element in the specified `stream`, with formatting depending on the specified `state`, and update the `state` accordingly&period; Return the `stream`&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 `formattingMode` and `encoderOptions` to control the formatting of `value`&period; If `value` is of type `bsl&colon;&colon;string`, it is truncated at any invalid UTF&hyphen;8 byte&hyphen;sequence or any control character&period; The list of invalid control characters includes characters in the range `&lsqb;0x00, 0x20)&rsqb;` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`&period; The five special characters&colon; apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML&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_PrettyImplUtil/addBlankLine.adoc[`addBlankLine`] 
| Insert one or two newline characters into the specified `stream` stream such that a blank line results, depending on the specified `state`, and update the `state` accordingly&period; Return the `stream`&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_PrettyImplUtil/addComment.adoc[`addComment`] 
| Write the specified `comment` into the specified `stream`, with formatting depending on the specified `state`, and update the `state` accordingly&period; Return 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_PrettyImplUtil/addData.adoc[`addData`] 
| Add the specified `value` as the data content to the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&period; Return the `stream`&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; 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`, it is truncated at any invalid UTF&hyphen;8 byte&hyphen;sequence or any control character&period; The list of invalid control characters includes characters in the range `&lsqb;0x00, 0x20)&rsqb;` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`&period; The five special characters&colon; apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML&period; If `value` is of type `char`, it is cast to a signed byte value with a range of &apos;&lsqb;&rsqb; &hyphen;128 &period;&period; 127 &rsqb;`&period; Optionally specify the `formattingMode&apos; and `encoderOptions` 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_PrettyImplUtil/addElementAndData.adoc[`addElementAndData`] 
| Add element of the specified `name` and the specified `value` as the data content to the specified `stream`, with formatting depending on the specified `state` and the optionally specified `encoderOptions`, and update `state` accordingly&period; Return the `stream`&period; This has the same effect as calling the following sequence&colon; &apos;openElement(name)&semi; addData(value), closeElement(name)&semi;&apos;&period; Optionally specify the `formattingMode`&period;
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/addHeader.adoc[`addHeader`] 
| Add XML header with optionally specified `encoding` to the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&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_PrettyImplUtil/addListData.adoc[`addListData`] 
| Add the specified `value` as the data content to the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&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; 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`, it is truncated at any invalid UTF&hyphen;8 byte&hyphen;sequence or any control character&period; The list of invalid control characters includes characters in the range `&lsqb;0x00, 0x20)&rsqb;` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`&period; The five special characters&colon; apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML&period; If `value` is of type `char`, it is cast to a signed byte value with a range of &apos;&lsqb; &hyphen;128 &period;&period;&rsqb; 127 &rsqb;`&period; Optionally specify the `formattingMode&apos; and `encoderOptions` 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_PrettyImplUtil/addNewline.adoc[`addNewline`] 
| Insert a literal newline into the XML output of the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&period; If following a call to `openElement`, or `addAttribute`, add a closing `&gt;` to the opened tag&period;
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/addValidComment.adoc[`addValidComment`] 
| Write the specified `comment` into the specified `stream`, with formatting depending on the specified `state`, and update the `state` accordingly&period; If the optionally specified `forceNewline` is `true` 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_PrettyImplUtil/closeElement.adoc[`closeElement`] 
| Decrement the indent level and add the closing tag for the element of the specified `name` to the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&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_PrettyImplUtil/flush.adoc[`flush`] 
| Insert the closing `&gt;` if there is an incomplete tag, and flush the specified output `stream`, with formatting depending on the specified `state`, and update `state` accordingly&period; Return the `stream`&period;
| xref:BloombergLP/balxml/Formatter_PrettyImplUtil/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 to the specified `stream`, with formatting depending on the specified `state`, and update `state` accordingly, incrementing the indent level&period; Return the `stream`&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_PrettyImplUtil/reset.adoc[`reset`] 
| Reset the specified formatter `state` such that it can be used to format a new XML document as if the formatter were just constructed
|===



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