View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.text.translate;
18  
19  import java.io.IOException;
20  import java.io.Writer;
21  
22  import org.apache.commons.lang3.StringUtils;
23  
24  /**
25   * Translates code points to their Unicode escaped value.
26   *
27   * @since 3.0
28   * @deprecated As of <a href="https://commons.apache.org/proper/commons-lang/changes-report.html#a3.6">3.6</a>, use Apache Commons Text
29   * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/translate/UnicodeEscaper.html">
30   * UnicodeEscaper</a>.
31   */
32  @Deprecated
33  public class UnicodeEscaper extends CodePointTranslator {
34  
35      /**
36       * Constructs a {@link UnicodeEscaper} above the specified value (exclusive).
37       *
38       * @param codePoint above which to escape.
39       * @return The newly created {@link UnicodeEscaper} instance.
40       */
41      public static UnicodeEscaper above(final int codePoint) {
42          return outsideOf(0, codePoint);
43      }
44  
45      /**
46       * Constructs a {@link UnicodeEscaper} below the specified value (exclusive).
47       *
48       * @param codePoint below which to escape.
49       * @return The newly created {@link UnicodeEscaper} instance.
50       */
51      public static UnicodeEscaper below(final int codePoint) {
52          return outsideOf(codePoint, Integer.MAX_VALUE);
53      }
54  
55      /**
56       * Constructs a {@link UnicodeEscaper} between the specified values (inclusive).
57       *
58       * @param codePointLow above which to escape.
59       * @param codePointHigh below which to escape.
60       * @return The newly created {@link UnicodeEscaper} instance.
61       */
62      public static UnicodeEscaper between(final int codePointLow, final int codePointHigh) {
63          return new UnicodeEscaper(codePointLow, codePointHigh, true);
64      }
65  
66      /**
67       * Constructs a {@link UnicodeEscaper} outside of the specified values (exclusive).
68       *
69       * @param codePointLow below which to escape.
70       * @param codePointHigh above which to escape.
71       * @return The newly created {@link UnicodeEscaper} instance.
72       */
73      public static UnicodeEscaper outsideOf(final int codePointLow, final int codePointHigh) {
74          return new UnicodeEscaper(codePointLow, codePointHigh, false);
75      }
76  
77      private final int below;
78  
79      private final int above;
80  
81      private final boolean between;
82  
83      /**
84       * Constructs a {@link UnicodeEscaper} for all characters.
85       */
86      public UnicodeEscaper() {
87          this(0, Integer.MAX_VALUE, true);
88      }
89  
90      /**
91       * Constructs a {@link UnicodeEscaper} for the specified range. This is
92       * the underlying method for the other constructors/builders. The {@code below}
93       * and {@code above} boundaries are inclusive when {@code between} is
94       * {@code true} and exclusive when it is {@code false}.
95       *
96       * @param below int value representing the lowest code point boundary.
97       * @param above int value representing the highest code point boundary.
98       * @param between whether to escape between the boundaries or outside them.
99       */
100     protected UnicodeEscaper(final int below, final int above, final boolean between) {
101         this.below = below;
102         this.above = above;
103         this.between = between;
104     }
105 
106     /**
107      * Converts the given code point to a hexadecimal string of the form {@code "\\uXXXX"}, or the
108      * surrogate pair form {@code "\\uXXXX\\uXXXX"} for a supplementary code point.
109      *
110      * @param codePoint
111      *            a Unicode code point.
112      * @return The hexadecimal string for the given code point.
113      * @since 3.2
114      */
115     protected String toUtf16Escape(final int codePoint) {
116         if (Character.isBmpCodePoint(codePoint)) {
117             return "\\u" + StringUtils.leftPad(hex(codePoint), 4, '0');
118         }
119         final char[] surrogatePair = Character.toChars(codePoint);
120         return "\\u" + hex(surrogatePair[0]) + "\\u" + hex(surrogatePair[1]);
121     }
122 
123     /**
124      * {@inheritDoc}
125      */
126     @Override
127     public boolean translate(final int codePoint, final Writer out) throws IOException {
128         if (between) {
129             if (codePoint < below || codePoint > above) {
130                 return false;
131             }
132         } else if (codePoint >= below && codePoint <= above) {
133             return false;
134         }
135 
136         // TODO: Handle potential + sign per various Unicode escape implementations
137         if (codePoint > 0xffff) {
138             out.write(toUtf16Escape(codePoint));
139         } else {
140           out.write("\\u");
141           out.write(HEX_DIGITS[codePoint >> 12 & 15]);
142           out.write(HEX_DIGITS[codePoint >> 8 & 15]);
143           out.write(HEX_DIGITS[codePoint >> 4 & 15]);
144           out.write(HEX_DIGITS[codePoint & 15]);
145         }
146         return true;
147     }
148 }