com.google.gwt.safehtml.shared

## Class SafeHtmlUtils

- java.lang.Object
- - com.google.gwt.safehtml.shared.SafeHtmlUtils

-     public final class SafeHtmlUtils
      extends java.lang.Object

  Utility class containing static methods for escaping and sanitizing strings.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static SafeHtml` | `EMPTY_SAFE_HTML` An empty String.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SafeHtml` | `fromSafeConstant(java.lang.String s)` Returns a `SafeHtml` constructed from a safe string, i.e., without escaping the string.
    `static SafeHtml` | `fromString(java.lang.String s)` Returns a `SafeHtml` containing the escaped string.
    `static SafeHtml` | `fromTrustedString(java.lang.String s)` Returns a `SafeHtml` constructed from a trusted string, i.e., without escaping the string.
    `static java.lang.String` | `htmlEscape(char c)` HTML-escapes a character.
    `static java.lang.String` | `htmlEscape(java.lang.String s)` HTML-escapes a string.
    `static java.lang.String` | `htmlEscapeAllowEntities(java.lang.String text)` HTML-escapes a string, but does not double-escape HTML-entities already present in the string.

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

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

- - ### Field Detail

    - #### EMPTY_SAFE_HTML

          public static final SafeHtml EMPTY_SAFE_HTML

      An empty String.

  - ### Method Detail

    - #### fromSafeConstant

          public static SafeHtml fromSafeConstant(java.lang.String s)

      Returns a `SafeHtml` constructed from a safe string, i.e., without escaping the string.

      Important: For this method to be able to honor the `SafeHtml` contract, all uses of this method must satisfy the following constraints:

      1. The argument expression must be fully determined at compile time.
      2. The value of the argument must end in "inner HTML" context and not contain incomplete HTML tags. I.e., the following is not a correct use of this method, because the `<a>` tag is incomplete:

              shb.appendHtmlConstant("<a href='").append(url)

      The first constraint provides a sufficient condition that the argument (and any HTML markup contained in it) originates from a trusted source. The second constraint ensures the composability of `SafeHtml` values.

      When executing client-side in Development Mode, or server-side with assertions enabled, the argument is HTML-parsed and validated to satisfy the second constraint (the server-side check can also be enabled programmatically, see `SafeHtmlHostedModeUtils.maybeCheckCompleteHtml(String)` for details). For performance reasons, this check is not performed in Production Mode on the client, and with assertions disabled on the server.

      Parameters:
        `s` - the string to be wrapped as a `SafeHtml`
      Returns:
        `s`, wrapped as a `SafeHtml`
      Throws:
        `java.lang.IllegalArgumentException` - if not running in Production Mode and `html` violates the second constraint

    - #### fromString

          public static SafeHtml fromString(java.lang.String s)

      Returns a `SafeHtml` containing the escaped string.
      Parameters:
        `s` - the input String
      Returns:
        a `SafeHtml` instance

    - #### fromTrustedString

          public static SafeHtml fromTrustedString(java.lang.String s)

      Returns a `SafeHtml` constructed from a trusted string, i.e., without escaping the string. No checks are performed. The calling code should be carefully reviewed to ensure the argument meets the `SafeHtml` contract.
      Parameters:
        `s` - the input String
      Returns:
        a `SafeHtml` instance

    - #### htmlEscape

          public static java.lang.String htmlEscape(char c)

      HTML-escapes a character. HTML meta characters will be escaped as follows:

           & - &amp;
           < - &lt;
           > - &gt;
           " - &quot;
           ' - &#39;

      Parameters:
        `c` - the character to be escaped
      Returns:
        a string containing either the input character or an equivalent HTML Entity Reference

    - #### htmlEscape

          public static java.lang.String htmlEscape(java.lang.String s)

      HTML-escapes a string.

      Note: The following variants of this function were profiled on FF40, Chrome44, Safari 8 and IE11:

      1. For each metachar, check indexOf, then use s.replace(regex, string)
      2. For each metachar use s.replace(regex, string)
      3. Manual replace each metachar by looping through characters in a loop.
      4. Check if any metachar is present using a regex, then use #1.
      5. Check if any metachar is present using a regex, then use #2.
      6. Check if any metachar is present using a regex, then use #3.

      For all browsers #4 was found to be the fastest, and is used below.

      The only out-lier was firefox with #6 being the optimal option, but #6 performs considerably worse in all other browsers.

      Parameters:
        `s` - the string to be escaped
      Returns:
        the input string, with all occurrences of HTML meta-characters replaced with their corresponding HTML Entity References

    - #### htmlEscapeAllowEntities

          public static java.lang.String htmlEscapeAllowEntities(java.lang.String text)

      HTML-escapes a string, but does not double-escape HTML-entities already present in the string.
      Parameters:
        `text` - the string to be escaped
      Returns:
        the input string, with all occurrences of HTML meta-characters replaced with their corresponding HTML Entity References, with the exception that ampersand characters are not double-escaped if they form the start of an HTML Entity Reference