Uplandustries/Eaglercraft-1.8
1
0
Fork 0
mirror of https://github.com/Eaglercraft-Archive/Eaglercraftx-1.8.8-src.git synced 2025-06-28 02:48:14 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update #0 - First Release

Browse Source
This commit is contained in:
LAX1DUDE
2022-12-25 01:12:28 -08:00
commit e7179fad45
2154 changed files with 256324 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
sources/main/java/com/google/common/escape/ArrayBasedCharEscaper.java Normal file
View File

@ -0,0 +1,165 @@
/*
* 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 com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* A {@link CharEscaper} that uses an array to quickly look up replacement
* characters for a given {@code char} value. An additional safe range is
* provided that determines whether {@code char} values without specific
* replacements are to be considered safe and left unescaped or should be
* escaped in a general way.
*
* <p>
* A good example of usage of this class is for Java source code escaping where
* the replacement array contains information about special ASCII characters
* such as {@code \\t} and {@code \\n} while {@link #escapeUnsafe} is overridden
* to handle general escaping of the form {@code \\uxxxx}.
*
* <p>
* The size of the data structure used by {@link ArrayBasedCharEscaper} is
* proportional to the highest valued character that requires escaping. For
* example a replacement map containing the single character
* '{@code \}{@code u1000}' will require approximately 16K of memory. If you
* need to create multiple escaper instances that have the same character
* replacement mapping consider using {@link ArrayBasedEscaperMap}.
*
* @author Sven Mawson
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public abstract class ArrayBasedCharEscaper extends CharEscaper {
// The replacement array (see ArrayBasedEscaperMap).
private final char[][] replacements;
// The number of elements in the replacement array.
private final int replacementsLength;
// The first character in the safe range.
private final char safeMin;
// The last character in the safe range.
private final char safeMax;
/**
* Creates a new ArrayBasedCharEscaper instance with the given replacement map
* and specified safe range. If {@code safeMax < safeMin} then no characters are
* considered safe.
*
* <p>
* If a character has no mapped replacement then it is checked against the safe
* range. If it lies outside that, then {@link #escapeUnsafe} is called,
* otherwise no escaping is performed.
*
* @param replacementMap a map of characters to their escaped representations
* @param safeMin the lowest character value in the safe range
* @param safeMax the highest character value in the safe range
*/
protected ArrayBasedCharEscaper(Map<Character, String> replacementMap, char safeMin, char safeMax) {
this(ArrayBasedEscaperMap.create(replacementMap), safeMin, safeMax);
}
/**
* Creates a new ArrayBasedCharEscaper instance with the given replacement map
* and specified safe range. If {@code safeMax < safeMin} then no characters are
* considered safe. This initializer is useful when explicit instances of
* ArrayBasedEscaperMap are used to allow the sharing of large replacement
* mappings.
*
* <p>
* If a character has no mapped replacement then it is checked against the safe
* range. If it lies outside that, then {@link #escapeUnsafe} is called,
* otherwise no escaping is performed.
*
* @param escaperMap the mapping of characters to be escaped
* @param safeMin the lowest character value in the safe range
* @param safeMax the highest character value in the safe range
*/
protected ArrayBasedCharEscaper(ArrayBasedEscaperMap escaperMap, char safeMin, char safeMax) {
checkNotNull(escaperMap); // GWT specific check (do not optimize)
this.replacements = escaperMap.getReplacementArray();
this.replacementsLength = replacements.length;
if (safeMax < safeMin) {
// If the safe range is empty, set the range limits to opposite extremes
// to ensure the first test of either value will (almost certainly) fail.
safeMax = Character.MIN_VALUE;
safeMin = Character.MAX_VALUE;
}
this.safeMin = safeMin;
this.safeMax = safeMax;
}
/*
* This is overridden to improve performance. Rough benchmarking shows that this
* almost doubles the speed when processing strings that do not require any
* escaping.
*/
@Override
public final String escape(String s) {
checkNotNull(s); // GWT specific check (do not optimize).
for (int i = 0; i < s.length(); i++) {
char c = s.charAt(i);
if ((c < replacementsLength && replacements[c] != null) || c > safeMax || c < safeMin) {
return escapeSlow(s, i);
}
}
return s;
}
/**
* Escapes a single character using the replacement array and safe range values.
* If the given character does not have an explicit replacement and lies outside
* the safe range then {@link #escapeUnsafe} is called.
*/
@Override
protected final char[] escape(char c) {
if (c < replacementsLength) {
char[] chars = replacements[c];
if (chars != null) {
return chars;
}
}
if (c >= safeMin && c <= safeMax) {
return null;
}
return escapeUnsafe(c);
}
/**
* Escapes a {@code char} value that has no direct explicit value in the
* replacement array and lies outside the stated safe range. Subclasses should
* override this method to provide generalized escaping for characters.
*
* <p>
* Note that arrays returned by this method must not be modified once they have
* been returned. However it is acceptable to return the same array multiple
* times (even for different input characters).
*
* @param c the character to escape
* @return the replacement characters, or {@code null} if no escaping was
* required
*/
// TODO(user,cpovirk): Rename this something better once refactoring done
protected abstract char[] escapeUnsafe(char c);
}

91
sources/main/java/com/google/common/escape/ArrayBasedEscaperMap.java Normal file
View File

