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

This utility `struct` provides a namespace for a suite of operations used to pretty‐print XML documents given a sequence of tokens to emit. Together with `Formatter_CompactImplState`, this `struct` provides an implementation of a state machine for such pretty‐printing.

== Synopsis

Declared in `<balxml_formatter_compactimpl.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct Formatter_CompactImplUtil;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/State.adoc[`State`] 
| State type used by compact‐formatter utilities.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/StateId.adoc[`StateId`] 
| State‐id type used by compact‐formatter utilities.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/WhitespaceType.adoc[`WhitespaceType`] 
| Alias for `FormatterWhitespaceType`.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. `value` can be of the following types: `char`, `short`, `int`, `bsls::Types::Int64`, `float`, `double`, `bsl::string`, `bdlt::Datetime`, `bdlt::Date`, and `bdlt::Time`. Precede this name="value" pair with a single space. Wrap line (write the attribute on next line with proper indentation), if the length of name="value" is too long. Optionally specify a `valueFormattingMode` and `encoderOptions` to control the formatting of `value`. If `value` is of type `bsl::string`, it is truncated at any invalid UTF‐8 byte‐sequence or any control character. The list of invalid control characters includes characters in the range `[0x00, 0x20)]` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If `value` is of type `char`, it is cast to a signed byte value with a range `[ ‐128 .. 127 ]`. The behavior is undefined unless the last manipulator was `openElement` or `addAttribute`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. If the last output was a newline, then only one newline is added, otherwise two newlines are added. If following a call to `openElement`, or `addAttribute`, add a closing `>` to the opened tag.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/addComment.adoc[`addComment`] 
| Write the specified `comment` into the specified `stream`, with formatting depending on the specified `state`, and update the `state` accordingly. Return the `stream`. The optionally specified `forceNewline`, if true, forces to start a new line solely for the comment if it's not on a new line already. Otherwise, comments continue on current line. If an element‐opening tag is not completed with a `>`, `addComment` will add `>`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. `value` can be of the following types: `char`, `short`, `int`, `bsls::Types::Int64`, `float`, `double`, `bsl::string`, `bdlt::Datetime`, `bdlt::Date`, and `bdlt::Time`. Perform no line‐wrapping or indentation as if the whitespace constraint were always `BAEXML_PRESERVE_WHITESPACE` in `openElement`, with the only exception that an initial newline and an initial indent is added when `openElement` specifies `BAEXML_NEWLINE_INDENT` option. If `value` is of type `bsl::string`, it is truncated at any invalid UTF‐8 byte‐sequence or any control character. The list of invalid control characters includes characters in the range `[0x00, 0x20)]` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If `value` is of type `char`, it is cast to a signed byte value with a range of '[ ‐128 ..] 127 ]`. Optionally specify the `formattingMode' and `encoderOptions` to specify the format used to encode `value`. The behavior is undefined if the call is made when there are no opened elements.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. This has the same effect as calling the following sequence: 'openElement(name); addData(value), closeElement(name);'. Optionally specify the `formattingMode`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. Version is always "1.0". The behavior is undefined unless `addHeader` is the first manipulator (with the exception of `rawOutputStream`) after construction or `reset`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. `value` can be of the following types: `char`, `short`, `int`, `bsls::Types::Int64`, `float`, `double`, `bsl::string`, `bdlt::Datetime`, `bdlt::Date`, and `bdlt::Time`. Prefix the `value` with a space(`0x20`) unless the data being added is the first data on a line. When adding the data makes the line too long, perform line‐wrapping and indentation as determined by the whitespace constraint used when the current element is opened with `openElement`. If `value` is of type `bsl::string`, it is truncated at any invalid UTF‐8 byte‐sequence or any control character. The list of invalid control characters includes characters in the range `[0x00, 0x20)]` and `0x7F` (DEL) but does not include `0x9`, `0xA`, and `0x0D`. The five special characters: apostrophe, double quote, ampersand, less than, and greater than are escaped in the output XML. If `value` is of type `char`, it is cast to a signed byte value with a range of '[ ‐128 ..] 127 ]`. Optionally specify the `formattingMode' and `encoderOptions` to specify the format used to encode `value`. The behavior is undefined if the call is made when there are no opened elements.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. If following a call to `openElement`, or `addAttribute`, add a closing `>` to the opened tag.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/addValidComment.adoc[`addValidComment`] 
| Write the specified `comment` into the specified `stream`, with formatting depending on the specified `state`, and update the `state` accordingly. If the optionally specified `forceNewline` is `true` then a new line is inserted for comments not already on a new line. Also optionally specify an `omitEnclosingWhitespace` that specifies if a space character should be omitted before and after `comment`. If `omitEnclosingWhitespace` is not specified then a space character is inserted before and after `comment`. Return 0 on success, and non‐zero value otherwise. Note that a non‐zero return value is returned if either `comment` contains `‐‐` or if `omitEnclosingWhitespace` is `true` and `comment` ends with `‐`. Also note that if an element‐opening tag is not completed with a `>`, `addValidComment` will add `>`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. If the element does not have content, write `/>` and a newline into stream. Otherwise, write `</name>` and a newline. If this `</name>` does not share the same line with data, or it follows another element's closing tag, indent properly before writing `</name>` and the newline. If `name` is root element, flush the output stream. The behavior is undefined if `name` is not the most recently opened element that's yet to be closed.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/flush.adoc[`flush`] 
| Insert the closing `>` if there is an incomplete tag, and flush the specified output `stream`, with formatting depending on the specified `state`, and update `state` accordingly. Return the `stream`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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. Return the `stream`. `whitespaceMode` constrains how textual data is written with `addListData` for the current element, but not its nested elements. The behavior is undefined if `openElement` is called after the root element is closed and there is no subsequent call to `reset`.
| xref:BloombergLP/balxml/Formatter_CompactImplUtil/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]#