001/*
002 * Copyright (C) 2009 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.escape;
016
017import static com.google.common.base.Preconditions.checkNotNull;
018
019import com.google.common.annotations.GwtCompatible;
020import java.util.Map;
021import javax.annotation.CheckForNull;
022import org.checkerframework.checker.nullness.qual.Nullable;
023
024/**
025 * A {@link UnicodeEscaper} that uses an array to quickly look up replacement characters for a given
026 * code point. An additional safe range is provided that determines whether code points without
027 * specific replacements are to be considered safe and left unescaped or should be escaped in a
028 * general way.
029 *
030 * <p>A good example of usage of this class is for HTML escaping where the replacement array
031 * contains information about the named HTML entities such as {@code &amp;} and {@code &quot;} while
032 * {@link #escapeUnsafe} is overridden to handle general escaping of the form {@code &#NNNNN;}.
033 *
034 * <p>The size of the data structure used by {@link ArrayBasedUnicodeEscaper} is proportional to the
035 * highest valued code point that requires escaping. For example a replacement map containing the
036 * single character '{@code \}{@code u1000}' will require approximately 16K of memory. If you need
037 * to create multiple escaper instances that have the same character replacement mapping consider
038 * using {@link ArrayBasedEscaperMap}.
039 *
040 * @author David Beaumont
041 * @since 15.0
042 */
043@GwtCompatible
044@ElementTypesAreNonnullByDefault
045public abstract class ArrayBasedUnicodeEscaper extends UnicodeEscaper {
046  // The replacement array (see ArrayBasedEscaperMap).
047  private final char[][] replacements;
048  // The number of elements in the replacement array.
049  private final int replacementsLength;
050  // The first code point in the safe range.
051  private final int safeMin;
052  // The last code point in the safe range.
053  private final int safeMax;
054
055  // Cropped values used in the fast path range checks.
056  private final char safeMinChar;
057  private final char safeMaxChar;
058
059  /**
060   * Creates a new ArrayBasedUnicodeEscaper instance with the given replacement map and specified
061   * safe range. If {@code safeMax < safeMin} then no code points are considered safe.
062   *
063   * <p>If a code point has no mapped replacement then it is checked against the safe range. If it
064   * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
065   *
066   * @param replacementMap a map of characters to their escaped representations
067   * @param safeMin the lowest character value in the safe range
068   * @param safeMax the highest character value in the safe range
069   * @param unsafeReplacement the default replacement for unsafe characters or null if no default
070   *     replacement is required
071   */
072  protected ArrayBasedUnicodeEscaper(
073      Map<Character, String> replacementMap,
074      int safeMin,
075      int safeMax,
076      @Nullable String unsafeReplacement) {
077    this(ArrayBasedEscaperMap.create(replacementMap), safeMin, safeMax, unsafeReplacement);
078  }
079
080  /**
081   * Creates a new ArrayBasedUnicodeEscaper instance with the given replacement map and specified
082   * safe range. If {@code safeMax < safeMin} then no code points are considered safe. This
083   * initializer is useful when explicit instances of ArrayBasedEscaperMap are used to allow the
084   * sharing of large replacement mappings.
085   *
086   * <p>If a code point has no mapped replacement then it is checked against the safe range. If it
087   * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
088   *
089   * @param escaperMap the map of replacements
090   * @param safeMin the lowest character value in the safe range
091   * @param safeMax the highest character value in the safe range
092   * @param unsafeReplacement the default replacement for unsafe characters or null if no default
093   *     replacement is required
094   */
095  protected ArrayBasedUnicodeEscaper(
096      ArrayBasedEscaperMap escaperMap,
097      int safeMin,
098      int safeMax,
099      @Nullable String unsafeReplacement) {
100    checkNotNull(escaperMap); // GWT specific check (do not optimize)
101    this.replacements = escaperMap.getReplacementArray();
102    this.replacementsLength = replacements.length;
103    if (safeMax < safeMin) {
104      // If the safe range is empty, set the range limits to opposite extremes
105      // to ensure the first test of either value will fail.
106      safeMax = -1;
107      safeMin = Integer.MAX_VALUE;
108    }
109    this.safeMin = safeMin;
110    this.safeMax = safeMax;
111
112    // This is a bit of a hack but lets us do quicker per-character checks in
113    // the fast path code. The safe min/max values are very unlikely to extend
114    // into the range of surrogate characters, but if they do we must not test
115    // any values in that range. To see why, consider the case where:
116    // safeMin <= {hi,lo} <= safeMax
117    // where {hi,lo} are characters forming a surrogate pair such that:
118    // codePointOf(hi, lo) > safeMax
119    // which would result in the surrogate pair being (wrongly) considered safe.
120    // If we clip the safe range used during the per-character tests so it is
121    // below the values of characters in surrogate pairs, this cannot occur.
122    // This approach does mean that we break out of the fast path code in cases
123    // where we don't strictly need to, but this situation will almost never
124    // occur in practice.
125    if (safeMin >= Character.MIN_HIGH_SURROGATE) {
126      // The safe range is empty or the all safe code points lie in or above the
127      // surrogate range. Either way the character range is empty.
128      this.safeMinChar = Character.MAX_VALUE;
129      this.safeMaxChar = 0;
130    } else {
131      // The safe range is non empty and contains values below the surrogate
132      // range but may extend above it. We may need to clip the maximum value.
133      this.safeMinChar = (char) safeMin;
134      this.safeMaxChar = (char) Math.min(safeMax, Character.MIN_HIGH_SURROGATE - 1);
135    }
136  }
137
138  /*
139   * This is overridden to improve performance. Rough benchmarking shows that this almost doubles
140   * the speed when processing strings that do not require any escaping.
141   */
142  @Override
143  public final String escape(String s) {
144    checkNotNull(s); // GWT specific check (do not optimize)
145    for (int i = 0; i < s.length(); i++) {
146      char c = s.charAt(i);
147      if ((c < replacementsLength && replacements[c] != null)
148          || c > safeMaxChar
149          || c < safeMinChar) {
150        return escapeSlow(s, i);
151      }
152    }
153    return s;
154  }
155
156  /**
157   * Escapes a single Unicode code point using the replacement array and safe range values. If the
158   * given character does not have an explicit replacement and lies outside the safe range then
159   * {@link #escapeUnsafe} is called.
160   *
161   * @return the replacement characters, or {@code null} if no escaping was required
162   */
163  @Override
164  @CheckForNull
165  protected final char[] escape(int cp) {
166    if (cp < replacementsLength) {
167      char[] chars = replacements[cp];
168      if (chars != null) {
169        return chars;
170      }
171    }
172    if (cp >= safeMin && cp <= safeMax) {
173      return null;
174    }
175    return escapeUnsafe(cp);
176  }
177
178  /* Overridden for performance. */
179  @Override
180  protected final int nextEscapeIndex(CharSequence csq, int index, int end) {
181    while (index < end) {
182      char c = csq.charAt(index);
183      if ((c < replacementsLength && replacements[c] != null)
184          || c > safeMaxChar
185          || c < safeMinChar) {
186        break;
187      }
188      index++;
189    }
190    return index;
191  }
192
193  /**
194   * Escapes a code point that has no direct explicit value in the replacement array and lies
195   * outside the stated safe range. Subclasses should override this method to provide generalized
196   * escaping for code points if required.
197   *
198   * <p>Note that arrays returned by this method must not be modified once they have been returned.
199   * However it is acceptable to return the same array multiple times (even for different input
200   * characters).
201   *
202   * @param cp the Unicode code point to escape
203   * @return the replacement characters, or {@code null} if no escaping was required
204   */
205  @CheckForNull
206  protected abstract char[] escapeUnsafe(int cp);
207}