@ -0,0 +1,91 @@
/*
* 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.Collections;
import java.util.Map;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.VisibleForTesting;
/**
* An implementation-specific parameter class suitable for initializing
* {@link ArrayBasedCharEscaper} or {@link ArrayBasedUnicodeEscaper} instances.
* This class should be used when more than one escaper is created using the
* same character replacement mapping to allow the underlying (implementation
* specific) data structures to be shared.
*
* <p>
* The size of the data structure used by ArrayBasedCharEscaper and
* ArrayBasedUnicodeEscaper is proportional to the highest valued character that
* has a replacement. For example a replacement map containing the single
* character '{@literal \}u1000' will require approximately 16K of memory. As
* such sharing this data structure between escaper instances is the primary
* goal of this class.
*
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public final class ArrayBasedEscaperMap {
/**
* Returns a new ArrayBasedEscaperMap for creating ArrayBasedCharEscaper or
* ArrayBasedUnicodeEscaper instances.
*
* @param replacements a map of characters to their escaped representations
*/
public static ArrayBasedEscaperMap create(Map<Character, String> replacements) {
return new ArrayBasedEscaperMap(createReplacementArray(replacements));
}
// The underlying replacement array we can share between multiple escaper
// instances.
private final char[][] replacementArray;
private ArrayBasedEscaperMap(char[][] replacementArray) {
this.replacementArray = replacementArray;
}
// Returns the non-null array of replacements for fast lookup.
char[][] getReplacementArray() {
return replacementArray;
}
// Creates a replacement array from the given map. The returned array is a
// linear lookup table of replacement character sequences indexed by the
// original character value.
@VisibleForTesting
static char[][] createReplacementArray(Map<Character, String> map) {
checkNotNull(map); // GWT specific check (do not optimize)
if (map.isEmpty()) {
return EMPTY_REPLACEMENT_ARRAY;
}
char max = Collections.max(map.keySet());
char[][] replacements = new char[max + 1][];
for (char c : map.keySet()) {
replacements[c] = map.get(c).toCharArray();
}
return replacements;
}
// Immutable empty array for when there are no replacements.
private static final char[][] EMPTY_REPLACEMENT_ARRAY = new char[0][0];
}

212
sources/main/java/com/google/common/escape/ArrayBasedUnicodeEscaper.java Normal file
View File

