mirror of
https://github.com/Eaglercraft-Archive/Eaglercraftx-1.8.8-src.git
synced 2025-06-28 02:48:14 -05:00
Update #0 - First Release
This commit is contained in:
LAX1DUDE
320
sources/main/java/com/google/common/escape/UnicodeEscaper.java
Normal file
320
sources/main/java/com/google/common/escape/UnicodeEscaper.java
Normal 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<Bar>"} 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;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user