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

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.

== Synopsis

Declared in `<balxml_formatter.h>`

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

== Description

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 specified `value` to the currently open element. `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 `formattingMode` used to control the formatting of the `value`. If `value` is of type `bsl::string` or convertible to `bsl::string_view`, the presence of invalid input stops the transfer of data to the output specified on construction (see {Valid Strings}). If `value` is of type `bsl::string` or convertible to `bsl::string_view`, any special characters in `value` are escaped (see {Special Characters}). 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/addBlankLine.adoc[`addBlankLine`] 
| Insert one or two newline characters into the output stream such that a blank line results. 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/addComment.adoc[`addComment`] 
| Write the specified `comment` into 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/addData.adoc[`addData`] 
| Add the specified `value` as the data content, where `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` or convertible to `bsl::string_view`, the presence of invalid input stops the transfer of data to the output specified on construction (see {Valid Strings}). If `value` is of type `bsl::string` or convertible to `bsl::string_view`, characters in `value` are escaped (see {Special Characters}). If `value` is of type `char`, it is cast to a signed byte value with a range of `[ ‐128 .. 127 ]`. Optionally specify the `formattingMode` 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/addElementAndData.adoc[`addElementAndData`] 
| Add element of the specified `name` and the specified `value` as the data content. This has the same effect as calling the following sequence: `openElement(name); addData(value), closeElement(name);`. Optionally specify the `formattingMode`.
| xref:BloombergLP/balxml/Formatter/addHeader.adoc[`addHeader`] 
| Add XML header with optionally specified `encoding`. 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/addListData.adoc[`addListData`] 
| Add the specified `value` as the data content, where `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` or convertible to `bsl::string_view`, the presence of invalid input stops the transfer of data to the output specified on construction (see {Valid Strings}). If `value` is of type `bsl::string` or convertible to `bsl::string_view`, any special characters in `value` are escaped (see {Special Characters}). If `value` is of type `char`, it is cast to a signed byte value with a range of `[ ‐128 .. 127 ]`. Optionally specify the `formattingMode` 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/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. Optionally specify `forceNewline` that specifies if a new line should be added before the comment if it is not already on a new line. If `forceNewline` is not specified 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/closeElement.adoc[`closeElement`] 
| Decrement the indent level and add the closing tag for the element of the specified `name`. 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/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` at current indent level with the optionally specified whitespace constraint `whitespaceMode` for its textual data and increment indent level. `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/outputColumn.adoc[`outputColumn`] 
| Return the current column position at a line where next output starts. This is unreliable if called after free‐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. This method is provided in order to enable user to temporarily jump out of the formatter and write user's own free‐lance content directly to the 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]#