@ -0,0 +1,212 @@
/*
* 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;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* A {@link UnicodeEscaper} that uses an array to quickly look up replacement
* characters for a given code point. An additional safe range is provided that
* determines whether code points without specific replacements are to be
* considered safe and left unescaped or should be escaped in a general way.
*
* <p>
* A good example of usage of this class is for HTML escaping where the
* replacement array contains information about the named HTML entities such as
* {@code &amp;} and {@code &quot;} while {@link #escapeUnsafe} is overridden to
* handle general escaping of the form {@code &#NNNNN;}.
*
* <p>
* The size of the data structure used by {@link ArrayBasedUnicodeEscaper} is
* proportional to the highest valued code point that requires escaping. For
* example a replacement map containing the single character
* '{@code \}{@code u1000}' will require approximately 16K of memory. If you
* need to create multiple escaper instances that have the same character
* replacement mapping consider using {@link ArrayBasedEscaperMap}.
*
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public abstract class ArrayBasedUnicodeEscaper extends UnicodeEscaper {
// The replacement array (see ArrayBasedEscaperMap).
private final char[][] replacements;
// The number of elements in the replacement array.
private final int replacementsLength;
// The first code point in the safe range.
private final int safeMin;
// The last code point in the safe range.
private final int safeMax;
// Cropped values used in the fast path range checks.
private final char safeMinChar;
private final char safeMaxChar;
/**
* Creates a new ArrayBasedUnicodeEscaper instance with the given replacement
* map and specified safe range. If {@code safeMax < safeMin} then no code
* points are considered safe.
*
* <p>
* If a code point has no mapped replacement then it is checked against the safe
* range. If it lies outside that, then {@link #escapeUnsafe} is called,
* otherwise no escaping is performed.
*
* @param replacementMap a map of characters to their escaped representations
* @param safeMin the lowest character value in the safe range
* @param safeMax the highest character value in the safe range
* @param unsafeReplacement the default replacement for unsafe characters or
* null if no default replacement is required
*/
protected ArrayBasedUnicodeEscaper(Map<Character, String> replacementMap, int safeMin, int safeMax,
@Nullable String unsafeReplacement) {
this(ArrayBasedEscaperMap.create(replacementMap), safeMin, safeMax, unsafeReplacement);
}
/**
* Creates a new ArrayBasedUnicodeEscaper instance with the given replacement
* map and specified safe range. If {@code safeMax < safeMin} then no code
* points are considered safe. This initializer is useful when explicit
* instances of ArrayBasedEscaperMap are used to allow the sharing of large
* replacement mappings.
*
* <p>
* If a code point has no mapped replacement then it is checked against the safe
* range. If it lies outside that, then {@link #escapeUnsafe} is called,
* otherwise no escaping is performed.
*
* @param escaperMap the map of replacements
* @param safeMin the lowest character value in the safe range
* @param safeMax the highest character value in the safe range
* @param unsafeReplacement the default replacement for unsafe characters or
* null if no default replacement is required
*/
protected ArrayBasedUnicodeEscaper(ArrayBasedEscaperMap escaperMap, int safeMin, int safeMax,
@Nullable String unsafeReplacement) {
checkNotNull(escaperMap); // GWT specific check (do not optimize)
this.replacements = escaperMap.getReplacementArray();
this.replacementsLength = replacements.length;
if (safeMax < safeMin) {
// If the safe range is empty, set the range limits to opposite extremes
// to ensure the first test of either value will fail.
safeMax = -1;
safeMin = Integer.MAX_VALUE;
}
this.safeMin = safeMin;
this.safeMax = safeMax;
// This is a bit of a hack but lets us do quicker per-character checks in
// the fast path code. The safe min/max values are very unlikely to extend
// into the range of surrogate characters, but if they do we must not test
// any values in that range. To see why, consider the case where:
// safeMin <= {hi,lo} <= safeMax
// where {hi,lo} are characters forming a surrogate pair such that:
// codePointOf(hi, lo) > safeMax
// which would result in the surrogate pair being (wrongly) considered safe.
// If we clip the safe range used during the per-character tests so it is
// below the values of characters in surrogate pairs, this cannot occur.
// This approach does mean that we break out of the fast path code in cases
// where we don't strictly need to, but this situation will almost never
// occur in practice.
if (safeMin >= Character.MIN_HIGH_SURROGATE) {
// The safe range is empty or the all safe code points lie in or above the
// surrogate range. Either way the character range is empty.
this.safeMinChar = Character.MAX_VALUE;
this.safeMaxChar = 0;
} else {
// The safe range is non empty and contains values below the surrogate
// range but may extend above it. We may need to clip the maximum value.
this.safeMinChar = (char) safeMin;
this.safeMaxChar = (char) Math.min(safeMax, Character.MIN_HIGH_SURROGATE - 1);
}
}
/*
* This is overridden to improve performance. Rough benchmarking shows that this
* almost doubles the speed when processing strings that do not require any
* escaping.
*/
@Override
public final String escape(String s) {
checkNotNull(s); // GWT specific check (do not optimize)
for (int i = 0; i < s.length(); i++) {
char c = s.charAt(i);
if ((c < replacementsLength && replacements[c] != null) || c > safeMaxChar || c < safeMinChar) {
return escapeSlow(s, i);
}
}
return s;
}
/* Overridden for performance. */
@Override
protected final int nextEscapeIndex(CharSequence csq, int index, int end) {
while (index < end) {
char c = csq.charAt(index);
if ((c < replacementsLength && replacements[c] != null) || c > safeMaxChar || c < safeMinChar) {
break;
}
index++;
}
return index;
}
/**
* Escapes a single Unicode code point using the replacement array and safe
* range values. If the given character does not have an explicit replacement
* and lies outside the safe range then {@link #escapeUnsafe} is called.
*/
@Override
protected final char[] escape(int cp) {
if (cp < replacementsLength) {
char[] chars = replacements[cp];
if (chars != null) {
return chars;
}
}
if (cp >= safeMin && cp <= safeMax) {
return null;
}
return escapeUnsafe(cp);
}
/**
* Escapes a code point that has no direct explicit value in the replacement
* array and lies outside the stated safe range. Subclasses should override this
* method to provide generalized escaping for code points if required.
*
* <p>
* Note that arrays returned by this method must not be modified once they have
* been returned. However it is acceptable to return the same array multiple
* times (even for different input characters).
*
* @param cp the Unicode code point to escape
* @return the replacement characters, or {@code null} if no escaping was
* required
*/
protected abstract char[] escapeUnsafe(int cp);
}

187
sources/main/java/com/google/common/escape/CharEscaper.java Normal file
View File

