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    *      http://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;
18  
19  /**
20   * Operations on {@link CharSequence} that are
21   * {@code null} safe.
22   *
23   * @see CharSequence
24   * @since 3.0
25   */
26  public class CharSequenceUtils {
27  
28      private static final int NOT_FOUND = -1;
29  
30      static final int TO_STRING_LIMIT = 16;
31  
32      private static boolean checkLaterThan1(final CharSequence cs, final CharSequence searchChar, final int len2, final int start1) {
33          for (int i = 1, j = len2 - 1; i <= j; i++, j--) {
34              if (cs.charAt(start1 + i) != searchChar.charAt(i) || cs.charAt(start1 + j) != searchChar.charAt(j)) {
35                  return false;
36              }
37          }
38          return true;
39      }
40  
41      /**
42       * Used by the indexOf(CharSequence methods) as a green implementation of indexOf.
43       *
44       * @param cs the {@link CharSequence} to be processed
45       * @param searchChar the {@link CharSequence} to be searched for
46       * @param start the start index
47       * @return the index where the search sequence was found
48       */
49      static int indexOf(final CharSequence cs, final CharSequence searchChar, final int start) {
50          if (cs instanceof String) {
51              return ((String) cs).indexOf(searchChar.toString(), start);
52          }
53          if (cs instanceof StringBuilder) {
54              return ((StringBuilder) cs).indexOf(searchChar.toString(), start);
55          }
56          if (cs instanceof StringBuffer) {
57              return ((StringBuffer) cs).indexOf(searchChar.toString(), start);
58          }
59          return cs.toString().indexOf(searchChar.toString(), start);
60  //        if (cs instanceof String && searchChar instanceof String) {
61  //            // TODO: Do we assume searchChar is usually relatively small;
62  //            //       If so then calling toString() on it is better than reverting to
63  //            //       the green implementation in the else block
64  //            return ((String) cs).indexOf((String) searchChar, start);
65  //        } else {
66  //            // TODO: Implement rather than convert to String
67  //            return cs.toString().indexOf(searchChar.toString(), start);
68  //        }
69      }
70  
71      /**
72       * Returns the index within {@code cs} of the first occurrence of the
73       * specified character, starting the search at the specified index.
74       * <p>
75       * If a character with value {@code searchChar} occurs in the
76       * character sequence represented by the {@code cs}
77       * object at an index no smaller than {@code start}, then
78       * the index of the first such occurrence is returned. For values
79       * of {@code searchChar} in the range from 0 to 0xFFFF (inclusive),
80       * this is the smallest value <em>k</em> such that:
81       * </p>
82       * <blockquote><pre>
83       * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= start)
84       * </pre></blockquote>
85       * is true. For other values of {@code searchChar}, it is the
86       * smallest value <em>k</em> such that:
87       * <blockquote><pre>
88       * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= start)
89       * </pre></blockquote>
90       * <p>
91       * is true. In either case, if no such character occurs inm {@code cs}
92       * at or after position {@code start}, then
93       * {@code -1} is returned.
94       * </p>
95       * <p>
96       * There is no restriction on the value of {@code start}. If it
97       * is negative, it has the same effect as if it were zero: the entire
98       * {@link CharSequence} may be searched. If it is greater than
99       * the length of {@code cs}, it has the same effect as if it were
100      * equal to the length of {@code cs}: {@code -1} is returned.
101      * </p>
102      * <p>All indices are specified in {@code char} values
103      * (Unicode code units).
104      * </p>
105      *
106      * @param cs  the {@link CharSequence} to be processed, not null
107      * @param searchChar  the char to be searched for
108      * @param start  the start index, negative starts at the string start
109      * @return the index where the search char was found, -1 if not found
110      * @since 3.6 updated to behave more like {@link String}
111      */
112     static int indexOf(final CharSequence cs, final int searchChar, int start) {
113         if (cs instanceof String) {
114             return ((String) cs).indexOf(searchChar, start);
115         }
116         final int sz = cs.length();
117         if (start < 0) {
118             start = 0;
119         }
120         if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
121             for (int i = start; i < sz; i++) {
122                 if (cs.charAt(i) == searchChar) {
123                     return i;
124                 }
125             }
126             return NOT_FOUND;
127         }
128         //supplementary characters (LANG1300)
129         if (searchChar <= Character.MAX_CODE_POINT) {
130             final char[] chars = Character.toChars(searchChar);
131             for (int i = start; i < sz - 1; i++) {
132                 final char high = cs.charAt(i);
133                 final char low = cs.charAt(i + 1);
134                 if (high == chars[0] && low == chars[1]) {
135                     return i;
136                 }
137             }
138         }
139         return NOT_FOUND;
140     }
141 
142     /**
143      * Used by the lastIndexOf(CharSequence methods) as a green implementation of lastIndexOf
144      *
145      * @param cs the {@link CharSequence} to be processed
146      * @param searchChar the {@link CharSequence} to find
147      * @param start the start index
148      * @return the index where the search sequence was found
149      */
150     static int lastIndexOf(final CharSequence cs, final CharSequence searchChar, int start) {
151         if (searchChar == null || cs == null) {
152             return NOT_FOUND;
153         }
154         if (searchChar instanceof String) {
155             if (cs instanceof String) {
156                 return ((String) cs).lastIndexOf((String) searchChar, start);
157             }
158             if (cs instanceof StringBuilder) {
159                 return ((StringBuilder) cs).lastIndexOf((String) searchChar, start);
160             }
161             if (cs instanceof StringBuffer) {
162                 return ((StringBuffer) cs).lastIndexOf((String) searchChar, start);
163             }
164         }
165 
166         final int len1 = cs.length();
167         final int len2 = searchChar.length();
168 
169         if (start > len1) {
170             start = len1;
171         }
172 
173         if (start < 0 || len2 > len1) {
174             return NOT_FOUND;
175         }
176 
177         if (len2 == 0) {
178             return start;
179         }
180 
181         if (len2 <= TO_STRING_LIMIT) {
182             if (cs instanceof String) {
183                 return ((String) cs).lastIndexOf(searchChar.toString(), start);
184             }
185             if (cs instanceof StringBuilder) {
186                 return ((StringBuilder) cs).lastIndexOf(searchChar.toString(), start);
187             }
188             if (cs instanceof StringBuffer) {
189                 return ((StringBuffer) cs).lastIndexOf(searchChar.toString(), start);
190             }
191         }
192 
193         if (start + len2 > len1) {
194             start = len1 - len2;
195         }
196 
197         final char char0 = searchChar.charAt(0);
198 
199         int i = start;
200         while (true) {
201             while (cs.charAt(i) != char0) {
202                 i--;
203                 if (i < 0) {
204                     return NOT_FOUND;
205                 }
206             }
207             if (checkLaterThan1(cs, searchChar, len2, i)) {
208                 return i;
209             }
210             i--;
211             if (i < 0) {
212                 return NOT_FOUND;
213             }
214         }
215     }
216 
217     /**
218      * Returns the index within {@code cs} of the last occurrence of
219      * the specified character, searching backward starting at the
220      * specified index. For values of {@code searchChar} in the range
221      * from 0 to 0xFFFF (inclusive), the index returned is the largest
222      * value <em>k</em> such that:
223      * <blockquote><pre>
224      * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= start)
225      * </pre></blockquote>
226      * is true. For other values of {@code searchChar}, it is the
227      * largest value <em>k</em> such that:
228      * <blockquote><pre>
229      * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= start)
230      * </pre></blockquote>
231      * is true. In either case, if no such character occurs in {@code cs}
232      * at or before position {@code start}, then {@code -1} is returned.
233      *
234      * <p>
235      * All indices are specified in {@code char} values
236      * (Unicode code units).
237      * </p>
238      *
239      * @param cs  the {@link CharSequence} to be processed
240      * @param searchChar  the char to be searched for
241      * @param start  the start index, negative returns -1, beyond length starts at end
242      * @return the index where the search char was found, -1 if not found
243      * @since 3.6 updated to behave more like {@link String}
244      */
245     static int lastIndexOf(final CharSequence cs, final int searchChar, int start) {
246         if (cs instanceof String) {
247             return ((String) cs).lastIndexOf(searchChar, start);
248         }
249         final int sz = cs.length();
250         if (start < 0) {
251             return NOT_FOUND;
252         }
253         if (start >= sz) {
254             start = sz - 1;
255         }
256         if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
257             for (int i = start; i >= 0; --i) {
258                 if (cs.charAt(i) == searchChar) {
259                     return i;
260                 }
261             }
262             return NOT_FOUND;
263         }
264         //supplementary characters (LANG1300)
265         //NOTE - we must do a forward traversal for this to avoid duplicating code points
266         if (searchChar <= Character.MAX_CODE_POINT) {
267             final char[] chars = Character.toChars(searchChar);
268             //make sure it's not the last index
269             if (start == sz - 1) {
270                 return NOT_FOUND;
271             }
272             for (int i = start; i >= 0; i--) {
273                 final char high = cs.charAt(i);
274                 final char low = cs.charAt(i + 1);
275                 if (chars[0] == high && chars[1] == low) {
276                     return i;
277                 }
278             }
279         }
280         return NOT_FOUND;
281     }
282 
283     /**
284      * Green implementation of regionMatches.
285      *
286      * @param cs the {@link CharSequence} to be processed
287      * @param ignoreCase whether or not to be case-insensitive
288      * @param thisStart the index to start on the {@code cs} CharSequence
289      * @param substring the {@link CharSequence} to be looked for
290      * @param start the index to start on the {@code substring} CharSequence
291      * @param length character length of the region
292      * @return whether the region matched
293      */
294     static boolean regionMatches(final CharSequence cs, final boolean ignoreCase, final int thisStart,
295             final CharSequence substring, final int start, final int length)    {
296         if (cs instanceof String && substring instanceof String) {
297             return ((String) cs).regionMatches(ignoreCase, thisStart, (String) substring, start, length);
298         }
299         int index1 = thisStart;
300         int index2 = start;
301         int tmpLen = length;
302 
303         // Extract these first so we detect NPEs the same as the java.lang.String version
304         final int srcLen = cs.length() - thisStart;
305         final int otherLen = substring.length() - start;
306 
307         // Check for invalid parameters
308         if (thisStart < 0 || start < 0 || length < 0) {
309             return false;
310         }
311 
312         // Check that the regions are long enough
313         if (srcLen < length || otherLen < length) {
314             return false;
315         }
316 
317         while (tmpLen-- > 0) {
318             final char c1 = cs.charAt(index1++);
319             final char c2 = substring.charAt(index2++);
320 
321             if (c1 == c2) {
322                 continue;
323             }
324 
325             if (!ignoreCase) {
326                 return false;
327             }
328 
329             // The real same check as in String.regionMatches():
330             final char u1 = Character.toUpperCase(c1);
331             final char u2 = Character.toUpperCase(c2);
332             if (u1 != u2 && Character.toLowerCase(u1) != Character.toLowerCase(u2)) {
333                 return false;
334             }
335         }
336 
337         return true;
338     }
339 
340     /**
341      * Returns a new {@link CharSequence} that is a subsequence of this
342      * sequence starting with the {@code char} value at the specified index.
343      *
344      * <p>This provides the {@link CharSequence} equivalent to {@link String#substring(int)}.
345      * The length (in {@code char}) of the returned sequence is {@code length() - start},
346      * so if {@code start == end} then an empty sequence is returned.</p>
347      *
348      * @param cs  the specified subsequence, null returns null
349      * @param start  the start index, inclusive, valid
350      * @return a new subsequence, may be null
351      * @throws IndexOutOfBoundsException if {@code start} is negative or if
352      *  {@code start} is greater than {@code length()}
353      */
354     public static CharSequence subSequence(final CharSequence cs, final int start) {
355         return cs == null ? null : cs.subSequence(start, cs.length());
356     }
357 
358     /**
359      * Converts the given CharSequence to a char[].
360      *
361      * @param source the {@link CharSequence} to be processed.
362      * @return the resulting char array, never null.
363      * @since 3.11
364      */
365     public static char[] toCharArray(final CharSequence source) {
366         final int len = StringUtils.length(source);
367         if (len == 0) {
368             return ArrayUtils.EMPTY_CHAR_ARRAY;
369         }
370         if (source instanceof String) {
371             return ((String) source).toCharArray();
372         }
373         final char[] array = new char[len];
374         for (int i = 0; i < len; i++) {
375             array[i] = source.charAt(i);
376         }
377         return array;
378     }
379 
380     /**
381      * {@link CharSequenceUtils} instances should NOT be constructed in
382      * standard programming.
383      *
384      * <p>This constructor is public to permit tools that require a JavaBean
385      * instance to operate.</p>
386      *
387      * @deprecated TODO Make private in 4.0.
388      */
389     @Deprecated
390     public CharSequenceUtils() {
391         // empty
392     }
393 }