View Javadoc
1   /*
2    * Copyright (C) 2006 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.escape;
16  
17  import static com.google.common.base.Preconditions.checkNotNull;
18  
19  import com.google.common.annotations.Beta;
20  import com.google.common.annotations.GwtCompatible;
21  
22  /**
23   * An object that converts literal text into a format safe for inclusion in a particular context
24   * (such as an XML document). Typically (but not always), the inverse process of "unescaping" the
25   * text is performed automatically by the relevant parser.
26   *
27   * <p>For example, an XML escaper would convert the literal string {@code "Foo<Bar>"} into {@code
28   * "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an XML tag. When the
29   * resulting XML document is parsed, the parser API will return this text as the original literal
30   * string {@code "Foo<Bar>"}.
31   *
32   * <p>A {@code CharEscaper} instance is required to be stateless, and safe when used concurrently by
33   * multiple threads.
34   *
35   * <p>Popular escapers are defined as constants in classes like
36   * {@link com.google.common.html.HtmlEscapers} and {@link com.google.common.xml.XmlEscapers}. To
37   * create your own escapers extend this class and implement the {@link #escape(char)} method.
38   *
39   * @author Sven Mawson
40   * @since 15.0
41   */
42  @Beta
43  @GwtCompatible
44  public abstract class CharEscaper extends Escaper {
45    /** Constructor for use by subclasses. */
46    protected CharEscaper() {}
47  
48    /**
49     * Returns the escaped form of a given literal string.
50     *
51     * @param string the literal string to be escaped
52     * @return the escaped form of {@code string}
53     * @throws NullPointerException if {@code string} is null
54     */
55    @Override
56    public String escape(String string) {
57      checkNotNull(string); // GWT specific check (do not optimize)
58      // Inlineable fast-path loop which hands off to escapeSlow() only if needed
59      int length = string.length();
60      for (int index = 0; index < length; index++) {
61        if (escape(string.charAt(index)) != null) {
62          return escapeSlow(string, index);
63        }
64      }
65      return string;
66    }
67  
68    /**
69     * Returns the escaped form of a given literal string, starting at the given index. This method is
70     * called by the {@link #escape(String)} method when it discovers that escaping is required. It is
71     * protected to allow subclasses to override the fastpath escaping function to inline their
72     * escaping test. See {@link CharEscaperBuilder} for an example usage.
73     *
74     * @param s the literal string to be escaped
75     * @param index the index to start escaping from
76     * @return the escaped form of {@code string}
77     * @throws NullPointerException if {@code string} is null
78     */
79    protected final String escapeSlow(String s, int index) {
80      int slen = s.length();
81  
82      // Get a destination buffer and setup some loop variables.
83      char[] dest = Platform.charBufferFromThreadLocal();
84      int destSize = dest.length;
85      int destIndex = 0;
86      int lastEscape = 0;
87  
88      // Loop through the rest of the string, replacing when needed into the
89      // destination buffer, which gets grown as needed as well.
90      for (; index < slen; index++) {
91  
92        // Get a replacement for the current character.
93        char[] r = escape(s.charAt(index));
94  
95        // If no replacement is needed, just continue.
96        if (r == null) {
97          continue;
98        }
99  
100       int rlen = r.length;
101       int charsSkipped = index - lastEscape;
102 
103       // This is the size needed to add the replacement, not the full size
104       // needed by the string. We only regrow when we absolutely must, and
105       // when we do grow, grow enough to avoid excessive growing. Grow.
106       int sizeNeeded = destIndex + charsSkipped + rlen;
107       if (destSize < sizeNeeded) {
108         destSize = sizeNeeded + DEST_PAD_MULTIPLIER * (slen - index);
109         dest = growBuffer(dest, destIndex, destSize);
110       }
111 
112       // If we have skipped any characters, we need to copy them now.
113       if (charsSkipped > 0) {
114         s.getChars(lastEscape, index, dest, destIndex);
115         destIndex += charsSkipped;
116       }
117 
118       // Copy the replacement string into the dest buffer as needed.
119       if (rlen > 0) {
120         System.arraycopy(r, 0, dest, destIndex, rlen);
121         destIndex += rlen;
122       }
123       lastEscape = index + 1;
124     }
125 
126     // Copy leftover characters if there are any.
127     int charsLeft = slen - lastEscape;
128     if (charsLeft > 0) {
129       int sizeNeeded = destIndex + charsLeft;
130       if (destSize < sizeNeeded) {
131 
132         // Regrow and copy, expensive! No padding as this is the final copy.
133         dest = growBuffer(dest, destIndex, sizeNeeded);
134       }
135       s.getChars(lastEscape, slen, dest, destIndex);
136       destIndex = sizeNeeded;
137     }
138     return new String(dest, 0, destIndex);
139   }
140 
141   /**
142    * Returns the escaped form of the given character, or {@code null} if this character does not
143    * need to be escaped. If an empty array is returned, this effectively strips the input character
144    * from the resulting text.
145    *
146    * <p>If the character does not need to be escaped, this method should return {@code null}, rather
147    * than a one-character array containing the character itself. This enables the escaping algorithm
148    * to perform more efficiently.
149    *
150    * <p>An escaper is expected to be able to deal with any {@code char} value, so this method should
151    * not throw any exceptions.
152    *
153    * @param c the character to escape if necessary
154    * @return the replacement characters, or {@code null} if no escaping was needed
155    */
156   protected abstract char[] escape(char c);
157 
158   /**
159    * Helper method to grow the character buffer as needed, this only happens once in a while so it's
160    * ok if it's in a method call. If the index passed in is 0 then no copying will be done.
161    */
162   private static char[] growBuffer(char[] dest, int index, int size) {
163     if (size < 0) { // overflow - should be OutOfMemoryError but GWT/j2cl don't support it
164       throw new AssertionError("Cannot increase internal buffer any further");
165     }
166     char[] copy = new char[size];
167     if (index > 0) {
168       System.arraycopy(dest, 0, copy, 0, index);
169     }
170     return copy;
171   }
172 
173   /**
174    * The multiplier for padding to use when growing the escape buffer.
175    */
176   private static final int DEST_PAD_MULTIPLIER = 2;
177 }