* 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
* 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.
For example, an XML escaper would convert the literal string
"Foo<Bar>" to prevent
"<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
Escaper instance is required to be stateless, and safe when used concurrently by
Because, in general, escaping operates on the code points of a string and not on its
char values, it is not safe to assume that
escape(s) is equivalent to
escape(s.substring(0, n)) + escape(s.substing(n)) for arbitrary
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
java.lang.Character.isHighSurrogate(char) pairs, or by starting
with short strings already known to be free of unpaired surrogates.
The two primary implementations of this interface are
. 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.
Several popular escapers are defined as constants in classes like
. To create your own escapers, use
, or extend
// TODO(user): evaluate custom implementations, considering package private constructor.
Note that this method may treat input characters differently depending on the specific escaper implementation.
handles correctly, including surrogate character pairs. If the input is badly formed the escaper should throw
handles Java characters independently and does not verify the input for well formed characters. A
CharEscapershould not be used in situations where input is not guaranteed to be restricted to the Basic Multilingual Plane (BMP).