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 org.jspecify.annotations.Nullable;
022
023/**
024 * A {@link CharEscaper} that uses an array to quickly look up replacement characters for a given
025 * {@code char} value. An additional safe range is provided that determines whether {@code char}
026 * values without specific replacements are to be considered safe and left unescaped or should be
027 * escaped in a general way.
028 *
029 * <p>A good example of usage of this class is for Java source code escaping where the replacement
030 * array contains information about special ASCII characters such as {@code \\t} and {@code \\n}
031 * while {@link #escapeUnsafe} is overridden to handle general escaping of the form {@code \\uxxxx}.
032 *
033 * <p>The size of the data structure used by {@link ArrayBasedCharEscaper} is proportional to the
034 * highest valued character that requires escaping. For example a replacement map containing the
035 * single character '{@code \}{@code u1000}' will require approximately 16K of memory. If you need
036 * to create multiple escaper instances that have the same character replacement mapping consider
037 * using {@link ArrayBasedEscaperMap}.
038 *
039 * @author Sven Mawson
040 * @author David Beaumont
041 * @since 15.0
042 */
043@GwtCompatible
044public abstract class ArrayBasedCharEscaper extends CharEscaper {
045  // The replacement array (see ArrayBasedEscaperMap).
046  private final char[][] replacements;
047  // The number of elements in the replacement array.
048  private final int replacementsLength;
049  // The first character in the safe range.
050  private final char safeMin;
051  // The last character in the safe range.
052  private final char safeMax;
053
054  /**
055   * Creates a new ArrayBasedCharEscaper instance with the given replacement map and specified safe
056   * range. If {@code safeMax < safeMin} then no characters are considered safe.
057   *
058   * <p>If a character has no mapped replacement then it is checked against the safe range. If it
059   * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
060   *
061   * @param replacementMap a map of characters to their escaped representations
062   * @param safeMin the lowest character value in the safe range
063   * @param safeMax the highest character value in the safe range
064   */
065  protected ArrayBasedCharEscaper(
066      Map<Character, String> replacementMap, char safeMin, char safeMax) {
067
068    this(ArrayBasedEscaperMap.create(replacementMap), safeMin, safeMax);
069  }
070
071  /**
072   * Creates a new ArrayBasedCharEscaper instance with the given replacement map and specified safe
073   * range. If {@code safeMax < safeMin} then no characters are considered safe. This initializer is
074   * useful when explicit instances of ArrayBasedEscaperMap are used to allow the sharing of large
075   * replacement mappings.
076   *
077   * <p>If a character has no mapped replacement then it is checked against the safe range. If it
078   * lies outside that, then {@link #escapeUnsafe} is called, otherwise no escaping is performed.
079   *
080   * @param escaperMap the mapping of characters to be escaped
081   * @param safeMin the lowest character value in the safe range
082   * @param safeMax the highest character value in the safe range
083   */
084  protected ArrayBasedCharEscaper(ArrayBasedEscaperMap escaperMap, char safeMin, char safeMax) {
085
086    checkNotNull(escaperMap); // GWT specific check (do not optimize)
087    this.replacements = escaperMap.getReplacementArray();
088    this.replacementsLength = replacements.length;
089    if (safeMax < safeMin) {
090      // If the safe range is empty, set the range limits to opposite extremes
091      // to ensure the first test of either value will (almost certainly) fail.
092      safeMax = Character.MIN_VALUE;
093      safeMin = Character.MAX_VALUE;
094    }
095    this.safeMin = safeMin;
096    this.safeMax = safeMax;
097  }
098
099  /*
100   * This is overridden to improve performance. Rough benchmarking shows that this almost doubles
101   * the speed when processing strings that do not require any escaping.
102   */
103  @Override
104  public final String escape(String s) {
105    checkNotNull(s); // GWT specific check (do not optimize).
106    for (int i = 0; i < s.length(); i++) {
107      char c = s.charAt(i);
108      if ((c < replacementsLength && replacements[c] != null) || c > safeMax || c < safeMin) {
109        return escapeSlow(s, i);
110      }
111    }
112    return s;
113  }
114
115  /**
116   * Escapes a single character using the replacement array and safe range values. If the given
117   * character does not have an explicit replacement and lies outside the safe range then {@link
118   * #escapeUnsafe} is called.
119   *
120   * @return the replacement characters, or {@code null} if no escaping was required
121   */
122  @Override
123  protected final char @Nullable [] escape(char c) {
124    if (c < replacementsLength) {
125      char[] chars = replacements[c];
126      if (chars != null) {
127        return chars;
128      }
129    }
130    if (c >= safeMin && c <= safeMax) {
131      return null;
132    }
133    return escapeUnsafe(c);
134  }
135
136  /**
137   * Escapes a {@code char} value that has no direct explicit value in the replacement array and
138   * lies outside the stated safe range. Subclasses should override this method to provide
139   * generalized escaping for characters.
140   *
141   * <p>Note that arrays returned by this method must not be modified once they have been returned.
142   * However it is acceptable to return the same array multiple times (even for different input
143   * characters).
144   *
145   * @param c the character to escape
146   * @return the replacement characters, or {@code null} if no escaping was required
147   */
148  // TODO(dbeaumont,cpovirk): Rename this something better once refactoring done
149  protected abstract char @Nullable [] escapeUnsafe(char c);
150}