1 /*
2 * Copyright (C) 2009 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 java.util.Map;
22 import javax.annotation.CheckForNull;
23
24 /**
25 * A {@link CharEscaper} that uses an array to quickly look up replacement characters for a given
26 * {@code char} value. An additional safe range is provided that determines whether {@code char}
27 * values without specific replacements are to be considered safe and left unescaped or should be
28 * escaped in a general way.
29 *
30 * <p>A good example of usage of this class is for Java source code escaping where the replacement
31 * array contains information about special ASCII characters such as {@code \\t} and {@code \\n}
32 * while {@link #escapeUnsafe} is overridden to handle general escaping of the form {@code \\uxxxx}.
33 *
34 * <p>The size of the data structure used by {@link ArrayBasedCharEscaper} is proportional to the
35 * highest valued character that requires escaping. For example a replacement map containing the
36 * single character '{@code \}{@code u1000}' will require approximately 16K of memory. If you need
37 * to create multiple escaper instances that have the same character replacement mapping consider
38 * using {@link ArrayBasedEscaperMap}.
39 *
40 * @author Sven Mawson
41 * @author David Beaumont
42 * @since 15.0
43 */
44 @Beta
45 @GwtCompatible
46 @ElementTypesAreNonnullByDefault
47 public abstract class ArrayBasedCharEscaper extends CharEscaper {
48 // The replacement array (see ArrayBasedEscaperMap).
49 private final char[][] replacements;
50 // The number of elements in the replacement array.
51 private final int replacementsLength;
52 // The first character in the safe range.
53 private final char safeMin;
54 // The last character in the safe range.
55 private final char safeMax;
56
57 /**
58 * Creates a new ArrayBasedCharEscaper instance with the given replacement map and specified safe
59 * range. If {@code safeMax < safeMin} then no characters are considered safe.
60 *
61 * <p>If a character has no mapped replacement then it is checked against the safe range. If it
62 * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
63 *
64 * @param replacementMap a map of characters to their escaped representations
65 * @param safeMin the lowest character value in the safe range
66 * @param safeMax the highest character value in the safe range
67 */
68 protected ArrayBasedCharEscaper(
69 Map<Character, String> replacementMap, char safeMin, char safeMax) {
70
71 this(ArrayBasedEscaperMap.create(replacementMap), safeMin, safeMax);
72 }
73
74 /**
75 * Creates a new ArrayBasedCharEscaper instance with the given replacement map and specified safe
76 * range. If {@code safeMax < safeMin} then no characters are considered safe. This initializer is
77 * useful when explicit instances of ArrayBasedEscaperMap are used to allow the sharing of large
78 * replacement mappings.
79 *
80 * <p>If a character has no mapped replacement then it is checked against the safe range. If it
81 * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
82 *
83 * @param escaperMap the mapping of characters to be escaped
84 * @param safeMin the lowest character value in the safe range
85 * @param safeMax the highest character value in the safe range
86 */
87 protected ArrayBasedCharEscaper(ArrayBasedEscaperMap escaperMap, char safeMin, char safeMax) {
88
89 checkNotNull(escaperMap); // GWT specific check (do not optimize)
90 this.replacements = escaperMap.getReplacementArray();
91 this.replacementsLength = replacements.length;
92 if (safeMax < safeMin) {
93 // If the safe range is empty, set the range limits to opposite extremes
94 // to ensure the first test of either value will (almost certainly) fail.
95 safeMax = Character.MIN_VALUE;
96 safeMin = Character.MAX_VALUE;
97 }
98 this.safeMin = safeMin;
99 this.safeMax = safeMax;
100 }
101
102 /*
103 * This is overridden to improve performance. Rough benchmarking shows that this almost doubles
104 * the speed when processing strings that do not require any escaping.
105 */
106 @Override
107 public final String escape(String s) {
108 checkNotNull(s); // GWT specific check (do not optimize).
109 for (int i = 0; i < s.length(); i++) {
110 char c = s.charAt(i);
111 if ((c < replacementsLength && replacements[c] != null) || c > safeMax || c < safeMin) {
112 return escapeSlow(s, i);
113 }
114 }
115 return s;
116 }
117
118 /**
119 * Escapes a single character using the replacement array and safe range values. If the given
120 * character does not have an explicit replacement and lies outside the safe range then {@link
121 * #escapeUnsafe} is called.
122 *
123 * @return the replacement characters, or {@code null} if no escaping was required
124 */
125 @Override
126 @CheckForNull
127 protected final char[] escape(char c) {
128 if (c < replacementsLength) {
129 char[] chars = replacements[c];
130 if (chars != null) {
131 return chars;
132 }
133 }
134 if (c >= safeMin && c <= safeMax) {
135 return null;
136 }
137 return escapeUnsafe(c);
138 }
139
140 /**
141 * Escapes a {@code char} value that has no direct explicit value in the replacement array and
142 * lies outside the stated safe range. Subclasses should override this method to provide
143 * generalized escaping for characters.
144 *
145 * <p>Note that arrays returned by this method must not be modified once they have been returned.
146 * However it is acceptable to return the same array multiple times (even for different input
147 * characters).
148 *
149 * @param c the character to escape
150 * @return the replacement characters, or {@code null} if no escaping was required
151 */
152 // TODO(dbeaumont,cpovirk): Rename this something better once refactoring done
153 @CheckForNull
154 protected abstract char[] escapeUnsafe(char c);
155 }