Package de.gebit.integrity.string

## Class FormattedString

- java.lang.Object
- - de.gebit.integrity.string.FormattedString

-     public class FormattedString
      extends Object

  Represents a String with formatting instructions. Each formatted string consists of a number of `AbstractFormattedStringElement`s and can be transformed in a standard `String` either with or without the formatting instructions. If formatting info is included in that `String`, this is done by adding the "[FORMATTED]" at the start of the string to inform any reader that there are formatting tokens to be found. These formatting tokens start with '[', followed by a token name, followed optionally by '|' plus a replacement string value (to be inserted into the string instead of the token if the formatting info is to be stripped from the string instead of being interpreted), and finally closed by ']'.

  Note that other than the standard `String`, this "formatted string" is a mutable object, hence it behaves more like a `StringBuilder` in practice!

  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected List<AbstractFormattedStringElement>` | `elements` | Contains the elements that the formatted string consists of.
    `static String` | `FORMATTED_STRING_START_TOKEN` | This token starts a formatted string.
    `protected String` | `formattedValueCache` | The formatted serialized value of this formatted string.
    `protected String` | `unformattedValueCache` | The unformatted serialized value of this formatted string.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FormattedString()` | Creates a new, empty formatted string.
    `FormattedString​(AbstractFormattedStringElement... someElements)` | Creates a new formatted string with the supplied elements.
    `FormattedString​(String aText)` | Creates a new formatted string with one plaintext element.
    `FormattedString​(String aText, FormattedStringElement.FormatFlag... someFlags)` | Creates a new formatted string with one text element, to which the provided format flags are added.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(AbstractFormattedStringElement anElement)` | Adds the element to the formatted string.
    `void` | `add​(AbstractFormattedStringElement... someElements)` | Adds the provided elements to the formatted string.
    `void` | `add​(FormattedString aFormattedString)` | Adds all elements of the provided formatted string to this formatted string.
    `void` | `add​(String aString)` | Adds a plaintext element without formatting flags to the formatted string.
    `void` | `add​(String... someStrings)` | Adds multiple plaintext elements without formatting flags to the formatted string.
    `void` | `add​(String aString, FormattedStringElement.FormatFlag... someFlags)` | Adds a text element with the provided formatting flags to the formatted string.
    `void` | `addMultiple​(AbstractFormattedStringElement anElement, int aNumber)` | Adds the provided element multiple times to the formatted string.
    `protected void` | `clearCache()` | Clears any cached serialized `String` values.
    `boolean` | `equals​(Object anOtherObject)` |
    `int` | `getElementCount()` |
    `int` | `hashCode()` |
    `String` | `toFormattedString()` | Serializes the formatted string elements into a single string with formatting tags embedded.
    `String` | `toFormattedStringLengthLimited​(int aMaxLength)` | Serializes the formatted string elements into a single string with formatting tags embedded, but only if the resulting string is below a certain length.
    `String` | `toString()` |
    `String` | `toUnformattedString()` | Serializes the formatted string elements into a single string without any formatting tags.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FORMATTED_STRING_START_TOKEN

          public static final String FORMATTED_STRING_START_TOKEN

      This token starts a formatted string.
      See Also:
        Constant Field Values

    - #### elements

          protected List<AbstractFormattedStringElement> elements

      Contains the elements that the formatted string consists of.

    - #### unformattedValueCache

          protected String unformattedValueCache

      The unformatted serialized value of this formatted string. Used for caching purposes.

    - #### formattedValueCache

          protected String formattedValueCache

      The formatted serialized value of this formatted string. Used for caching purposes.

  - ### Constructor Detail

    - #### FormattedString

          public FormattedString()

      Creates a new, empty formatted string.

    - #### FormattedString

          public FormattedString​(String aText)

      Creates a new formatted string with one plaintext element.
      Parameters:
        `aText` - the new string content

    - #### FormattedString

          public FormattedString​(String aText,
                                 FormattedStringElement.FormatFlag... someFlags)

      Creates a new formatted string with one text element, to which the provided format flags are added.
      Parameters:
        `aText` - the new string content
        `someFlags` - the format flags to apply to the string content

    - #### FormattedString

          public FormattedString​(AbstractFormattedStringElement... someElements)

      Creates a new formatted string with the supplied elements.
      Parameters:
        `someElements` - the elements to add to the string

  - ### Method Detail

    - #### add

          public void add​(AbstractFormattedStringElement anElement)

      Adds the element to the formatted string. Elements are always added at the end.
      Parameters:
        `anElement` - the element to be added

    - #### addMultiple

          public void addMultiple​(AbstractFormattedStringElement anElement,
                                  int aNumber)

      Adds the provided element multiple times to the formatted string. The element is NOT cloned, but the same instance is added multiple times.
      Parameters:
        `anElement` - the element to be added
        `aNumber` - the number of times that the element is to be added

    - #### add

          public void add​(String aString)

      Adds a plaintext element without formatting flags to the formatted string.
      Parameters:
        `aString` - the text for the plaintext element

    - #### add

          public void add​(String aString,
                          FormattedStringElement.FormatFlag... someFlags)

      Adds a text element with the provided formatting flags to the formatted string.
      Parameters:
        `aString` - the text for the element
        `someFlags` - the formatting flags to apply

    - #### add

          public void add​(AbstractFormattedStringElement... someElements)

      Adds the provided elements to the formatted string.
      Parameters:
        `someElements` - the elements to add

    - #### add

          public void add​(FormattedString aFormattedString)

      Adds all elements of the provided formatted string to this formatted string.
      Parameters:
        `aFormattedString` - the formatted string whose elements are to be added

    - #### add

          public void add​(String... someStrings)

      Adds multiple plaintext elements without formatting flags to the formatted string.
      Parameters:
        `someStrings` - the strings to add as plaintext elements

    - #### clearCache

          protected void clearCache()

      Clears any cached serialized `String` values.

    - #### toFormattedString

          public String toFormattedString()

      Serializes the formatted string elements into a single string with formatting tags embedded.
      Returns:
        the string with formatting tags

    - #### toFormattedStringLengthLimited

          public String toFormattedStringLengthLimited​(int aMaxLength)

      Serializes the formatted string elements into a single string with formatting tags embedded, but only if the resulting string is below a certain length. If it exceeds this length, an unformatted string is returned.
      Parameters:
        `aMaxLength` - the maximum length in Unicode code units.
      Returns:
        either a formatted or unformatted string

    - #### toUnformattedString

          public String toUnformattedString()

      Serializes the formatted string elements into a single string without any formatting tags.
      Returns:
        the string without formatting tags

    - #### getElementCount

          public int getElementCount()

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals​(Object anOtherObject)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`