@ -0,0 +1,187 @@
/*
* Copyright (C) 2006 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 com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* An object that converts literal text into a format safe for inclusion in a
* particular context (such as an XML document). Typically (but not always), the
* inverse process of "unescaping" the text is performed automatically by the
* relevant parser.
*
* <p>
* For example, an XML escaper would convert the literal string
* {@code "Foo<Bar>"} into {@code
* "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an XML
* tag. When the resulting XML document is parsed, the parser API will return
* this text as the original literal string {@code "Foo<Bar>"}.
*
* <p>
* A {@code CharEscaper} instance is required to be stateless, and safe when
* used concurrently by multiple threads.
*
* <p>
* Several popular escapers are defined as constants in classes like
* {@link com.google.common.html.HtmlEscapers},
* {@link com.google.common.xml.XmlEscapers}, and {@link SourceCodeEscapers}. To
* create your own escapers extend this class and implement the
* {@link #escape(char)} method.
*
* @author Sven Mawson
* @since 15.0
*/
@Beta
@GwtCompatible
public abstract class CharEscaper extends Escaper {
/** Constructor for use by subclasses. */
protected CharEscaper() {
}
/**
* Returns the escaped form of a given literal string.
*
* @param string the literal string to be escaped
* @return the escaped form of {@code string}
* @throws NullPointerException if {@code string} is null
*/
@Override
public String escape(String string) {
checkNotNull(string); // GWT specific check (do not optimize)
// Inlineable fast-path loop which hands off to escapeSlow() only if needed
int length = string.length();
for (int index = 0; index < length; index++) {
if (escape(string.charAt(index)) != null) {
return escapeSlow(string, index);
}
}
return string;
}
/**
* Returns the escaped form of a given literal string, starting at the given
* index. This method is called by the {@link #escape(String)} method when it
* discovers that escaping is required. It is protected to allow subclasses to
* override the fastpath escaping function to inline their escaping test. See
* {@link CharEscaperBuilder} for an example usage.
*
* @param s the literal string to be escaped
* @param index the index to start escaping from
* @return the escaped form of {@code string}
* @throws NullPointerException if {@code string} is null
*/
protected final String escapeSlow(String s, int index) {
int slen = s.length();
// Get a destination buffer and setup some loop variables.
char[] dest = Platform.charBufferFromThreadLocal();
int destSize = dest.length;
int destIndex = 0;
int lastEscape = 0;
// Loop through the rest of the string, replacing when needed into the
// destination buffer, which gets grown as needed as well.
for (; index < slen; index++) {
// Get a replacement for the current character.
char[] r = escape(s.charAt(index));
// If no replacement is needed, just continue.
if (r == null)
continue;
int rlen = r.length;
int charsSkipped = index - lastEscape;
// This is the size needed to add the replacement, not the full size
// needed by the string. We only regrow when we absolutely must, and
// when we do grow, grow enough to avoid excessive growing. Grow.
int sizeNeeded = destIndex + charsSkipped + rlen;
if (destSize < sizeNeeded) {
destSize = sizeNeeded + DEST_PAD_MULTIPLIER * (slen - index);
dest = growBuffer(dest, destIndex, destSize);
}
// If we have skipped any characters, we need to copy them now.
if (charsSkipped > 0) {
s.getChars(lastEscape, index, dest, destIndex);
destIndex += charsSkipped;
}
// Copy the replacement string into the dest buffer as needed.
if (rlen > 0) {
System.arraycopy(r, 0, dest, destIndex, rlen);
destIndex += rlen;
}
lastEscape = index + 1;
}
// Copy leftover characters if there are any.
int charsLeft = slen - lastEscape;
if (charsLeft > 0) {
int sizeNeeded = destIndex + charsLeft;
if (destSize < sizeNeeded) {
// Regrow and copy, expensive! No padding as this is the final copy.
dest = growBuffer(dest, destIndex, sizeNeeded);
}
s.getChars(lastEscape, slen, dest, destIndex);
destIndex = sizeNeeded;
}
return new String(dest, 0, destIndex);
}
/**
* Returns the escaped form of the given character, or {@code null} if this
* character does not need to be escaped. If an empty array is returned, this
* effectively strips the input character from the resulting text.
*
* <p>
* If the character does not need to be escaped, this method should return
* {@code null}, rather than a one-character array containing the character
* itself. This enables the escaping algorithm to perform more efficiently.
*
* <p>
* An escaper is expected to be able to deal with any {@code char} value, so
* this method should not throw any exceptions.
*
* @param c the character to escape if necessary
* @return the replacement characters, or {@code null} if no escaping was needed
*/
protected abstract char[] escape(char c);
/**
* Helper method to grow the character buffer as needed, this only happens once
* in a while so it's ok if it's in a method call. If the index passed in is 0
* then no copying will be done.
*/
private static char[] growBuffer(char[] dest, int index, int size) {
char[] copy = new char[size];
if (index > 0) {
System.arraycopy(dest, 0, copy, 0, index);
}
return copy;
}
/**
* The multiplier for padding to use when growing the escape buffer.
*/
private static final int DEST_PAD_MULTIPLIER = 2;
}

134
sources/main/java/com/google/common/escape/CharEscaperBuilder.java Normal file
View File

@ -0,0 +1,134 @@
/*
* Copyright (C) 2006 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.HashMap;
import java.util.Map;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* Simple helper class to build a "sparse" array of objects based on the indexes
* that were added to it. The array will be from 0 to the maximum index given.
* All non-set indexes will contain null (so it's not really a sparse array,
* just a pseudo sparse array). The builder can also return a CharEscaper based
* on the generated array.
*
* @author Sven Mawson
* @since 15.0
*/
@Beta
@GwtCompatible
public final class CharEscaperBuilder {
/**
* Simple decorator that turns an array of replacement char[]s into a
* CharEscaper, this results in a very fast escape method.
*/
private static class CharArrayDecorator extends CharEscaper {
private final char[][] replacements;
private final int replaceLength;
CharArrayDecorator(char[][] replacements) {
this.replacements = replacements;
this.replaceLength = replacements.length;
}
/*
* Overriding escape method to be slightly faster for this decorator. We test
* the replacements array directly, saving a method call.
*/
@Override
public String escape(String s) {
int slen = s.length();
for (int index = 0; index < slen; index++) {
char c = s.charAt(index);
if (c < replacements.length && replacements[c] != null) {
return escapeSlow(s, index);
}
}
return s;
}
@Override
protected char[] escape(char c) {
return c < replaceLength ? replacements[c] : null;
}
}
// Replacement mappings.
private final Map<Character, String> map;
// The highest index we've seen so far.
private int max = -1;
/**
* Construct a new sparse array builder.
*/
public CharEscaperBuilder() {
this.map = new HashMap<Character, String>();
}
/**
* Add a new mapping from an index to an object to the escaping.
*/
public CharEscaperBuilder addEscape(char c, String r) {
map.put(c, checkNotNull(r));
if (c > max) {
max = c;
}
return this;
}
/**
* Add multiple mappings at once for a particular index.
*/
public CharEscaperBuilder addEscapes(char[] cs, String r) {
checkNotNull(r);
for (char c : cs) {
addEscape(c, r);
}
return this;
}
/**
* Convert this builder into an array of char[]s where the maximum index is the
* value of the highest character that has been seen. The array will be sparse
* in the sense that any unseen index will default to null.
*
* @return a "sparse" array that holds the replacement mappings.
*/
public char[][] toArray() {
char[][] result = new char[max + 1][];
for (Map.Entry<Character, String> entry : map.entrySet()) {
result[entry.getKey()] = entry.getValue().toCharArray();
}
return result;
}
/**
* Convert this builder into a char escaper which is just a decorator around the
* underlying array of replacement char[]s.
*
* @return an escaper that escapes based on the underlying array.
*/
public Escaper toEscaper() {
return new CharArrayDecorator(toArray());
}
}

