For example, an XML escaper would convert the literal string {@code "Foo An {@code Escaper} instance is required to be stateless, and safe when used concurrently bymultiple threads. 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. 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. 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
| |