Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (C) 2009 The Guava Authors
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package com.google.common.escape;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
 
 import java.util.Map;
 
 import  javax.annotation.Nullable;

Static utility methods pertaining to Escaper instances.

Author(s):
Sven Mawson
David Beaumont
Since:
15.0
 
 public final class Escapers {
   private Escapers() {}

  
Returns an Escaper that does no escaping, passing all character data through unchanged.
 
   public static Escaper nullEscaper() {
     return ;
   }
 
   // An Escaper that efficiently performs no escaping.
   // Extending CharEscaper (instead of Escaper) makes Escapers.compose() easier.
   private static final Escaper NULL_ESCAPER = new CharEscaper() {
     @Override public String escape(String string) {
       return checkNotNull(string);
     }
 
     @Override protected char[] escape(char c) {
       // TODO: Fix tests not to call this directly and make it throw an error.
       return null;
     }
   };

  
Returns a builder for creating simple, fast escapers. A builder instance can be reused and each escaper that is created will be a snapshot of the current builder state. Builders are not thread safe.

The initial state of the builder is such that:

  • There are no replacement mappings
  • safeMin == Character.MIN_VALUE
  • safeMax == Character.MAX_VALUE
  • unsafeReplacement == null

For performance reasons escapers created by this builder are not Unicode aware and will not validate the well-formedness of their input.

 
   public static Builder builder() {
     return new Builder();
   }

  
A builder for simple, fast escapers.

Typically an escaper needs to deal with the escaping of high valued characters or code points. In these cases it is necessary to extend either ArrayBasedCharEscaper or ArrayBasedUnicodeEscaper to provide the desired behavior. However this builder is suitable for creating escapers that replace a relative small set of characters.

Author(s):
David Beaumont
Since:
15.0
 
   @Beta
   public static final class Builder {
     private final Map<CharacterStringreplacementMap =
         new HashMap<CharacterString>();
     private char safeMin = .;
     private char safeMax = .;
     private String unsafeReplacement = null;
    // The constructor is exposed via the builder() method above.
    private Builder() {}

    
Sets the safe range of characters for the escaper. Characters in this range that have no explicit replacement are considered 'safe' and remain unescaped in the output. If safeMax < safeMin then the safe range is empty.

Parameters:
safeMin the lowest 'safe' character
safeMax the highest 'safe' character
Returns:
the builder instance
    public Builder setSafeRange(char safeMinchar safeMax) {
      this. = safeMin;
      this. = safeMax;
      return this;
    }

    
Sets the replacement string for any characters outside the 'safe' range that have no explicit replacement. If unsafeReplacement is null then no replacement will occur, if it is "" then the unsafe characters are removed from the output.

Parameters:
unsafeReplacement the string to replace unsafe chracters
Returns:
the builder instance
    public Builder setUnsafeReplacement(@Nullable String unsafeReplacement) {
      this. = unsafeReplacement;
      return this;
    }

    
Adds a replacement string for the given input character. The specified character will be replaced by the given string whenever it occurs in the input, irrespective of whether it lies inside or outside the 'safe' range.

Parameters:
c the character to be replaced
replacement the string to replace the given character
Returns:
the builder instance
Throws:
NullPointerException if replacement is null
    public Builder addEscape(char cString replacement) {
      checkNotNull(replacement);
      // This can replace an existing character (the builder is re-usable).
      .put(creplacement);
      return this;
    }

    
Returns a new escaper based on the current state of the builder.
    public Escaper build() {
      return new ArrayBasedCharEscaper() {
        private final char[] replacementChars =
             != null ? .toCharArray() : null;
        @Override protected char[] escapeUnsafe(char c) {
          return ;
        }
      };
    }
  }

  
Returns a UnicodeEscaper equivalent to the given escaper instance. If the escaper is already a UnicodeEscaper then it is simply returned, otherwise it is wrapped in a UnicodeEscaper.

When a CharEscaper escaper is wrapped by this method it acquires extra behavior with respect to the well-formedness of Unicode character sequences and will throw IllegalArgumentException when given bad input.

Parameters:
escaper the instance to be wrapped
Returns:
a UnicodeEscaper with the same behavior as the given instance
Throws:
NullPointerException if escaper is null
IllegalArgumentException if escaper is not a UnicodeEscaper or a CharEscaper
  static UnicodeEscaper asUnicodeEscaper(Escaper escaper) {
    checkNotNull(escaper);
    if (escaper instanceof UnicodeEscaper) {
      return (UnicodeEscaperescaper;
    } else if (escaper instanceof CharEscaper) {
      return wrap((CharEscaperescaper);
    }
    // In practice this shouldn't happen because it would be very odd not to
    // extend either CharEscaper or UnicodeEscaper for non trivial cases.
    throw new IllegalArgumentException("Cannot create a UnicodeEscaper from: " +
        escaper.getClass().getName());
  }

  
Returns a string that would replace the given character in the specified escaper, or null if no replacement should be made. This method is intended for use in tests through the EscaperAsserts class; production users of CharEscaper should limit themselves to its public interface.

Parameters:
c the character to escape if necessary
Returns:
the replacement string, or null if no escaping was needed
  public static String computeReplacement(CharEscaper escaperchar c) {
    return stringOrNull(escaper.escape(c));
  }

  
Returns a string that would replace the given character in the specified escaper, or null if no replacement should be made. This method is intended for use in tests through the EscaperAsserts class; production users of UnicodeEscaper should limit themselves to its public interface.

Parameters:
cp the Unicode code point to escape if necessary
Returns:
the replacement string, or null if no escaping was needed
  public static String computeReplacement(UnicodeEscaper escaperint cp) {
    return stringOrNull(escaper.escape(cp));
  }
  private static String stringOrNull(char[] in) {
    return (in == null) ? null : new String(in);
  }

  
Private helper to wrap a CharEscaper as a UnicodeEscaper.
  private static UnicodeEscaper wrap(final CharEscaper escaper) {
    return new UnicodeEscaper() {
      @Override protected char[] escape(int cp) {
        // If a code point maps to a single character, just escape that.
        if (cp < .) {
          return escaper.escape((charcp);
        }
        // Convert the code point to a surrogate pair and escape them both.
        // Note: This code path is horribly slow and typically allocates 4 new
        // char[] each time it is invoked. However this avoids any
        // synchronization issues and makes the escaper thread safe.
        char[] surrogateChars = new char[2];
        Character.toChars(cpsurrogateChars, 0);
        char[] hiChars = escaper.escape(surrogateChars[0]);
        char[] loChars = escaper.escape(surrogateChars[1]);
        // If either hiChars or lowChars are non-null, the CharEscaper is trying
        // to escape the characters of a surrogate pair separately. This is
        // uncommon and applies only to escapers that assume UCS-2 rather than
        // UTF-16. See: http://en.wikipedia.org/wiki/UTF-16/UCS-2
        if (hiChars == null && loChars == null) {
          // We expect this to be the common code path for most escapers.
          return null;
        }
        // Combine the characters and/or escaped sequences into a single array.
        int hiCount = hiChars != null ? hiChars.length : 1;
        int loCount = loChars != null ? loChars.length : 1;
        char[] output = new char[hiCount + loCount];
        if (hiChars != null) {
          // TODO: Is this faster than System.arraycopy() for small arrays?
          for (int n = 0; n < hiChars.length; ++n) {
            output[n] = hiChars[n];
          }
        } else {
          output[0] = surrogateChars[0];
        }
        if (loChars != null) {
          for (int n = 0; n < loChars.length; ++n) {
            output[hiCount + n] = loChars[n];
          }
        } else {
          output[hiCount] = surrogateChars[1];
        }
        return output;
      }
    };
  }
New to GrepCode? Check out our FAQ X