122
sources/main/java/com/google/common/escape/Escaper.java Normal file
View File

@ -0,0 +1,122 @@
/*
* Copyright (C) 2008 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 com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Function;
/**
* An object that converts literal text into a format safe for inclusion in a
* particular context (such as an XML document). Typically (but not always), the
* inverse process of "unescaping" the text is performed automatically by the
* relevant parser.
*
* <p>
* For example, an XML escaper would convert the literal string
* {@code "Foo<Bar>"} into {@code
* "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an XML
* tag. When the resulting XML document is parsed, the parser API will return
* this text as the original literal string {@code "Foo<Bar>"}.
*
* <p>
* An {@code Escaper} instance is required to be stateless, and safe when used
* concurrently by multiple threads.
*
* <p>
* Because, in general, escaping operates on the code points of a string and not
* on its individual {@code char} values, it is not safe to assume that
* {@code escape(s)} is equivalent to
* {@code escape(s.substring(0, n)) + escape(s.substing(n))} for arbitrary
* {@code n}. This is because of the possibility of splitting a surrogate pair.
* The only case in which it is safe to escape strings and concatenate the
* results is if you can rule out this possibility, either by splitting an
* existing long string into short strings adaptively around
* {@linkplain Character#isHighSurrogate surrogate}
* {@linkplain Character#isLowSurrogate pairs}, or by starting with short
* strings already known to be free of unpaired surrogates.
*
* <p>
* The two primary implementations of this interface are {@link CharEscaper} and
* {@link UnicodeEscaper}. They are heavily optimized for performance and
* greatly simplify the task of implementing new escapers. It is strongly
* recommended that when implementing a new escaper you extend one of these
* classes. If you find that you are unable to achieve the desired behavior
* using either of these classes, please contact the Java libraries team for
* advice.
*
* <p>
* Several popular escapers are defined as constants in classes like
* {@link com.google.common.html.HtmlEscapers},
* {@link com.google.common.xml.XmlEscapers}, and {@link SourceCodeEscapers}. To
* create your own escapers, use {@link CharEscaperBuilder}, or extend
* {@code CharEscaper} or {@code UnicodeEscaper}.
*
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public abstract class Escaper {
// TODO(user): evaluate custom implementations, considering package private
// constructor.
/** Constructor for use by subclasses. */
protected Escaper() {
}
/**
* Returns the escaped form of a given literal string.
*
* <p>
* Note that this method may treat input characters differently depending on the
* specific escaper implementation.
*
* <ul>
* <li>{@link UnicodeEscaper} handles
* <a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> correctly, including
* surrogate character pairs. If the input is badly formed the escaper should
* throw {@link IllegalArgumentException}.
* <li>{@link CharEscaper} handles Java characters independently and does not
* verify the input for well formed characters. A {@code CharEscaper} should not
* be used in situations where input is not guaranteed to be restricted to the
* Basic Multilingual Plane (BMP).
* </ul>
*
* @param string the literal string to be escaped
* @return the escaped form of {@code string}
* @throws NullPointerException if {@code string} is null
* @throws IllegalArgumentException if {@code string} contains badly formed
* UTF-16 or cannot be escaped for any other
* reason
*/
public abstract String escape(String string);
private final Function<String, String> asFunction = new Function<String, String>() {
@Override
public String apply(String from) {
return escape(from);
}
};
/**
* Returns a {@link Function} that invokes {@link #escape(String)} on this
* escaper.
*/
public final Function<String, String> asFunction() {
return asFunction;
}
}

283
sources/main/java/com/google/common/escape/Escapers.java Normal file
View File

