Escapers.Builder
Date: 2016-05-24

com.google.common.escape

## Class Escapers.Builder

- java.lang.Object
- - com.google.common.escape.Escapers.Builder

- Enclosing class:
    Escapers

      @Beta
      public static final class Escapers.Builder
      extends java.lang.Object

  A builder for simple, fast escapers.

  Typically an escaper needs to deal with the escaping of high valued characters or code points. In these cases it is necessary to extend either `ArrayBasedCharEscaper` or `ArrayBasedUnicodeEscaper` to provide the desired behavior. However this builder is suitable for creating escapers that replace a relative small set of characters.

  Since:
    15.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Escapers.Builder` | `addEscape(char c, java.lang.String replacement)` Adds a replacement string for the given input character.
    `Escaper` | `build()` Returns a new escaper based on the current state of the builder.
    `Escapers.Builder` | `setSafeRange(char safeMin, char safeMax)` Sets the safe range of characters for the escaper.
    `Escapers.Builder` | `setUnsafeReplacement(java.lang.String unsafeReplacement)` Sets the replacement string for any characters outside the 'safe' range that have no explicit replacement.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### setSafeRange

          public Escapers.Builder setSafeRange(char safeMin,
                                      char safeMax)

      Sets the safe range of characters for the escaper. Characters in this range that have no explicit replacement are considered 'safe' and remain unescaped in the output. If `safeMax < safeMin` then the safe range is empty.
      Parameters:
        `safeMin` - the lowest 'safe' character
        `safeMax` - the highest 'safe' character
      Returns:
        the builder instance

    - #### setUnsafeReplacement

          public Escapers.Builder setUnsafeReplacement(@Nullable
                                              java.lang.String unsafeReplacement)

      Sets the replacement string for any characters outside the 'safe' range that have no explicit replacement. If `unsafeReplacement` is `null` then no replacement will occur, if it is `""` then the unsafe characters are removed from the output.
      Parameters:
        `unsafeReplacement` - the string to replace unsafe chracters
      Returns:
        the builder instance

    - #### addEscape

          public Escapers.Builder addEscape(char c,
                                   java.lang.String replacement)

      Adds a replacement string for the given input character. The specified character will be replaced by the given string whenever it occurs in the input, irrespective of whether it lies inside or outside the 'safe' range.
      Parameters:
        `c` - the character to be replaced
        `replacement` - the string to replace the given character
      Returns:
        the builder instance
      Throws:
        `java.lang.NullPointerException` - if `replacement` is null

    - #### build

          public Escaper build()

      Returns a new escaper based on the current state of the builder.