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