@ -0,0 +1,283 @@
/*
* 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.HashMap;
import java.util.Map;
import javax.annotation.Nullable;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* Static utility methods pertaining to {@link Escaper} instances.
*
* @author Sven Mawson
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public final class Escapers {
private Escapers() {
}
/**
* Returns an {@link Escaper} that does no escaping, passing all character data
* through unchanged.
*/
public static Escaper nullEscaper() {
return NULL_ESCAPER;
}
// 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.
*
* <p>
* The initial state of the builder is such that:
* <ul>
* <li>There are no replacement mappings
* <li>
* <li>{@code safeMin == Character.MIN_VALUE}</li>
* <li>{@code safeMax == Character.MAX_VALUE}</li>
* <li>{@code unsafeReplacement == null}</li>
* </ul>
* <p>
* 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.
*
* <p>
* 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
* {@link ArrayBasedCharEscaper} or {@link ArrayBasedUnicodeEscaper} to provide
* the desired behavior. However this builder is suitable for creating escapers
* that replace a relative small set of characters.
*
* @author David Beaumont
* @since 15.0
*/
@Beta
public static final class Builder {
private final Map<Character, String> replacementMap = new HashMap<Character, String>();
private char safeMin = Character.MIN_VALUE;
private char safeMax = Character.MAX_VALUE;
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 {@code safeMax < safeMin} then the safe range is empty.
*
* @param safeMin the lowest 'safe' character
* @param safeMax the highest 'safe' character
* @return the builder instance
*/
public Builder setSafeRange(char safeMin, char safeMax) {
this.safeMin = safeMin;
this.safeMax = safeMax;
return this;
}
/**
* Sets the replacement string for any characters outside the 'safe' range that
* have no explicit replacement. If {@code unsafeReplacement} is {@code null}
* then no replacement will occur, if it is {@code ""} then the unsafe
* characters are removed from the output.
*
* @param unsafeReplacement the string to replace unsafe chracters
* @return the builder instance
*/
public Builder setUnsafeReplacement(@Nullable String unsafeReplacement) {
this.unsafeReplacement = 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.
*
* @param c the character to be replaced
* @param replacement the string to replace the given character
* @return the builder instance
* @throws NullPointerException if {@code replacement} is null
*/
public Builder addEscape(char c, String replacement) {
checkNotNull(replacement);
// This can replace an existing character (the builder is re-usable).
replacementMap.put(c, replacement);
return this;
}
/**
* Returns a new escaper based on the current state of the builder.
*/
public Escaper build() {
return new ArrayBasedCharEscaper(replacementMap, safeMin, safeMax) {
private final char[] replacementChars = unsafeReplacement != null ? unsafeReplacement.toCharArray()
: null;
@Override
protected char[] escapeUnsafe(char c) {
return replacementChars;
}
};
}
}
/**
* Returns a {@link 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.
*
* <p>
* When a {@link CharEscaper} escaper is wrapped by this method it acquires
* extra behavior with respect to the well-formedness of Unicode character
* sequences and will throw {@link IllegalArgumentException} when given bad
* input.
*
* @param escaper the instance to be wrapped
* @return a UnicodeEscaper with the same behavior as the given instance
* @throws NullPointerException if escaper is null
* @throws IllegalArgumentException if escaper is not a UnicodeEscaper or a
* CharEscaper
*/
static UnicodeEscaper asUnicodeEscaper(Escaper escaper) {
checkNotNull(escaper);
if (escaper instanceof UnicodeEscaper) {
return (UnicodeEscaper) escaper;
} else if (escaper instanceof CharEscaper) {
return wrap((CharEscaper) escaper);
}
// 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 {@code null} if no replacement should be made. This method is
* intended for use in tests through the {@code EscaperAsserts} class;
* production users of {@link CharEscaper} should limit themselves to its public
* interface.
*
* @param c the character to escape if necessary
* @return the replacement string, or {@code null} if no escaping was needed
*/
public static String computeReplacement(CharEscaper escaper, char c) {
return stringOrNull(escaper.escape(c));
}
/**
* Returns a string that would replace the given character in the specified
* escaper, or {@code null} if no replacement should be made. This method is
* intended for use in tests through the {@code EscaperAsserts} class;
* production users of {@link UnicodeEscaper} should limit themselves to its
* public interface.
*
* @param cp the Unicode code point to escape if necessary
* @return the replacement string, or {@code null} if no escaping was needed
*/
public static String computeReplacement(UnicodeEscaper escaper, int 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 < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
return escaper.escape((char) cp);
}
// 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(cp, surrogateChars, 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;
}
};
}
}

47
sources/main/java/com/google/common/escape/Platform.java Normal file
View File

@ -0,0 +1,47 @@
/*
* 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 com.google.common.annotations.GwtCompatible;
/**
* Methods factored out so that they can be emulated differently in GWT.
*
* @author Jesse Wilson
*/
@GwtCompatible(emulated = true)
final class Platform {
private Platform() {
}
/** Returns a thread-local 1024-char array. */
static char[] charBufferFromThreadLocal() {
return DEST_TL.get();
}
/**
* A thread-local destination buffer to keep us from creating new buffers. The
* starting size is 1024 characters. If we grow past this we don't put it back
* in the threadlocal, we just keep going and grow as needed.
*/
private static final ThreadLocal<char[]> DEST_TL = new ThreadLocal<char[]>() {
@Override
protected char[] initialValue() {
return new char[1024];
}
};
}

320
sources/main/java/com/google/common/escape/UnicodeEscaper.java Normal file
View File

@ -0,0 +1,320 @@
/*
* Copyright (C) 2008 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 com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
/**
* An {@link Escaper} that converts literal text into a format safe for
* inclusion in a particular context (such as an XML document). Typically (but
* not always), the inverse process of "unescaping" the text is performed
* automatically by the relevant parser.
*
* <p>
* For example, an XML escaper would convert the literal string {@code
* "Foo<Bar>"} into {@code "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from
* being confused with an XML tag. When the resulting XML document is parsed,
* the parser API will return this text as the original literal string {@code
* "Foo<Bar>"}.
*
* <p>
* <b>Note:</b> This class is similar to {@link CharEscaper} but with one very
* important difference. A CharEscaper can only process Java
* <a href="http://en.wikipedia.org/wiki/UTF-16">UTF16</a> characters in
* isolation and may not cope when it encounters surrogate pairs. This class
* facilitates the correct escaping of all Unicode characters.
*
* <p>
* As there are important reasons, including potential security issues, to
* handle Unicode correctly if you are considering implementing a new escaper
* you should favor using UnicodeEscaper wherever possible.
*
* <p>
* A {@code UnicodeEscaper} instance is required to be stateless, and safe when
* used concurrently by multiple threads.
*
* <p>
* Several popular escapers are defined as constants in classes like
* {@link com.google.common.html.HtmlEscapers},
* {@link com.google.common.xml.XmlEscapers}, and {@link SourceCodeEscapers}. To
* create your own escapers extend this class and implement the
* {@link #escape(int)} method.
*
* @author David Beaumont
* @since 15.0
*/
@Beta
@GwtCompatible
public abstract class UnicodeEscaper extends Escaper {
/** The amount of padding (chars) to use when growing the escape buffer. */
private static final int DEST_PAD = 32;
/** Constructor for use by subclasses. */
protected UnicodeEscaper() {
}
/**
* Returns the escaped form of the given Unicode code point, or {@code null} if
* this code point does not need to be escaped. When called as part of an
* escaping operation, the given code point is guaranteed to be in the range
* {@code 0 <= cp <= Character#MAX_CODE_POINT}.
*
* <p>
* If an empty array is returned, this effectively strips the input character
* from the resulting text.
*
* <p>
* If the character does not need to be escaped, this method should return
* {@code null}, rather than an array containing the character representation of
* the code point. This enables the escaping algorithm to perform more
* efficiently.
*
* <p>
* If the implementation of this method cannot correctly handle a particular
* code point then it should either throw an appropriate runtime exception or
* return a suitable replacement character. It must never silently discard
* invalid input as this may constitute a security risk.
*
* @param cp the Unicode code point to escape if necessary
* @return the replacement characters, or {@code null} if no escaping was needed
*/
protected abstract char[] escape(int cp);
/**
* Scans a sub-sequence of characters from a given {@link CharSequence},
* returning the index of the next character that requires escaping.
*
* <p>
* <b>Note:</b> When implementing an escaper, it is a good idea to override this
* method for efficiency. The base class implementation determines successive
* Unicode code points and invokes {@link #escape(int)} for each of them. If the
* semantics of your escaper are such that code points in the supplementary
* range are either all escaped or all unescaped, this method can be implemented
* more efficiently using {@link CharSequence#charAt(int)}.
*
* <p>
* Note however that if your escaper does not escape characters in the
* supplementary range, you should either continue to validate the correctness
* of any surrogate characters encountered or provide a clear warning to users
* that your escaper does not validate its input.
*
* <p>
* See {@link com.google.common.net.PercentEscaper} for an example.
*
* @param csq a sequence of characters
* @param start the index of the first character to be scanned
* @param end the index immediately after the last character to be scanned
* @throws IllegalArgumentException if the scanned sub-sequence of {@code csq}
* contains invalid surrogate pairs
*/
protected int nextEscapeIndex(CharSequence csq, int start, int end) {
int index = start;
while (index < end) {
int cp = codePointAt(csq, index, end);
if (cp < 0 || escape(cp) != null) {
break;
}
index += Character.isSupplementaryCodePoint(cp) ? 2 : 1;
}
return index;
}
/**
* Returns the escaped form of a given literal string.
*
* <p>
* If you are escaping input in arbitrary successive chunks, then it is not
* generally safe to use this method. If an input string ends with an unmatched
* high surrogate character, then this method will throw
* {@link IllegalArgumentException}. You should ensure your input is valid
* <a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> before calling this
* method.
*
* <p>
* <b>Note:</b> When implementing an escaper it is a good idea to override this
* method for efficiency by inlining the implementation of
* {@link #nextEscapeIndex(CharSequence, int, int)} directly. Doing this for
* {@link com.google.common.net.PercentEscaper} more than doubled the
* performance for unescaped strings (as measured by
* {@link CharEscapersBenchmark}).
*
* @param string the literal string to be escaped
* @return the escaped form of {@code string}
* @throws NullPointerException if {@code string} is null
* @throws IllegalArgumentException if invalid surrogate characters are
* encountered
*/
@Override
public String escape(String string) {
checkNotNull(string);
int end = string.length();
int index = nextEscapeIndex(string, 0, end);
return index == end ? string : escapeSlow(string, index);
}
/**
* Returns the escaped form of a given literal string, starting at the given
* index. This method is called by the {@link #escape(String)} method when it
* discovers that escaping is required. It is protected to allow subclasses to
* override the fastpath escaping function to inline their escaping test. See
* {@link CharEscaperBuilder} for an example usage.
*
* <p>
* This method is not reentrant and may only be invoked by the top level
* {@link #escape(String)} method.
*
* @param s the literal string to be escaped
* @param index the index to start escaping from
* @return the escaped form of {@code string}
* @throws NullPointerException if {@code string} is null
* @throws IllegalArgumentException if invalid surrogate characters are
* encountered
*/
protected final String escapeSlow(String s, int index) {
int end = s.length();
// Get a destination buffer and setup some loop variables.
char[] dest = Platform.charBufferFromThreadLocal();
int destIndex = 0;
int unescapedChunkStart = 0;
while (index < end) {
int cp = codePointAt(s, index, end);
if (cp < 0) {
throw new IllegalArgumentException("Trailing high surrogate at end of input");
}
// It is possible for this to return null because nextEscapeIndex() may
// (for performance reasons) yield some false positives but it must never
// give false negatives.
char[] escaped = escape(cp);
int nextIndex = index + (Character.isSupplementaryCodePoint(cp) ? 2 : 1);
if (escaped != null) {
int charsSkipped = index - unescapedChunkStart;
// This is the size needed to add the replacement, not the full
// size needed by the string. We only regrow when we absolutely must.
int sizeNeeded = destIndex + charsSkipped + escaped.length;
if (dest.length < sizeNeeded) {
int destLength = sizeNeeded + (end - index) + DEST_PAD;
dest = growBuffer(dest, destIndex, destLength);
}
// If we have skipped any characters, we need to copy them now.
if (charsSkipped > 0) {
s.getChars(unescapedChunkStart, index, dest, destIndex);
destIndex += charsSkipped;
}
if (escaped.length > 0) {
System.arraycopy(escaped, 0, dest, destIndex, escaped.length);
destIndex += escaped.length;
}
// If we dealt with an escaped character, reset the unescaped range.
unescapedChunkStart = nextIndex;
}
index = nextEscapeIndex(s, nextIndex, end);
}
// Process trailing unescaped characters - no need to account for escaped
// length or padding the allocation.
int charsSkipped = end - unescapedChunkStart;
if (charsSkipped > 0) {
int endIndex = destIndex + charsSkipped;
if (dest.length < endIndex) {
dest = growBuffer(dest, destIndex, endIndex);
}
s.getChars(unescapedChunkStart, end, dest, destIndex);
destIndex = endIndex;
}
return new String(dest, 0, destIndex);
}
/**
* Returns the Unicode code point of the character at the given index.
*
* <p>
* Unlike {@link Character#codePointAt(CharSequence, int)} or
* {@link String#codePointAt(int)} this method will never fail silently when
* encountering an invalid surrogate pair.
*
* <p>
* The behaviour of this method is as follows:
* <ol>
* <li>If {@code index >= end}, {@link IndexOutOfBoundsException} is thrown.
* <li><b>If the character at the specified index is not a surrogate, it is
* returned.</b>
* <li>If the first character was a high surrogate value, then an attempt is
* made to read the next character.
* <ol>
* <li><b>If the end of the sequence was reached, the negated value of the
* trailing high surrogate is returned.</b>
* <li><b>If the next character was a valid low surrogate, the code point value
* of the high/low surrogate pair is returned.</b>
* <li>If the next character was not a low surrogate value, then
* {@link IllegalArgumentException} is thrown.
* </ol>
* <li>If the first character was a low surrogate value,
* {@link IllegalArgumentException} is thrown.
* </ol>
*
* @param seq the sequence of characters from which to decode the code point
* @param index the index of the first character to decode
* @param end the index beyond the last valid character to decode
* @return the Unicode code point for the given index or the negated value of
* the trailing high surrogate character at the end of the sequence
*/
protected static int codePointAt(CharSequence seq, int index, int end) {
checkNotNull(seq);
if (index < end) {
char c1 = seq.charAt(index++);
if (c1 < Character.MIN_HIGH_SURROGATE || c1 > Character.MAX_LOW_SURROGATE) {
// Fast path (first test is probably all we need to do)
return c1;
} else if (c1 <= Character.MAX_HIGH_SURROGATE) {
// If the high surrogate was the last character, return its inverse
if (index == end) {
return -c1;
}
// Otherwise look for the low surrogate following it
char c2 = seq.charAt(index);
if (Character.isLowSurrogate(c2)) {
return Character.toCodePoint(c1, c2);
}
throw new IllegalArgumentException("Expected low surrogate but got char '" + c2 + "' with value "
+ (int) c2 + " at index " + index + " in '" + seq + "'");
} else {
throw new IllegalArgumentException("Unexpected low surrogate character '" + c1 + "' with value "
+ (int) c1 + " at index " + (index - 1) + " in '" + seq + "'");
}
}
throw new IndexOutOfBoundsException("Index exceeds specified range");
}
/**
* Helper method to grow the character buffer as needed, this only happens once
* in a while so it's ok if it's in a method call. If the index passed in is 0
* then no copying will be done.
*/
private static char[] growBuffer(char[] dest, int index, int size) {
char[] copy = new char[size];
if (index > 0) {
System.arraycopy(dest, 0, copy, 0, index);
}
return copy;
}
}

35
sources/main/java/com/google/common/escape/package-info.java Normal file
View File

@ -0,0 +1,35 @@
/*
* Copyright (C) 2012 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.
*/
/**
* Interfaces, utilities, and simple implementations of escapers and encoders.
* The primary type is {@link com.google.common.escape.Escaper}.
*
* <p>
* Additional escapers implementations are found in the applicable packages:
* {@link com.google.common.html.HtmlEscapers} in
* {@code com.google.common.html}, {@link com.google.common.xml.XmlEscapers} in
* {@code com.google.common.xml}, and {@link com.google.common.net.UrlEscapers}
* in {@code com.google.common.net}.
*
* <p>
* This package is a part of the open-source
* <a href="http://guava-libraries.googlecode.com">Guava libraries</a>.
*/
@ParametersAreNonnullByDefault
package com.google.common.escape;
import javax.annotation.ParametersAreNonnullByDefault;