View Javadoc
1   /*
2    * Copyright (C) 2010 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.base;
16  
17  import static com.google.common.base.Preconditions.checkArgument;
18  import static com.google.common.base.Preconditions.checkNotNull;
19  
20  import com.google.common.annotations.GwtCompatible;
21  
22  /**
23   * Static methods pertaining to ASCII characters (those in the range of values {@code 0x00} through
24   * {@code 0x7F}), and to strings containing such characters.
25   *
26   * <p>ASCII utilities also exist in other classes of this package:
27   * <ul>
28   * <!-- TODO(kevinb): how can we make this not produce a warning when building gwt javadoc? -->
29   * <li>{@link Charsets#US_ASCII} specifies the {@code Charset} of ASCII characters.
30   * <li>{@link CharMatcher#ascii} matches ASCII characters and provides text processing methods which
31   * operate only on the ASCII characters of a string.
32   * </ul>
33   *
34   * @author Craig Berry
35   * @author Gregory Kick
36   * @since 7.0
37   */
38  @GwtCompatible
39  public final class Ascii {
40  
41    private Ascii() {}
42  
43    /* The ASCII control characters, per RFC 20. */
44    /**
45     * Null ('\0'): The all-zeros character which may serve to accomplish time fill and media fill.
46     * Normally used as a C string terminator.
47     *
48     * <p>Although RFC 20 names this as "Null", note that it is distinct from the C/C++ "NULL"
49     * pointer.
50     *
51     * @since 8.0
52     */
53    public static final byte NUL = 0;
54  
55    /**
56     * Start of Heading: A communication control character used at the beginning of a sequence of
57     * characters which constitute a machine-sensible address or routing information. Such a sequence
58     * is referred to as the "heading." An STX character has the effect of terminating a heading.
59     *
60     * @since 8.0
61     */
62    public static final byte SOH = 1;
63  
64    /**
65     * Start of Text: A communication control character which precedes a sequence of characters that
66     * is to be treated as an entity and entirely transmitted through to the ultimate destination.
67     * Such a sequence is referred to as "text." STX may be used to terminate a sequence of characters
68     * started by SOH.
69     *
70     * @since 8.0
71     */
72    public static final byte STX = 2;
73  
74    /**
75     * End of Text: A communication control character used to terminate a sequence of characters
76     * started with STX and transmitted as an entity.
77     *
78     * @since 8.0
79     */
80    public static final byte ETX = 3;
81  
82    /**
83     * End of Transmission: A communication control character used to indicate the conclusion of a
84     * transmission, which may have contained one or more texts and any associated headings.
85     *
86     * @since 8.0
87     */
88    public static final byte EOT = 4;
89  
90    /**
91     * Enquiry: A communication control character used in data communication systems as a request for
92     * a response from a remote station. It may be used as a "Who Are You" (WRU) to obtain
93     * identification, or may be used to obtain station status, or both.
94     *
95     * @since 8.0
96     */
97    public static final byte ENQ = 5;
98  
99    /**
100    * Acknowledge: A communication control character transmitted by a receiver as an affirmative
101    * response to a sender.
102    *
103    * @since 8.0
104    */
105   public static final byte ACK = 6;
106 
107   /**
108    * Bell ('\a'): A character for use when there is a need to call for human attention. It may
109    * control alarm or attention devices.
110    *
111    * @since 8.0
112    */
113   public static final byte BEL = 7;
114 
115   /**
116    * Backspace ('\b'): A format effector which controls the movement of the printing position one
117    * printing space backward on the same printing line. (Applicable also to display devices.)
118    *
119    * @since 8.0
120    */
121   public static final byte BS = 8;
122 
123   /**
124    * Horizontal Tabulation ('\t'): A format effector which controls the movement of the printing
125    * position to the next in a series of predetermined positions along the printing line.
126    * (Applicable also to display devices and the skip function on punched cards.)
127    *
128    * @since 8.0
129    */
130   public static final byte HT = 9;
131 
132   /**
133    * Line Feed ('\n'): A format effector which controls the movement of the printing position to the
134    * next printing line. (Applicable also to display devices.) Where appropriate, this character may
135    * have the meaning "New Line" (NL), a format effector which controls the movement of the printing
136    * point to the first printing position on the next printing line. Use of this convention requires
137    * agreement between sender and recipient of data.
138    *
139    * @since 8.0
140    */
141   public static final byte LF = 10;
142 
143   /**
144    * Alternate name for {@link #LF}. ({@code LF} is preferred.)
145    *
146    * @since 8.0
147    */
148   public static final byte NL = 10;
149 
150   /**
151    * Vertical Tabulation ('\v'): A format effector which controls the movement of the printing
152    * position to the next in a series of predetermined printing lines. (Applicable also to display
153    * devices.)
154    *
155    * @since 8.0
156    */
157   public static final byte VT = 11;
158 
159   /**
160    * Form Feed ('\f'): A format effector which controls the movement of the printing position to the
161    * first pre-determined printing line on the next form or page. (Applicable also to display
162    * devices.)
163    *
164    * @since 8.0
165    */
166   public static final byte FF = 12;
167 
168   /**
169    * Carriage Return ('\r'): A format effector which controls the movement of the printing position
170    * to the first printing position on the same printing line. (Applicable also to display devices.)
171    *
172    * @since 8.0
173    */
174   public static final byte CR = 13;
175 
176   /**
177    * Shift Out: A control character indicating that the code combinations which follow shall be
178    * interpreted as outside of the character set of the standard code table until a Shift In
179    * character is reached.
180    *
181    * @since 8.0
182    */
183   public static final byte SO = 14;
184 
185   /**
186    * Shift In: A control character indicating that the code combinations which follow shall be
187    * interpreted according to the standard code table.
188    *
189    * @since 8.0
190    */
191   public static final byte SI = 15;
192 
193   /**
194    * Data Link Escape: A communication control character which will change the meaning of a limited
195    * number of contiguously following characters. It is used exclusively to provide supplementary
196    * controls in data communication networks.
197    *
198    * @since 8.0
199    */
200   public static final byte DLE = 16;
201 
202   /**
203    * Device Control 1. Characters for the control of ancillary devices associated with data
204    * processing or telecommunication systems, more especially switching devices "on" or "off." (If a
205    * single "stop" control is required to interrupt or turn off ancillary devices, DC4 is the
206    * preferred assignment.)
207    *
208    * @since 8.0
209    */
210   public static final byte DC1 = 17; // aka XON
211 
212   /**
213    * Transmission On: Although originally defined as DC1, this ASCII control character is now better
214    * known as the XON code used for software flow control in serial communications. The main use is
215    * restarting the transmission after the communication has been stopped by the XOFF control code.
216    *
217    * @since 8.0
218    */
219   public static final byte XON = 17; // aka DC1
220 
221   /**
222    * Device Control 2. Characters for the control of ancillary devices associated with data
223    * processing or telecommunication systems, more especially switching devices "on" or "off." (If a
224    * single "stop" control is required to interrupt or turn off ancillary devices, DC4 is the
225    * preferred assignment.)
226    *
227    * @since 8.0
228    */
229   public static final byte DC2 = 18;
230 
231   /**
232    * Device Control 3. Characters for the control of ancillary devices associated with data
233    * processing or telecommunication systems, more especially switching devices "on" or "off." (If a
234    * single "stop" control is required to interrupt or turn off ancillary devices, DC4 is the
235    * preferred assignment.)
236    *
237    * @since 8.0
238    */
239   public static final byte DC3 = 19; // aka XOFF
240 
241   /**
242    * Transmission off. See {@link #XON} for explanation.
243    *
244    * @since 8.0
245    */
246   public static final byte XOFF = 19; // aka DC3
247 
248   /**
249    * Device Control 4. Characters for the control of ancillary devices associated with data
250    * processing or telecommunication systems, more especially switching devices "on" or "off." (If a
251    * single "stop" control is required to interrupt or turn off ancillary devices, DC4 is the
252    * preferred assignment.)
253    *
254    * @since 8.0
255    */
256   public static final byte DC4 = 20;
257 
258   /**
259    * Negative Acknowledge: A communication control character transmitted by a receiver as a negative
260    * response to the sender.
261    *
262    * @since 8.0
263    */
264   public static final byte NAK = 21;
265 
266   /**
267    * Synchronous Idle: A communication control character used by a synchronous transmission system
268    * in the absence of any other character to provide a signal from which synchronism may be
269    * achieved or retained.
270    *
271    * @since 8.0
272    */
273   public static final byte SYN = 22;
274 
275   /**
276    * End of Transmission Block: A communication control character used to indicate the end of a
277    * block of data for communication purposes. ETB is used for blocking data where the block
278    * structure is not necessarily related to the processing format.
279    *
280    * @since 8.0
281    */
282   public static final byte ETB = 23;
283 
284   /**
285    * Cancel: A control character used to indicate that the data with which it is sent is in error or
286    * is to be disregarded.
287    *
288    * @since 8.0
289    */
290   public static final byte CAN = 24;
291 
292   /**
293    * End of Medium: A control character associated with the sent data which may be used to identify
294    * the physical end of the medium, or the end of the used, or wanted, portion of information
295    * recorded on a medium. (The position of this character does not necessarily correspond to the
296    * physical end of the medium.)
297    *
298    * @since 8.0
299    */
300   public static final byte EM = 25;
301 
302   /**
303    * Substitute: A character that may be substituted for a character which is determined to be
304    * invalid or in error.
305    *
306    * @since 8.0
307    */
308   public static final byte SUB = 26;
309 
310   /**
311    * Escape: A control character intended to provide code extension (supplementary characters) in
312    * general information interchange. The Escape character itself is a prefix affecting the
313    * interpretation of a limited number of contiguously following characters.
314    *
315    * @since 8.0
316    */
317   public static final byte ESC = 27;
318 
319   /**
320    * File Separator: These four information separators may be used within data in optional fashion,
321    * except that their hierarchical relationship shall be: FS is the most inclusive, then GS, then
322    * RS, and US is least inclusive. (The content and length of a File, Group, Record, or Unit are
323    * not specified.)
324    *
325    * @since 8.0
326    */
327   public static final byte FS = 28;
328 
329   /**
330    * Group Separator: These four information separators may be used within data in optional fashion,
331    * except that their hierarchical relationship shall be: FS is the most inclusive, then GS, then
332    * RS, and US is least inclusive. (The content and length of a File, Group, Record, or Unit are
333    * not specified.)
334    *
335    * @since 8.0
336    */
337   public static final byte GS = 29;
338 
339   /**
340    * Record Separator: These four information separators may be used within data in optional
341    * fashion, except that their hierarchical relationship shall be: FS is the most inclusive, then
342    * GS, then RS, and US is least inclusive. (The content and length of a File, Group, Record, or
343    * Unit are not specified.)
344    *
345    * @since 8.0
346    */
347   public static final byte RS = 30;
348 
349   /**
350    * Unit Separator: These four information separators may be used within data in optional fashion,
351    * except that their hierarchical relationship shall be: FS is the most inclusive, then GS, then
352    * RS, and US is least inclusive. (The content and length of a File, Group, Record, or Unit are
353    * not specified.)
354    *
355    * @since 8.0
356    */
357   public static final byte US = 31;
358 
359   /**
360    * Space: A normally non-printing graphic character used to separate words. It is also a format
361    * effector which controls the movement of the printing position, one printing position forward.
362    * (Applicable also to display devices.)
363    *
364    * @since 8.0
365    */
366   public static final byte SP = 32;
367 
368   /**
369    * Alternate name for {@link #SP}.
370    *
371    * @since 8.0
372    */
373   public static final byte SPACE = 32;
374 
375   /**
376    * Delete: This character is used primarily to "erase" or "obliterate" erroneous or unwanted
377    * characters in perforated tape.
378    *
379    * @since 8.0
380    */
381   public static final byte DEL = 127;
382 
383   /**
384    * The minimum value of an ASCII character.
385    *
386    * @since 9.0 (was type {@code int} before 12.0)
387    */
388   public static final char MIN = 0;
389 
390   /**
391    * The maximum value of an ASCII character.
392    *
393    * @since 9.0 (was type {@code int} before 12.0)
394    */
395   public static final char MAX = 127;
396 
397   /**
398    * Returns a copy of the input string in which all {@linkplain #isUpperCase(char) uppercase ASCII
399    * characters} have been converted to lowercase. All other characters are copied without
400    * modification.
401    */
402   public static String toLowerCase(String string) {
403     int length = string.length();
404     for (int i = 0; i < length; i++) {
405       if (isUpperCase(string.charAt(i))) {
406         char[] chars = string.toCharArray();
407         for (; i < length; i++) {
408           char c = chars[i];
409           if (isUpperCase(c)) {
410             chars[i] = (char) (c ^ 0x20);
411           }
412         }
413         return String.valueOf(chars);
414       }
415     }
416     return string;
417   }
418 
419   /**
420    * Returns a copy of the input character sequence in which all {@linkplain #isUpperCase(char)
421    * uppercase ASCII characters} have been converted to lowercase. All other characters are copied
422    * without modification.
423    *
424    * @since 14.0
425    */
426   public static String toLowerCase(CharSequence chars) {
427     if (chars instanceof String) {
428       return toLowerCase((String) chars);
429     }
430     char[] newChars = new char[chars.length()];
431     for (int i = 0; i < newChars.length; i++) {
432       newChars[i] = toLowerCase(chars.charAt(i));
433     }
434     return String.valueOf(newChars);
435   }
436 
437   /**
438    * If the argument is an {@linkplain #isUpperCase(char) uppercase ASCII character} returns the
439    * lowercase equivalent. Otherwise returns the argument.
440    */
441   public static char toLowerCase(char c) {
442     return isUpperCase(c) ? (char) (c ^ 0x20) : c;
443   }
444 
445   /**
446    * Returns a copy of the input string in which all {@linkplain #isLowerCase(char) lowercase ASCII
447    * characters} have been converted to uppercase. All other characters are copied without
448    * modification.
449    */
450   public static String toUpperCase(String string) {
451     int length = string.length();
452     for (int i = 0; i < length; i++) {
453       if (isLowerCase(string.charAt(i))) {
454         char[] chars = string.toCharArray();
455         for (; i < length; i++) {
456           char c = chars[i];
457           if (isLowerCase(c)) {
458             chars[i] = (char) (c & 0x5f);
459           }
460         }
461         return String.valueOf(chars);
462       }
463     }
464     return string;
465   }
466 
467   /**
468    * Returns a copy of the input character sequence in which all {@linkplain #isLowerCase(char)
469    * lowercase ASCII characters} have been converted to uppercase. All other characters are copied
470    * without modification.
471    *
472    * @since 14.0
473    */
474   public static String toUpperCase(CharSequence chars) {
475     if (chars instanceof String) {
476       return toUpperCase((String) chars);
477     }
478     char[] newChars = new char[chars.length()];
479     for (int i = 0; i < newChars.length; i++) {
480       newChars[i] = toUpperCase(chars.charAt(i));
481     }
482     return String.valueOf(newChars);
483   }
484 
485   /**
486    * If the argument is a {@linkplain #isLowerCase(char) lowercase ASCII character} returns the
487    * uppercase equivalent. Otherwise returns the argument.
488    */
489   public static char toUpperCase(char c) {
490     return isLowerCase(c) ? (char) (c & 0x5f) : c;
491   }
492 
493   /**
494    * Indicates whether {@code c} is one of the twenty-six lowercase ASCII alphabetic characters
495    * between {@code 'a'} and {@code 'z'} inclusive. All others (including non-ASCII characters)
496    * return {@code false}.
497    */
498   public static boolean isLowerCase(char c) {
499     // Note: This was benchmarked against the alternate expression "(char)(c - 'a') < 26" (Nov '13)
500     // and found to perform at least as well, or better.
501     return (c >= 'a') && (c <= 'z');
502   }
503 
504   /**
505    * Indicates whether {@code c} is one of the twenty-six uppercase ASCII alphabetic characters
506    * between {@code 'A'} and {@code 'Z'} inclusive. All others (including non-ASCII characters)
507    * return {@code false}.
508    */
509   public static boolean isUpperCase(char c) {
510     return (c >= 'A') && (c <= 'Z');
511   }
512 
513   /**
514    * Truncates the given character sequence to the given maximum length. If the length of the
515    * sequence is greater than {@code maxLength}, the returned string will be exactly
516    * {@code maxLength} chars in length and will end with the given {@code truncationIndicator}.
517    * Otherwise, the sequence will be returned as a string with no changes to the content.
518    *
519    * <p>Examples:
520    *
521    * <pre>   {@code
522    *   Ascii.truncate("foobar", 7, "..."); // returns "foobar"
523    *   Ascii.truncate("foobar", 5, "..."); // returns "fo..." }</pre>
524    *
525    * <p><b>Note:</b> This method <i>may</i> work with certain non-ASCII text but is not safe for use
526    * with arbitrary Unicode text. It is mostly intended for use with text that is known to be safe
527    * for use with it (such as all-ASCII text) and for simple debugging text. When using this method,
528    * consider the following:
529    *
530    * <ul>
531    * <li>it may split surrogate pairs
532    * <li>it may split characters and combining characters
533    * <li>it does not consider word boundaries
534    * <li>if truncating for display to users, there are other considerations that must be taken into
535    *     account
536    * <li>the appropriate truncation indicator may be locale-dependent
537    * <li>it is safe to use non-ASCII characters in the truncation indicator
538    * </ul>
539    *
540    *
541    * @throws IllegalArgumentException if {@code maxLength} is less than the length of
542    *     {@code truncationIndicator}
543    * @since 16.0
544    */
545   public static String truncate(CharSequence seq, int maxLength, String truncationIndicator) {
546     checkNotNull(seq);
547 
548     // length to truncate the sequence to, not including the truncation indicator
549     int truncationLength = maxLength - truncationIndicator.length();
550 
551     // in this worst case, this allows a maxLength equal to the length of the truncationIndicator,
552     // meaning that a string will be truncated to just the truncation indicator itself
553     checkArgument(
554         truncationLength >= 0,
555         "maxLength (%s) must be >= length of the truncation indicator (%s)",
556         maxLength,
557         truncationIndicator.length());
558 
559     if (seq.length() <= maxLength) {
560       String string = seq.toString();
561       if (string.length() <= maxLength) {
562         return string;
563       }
564       // if the length of the toString() result was > maxLength for some reason, truncate that
565       seq = string;
566     }
567 
568     return new StringBuilder(maxLength)
569         .append(seq, 0, truncationLength)
570         .append(truncationIndicator)
571         .toString();
572   }
573 
574   /**
575    * Indicates whether the contents of the given character sequences {@code s1} and {@code s2} are
576    * equal, ignoring the case of any ASCII alphabetic characters between {@code 'a'} and {@code 'z'}
577    * or {@code 'A'} and {@code 'Z'} inclusive.
578    *
579    * <p>This method is significantly faster than {@link String#equalsIgnoreCase} and should be used
580    * in preference if at least one of the parameters is known to contain only ASCII characters.
581    *
582    * <p>Note however that this method does not always behave identically to expressions such as:
583    * <ul>
584    * <li>{@code string.toUpperCase().equals("UPPER CASE ASCII")}
585    * <li>{@code string.toLowerCase().equals("lower case ascii")}
586    * </ul>
587    * <p>due to case-folding of some non-ASCII characters (which does not occur in
588    * {@link String#equalsIgnoreCase}). However in almost all cases that ASCII strings are used, the
589    * author probably wanted the behavior provided by this method rather than the subtle and
590    * sometimes surprising behavior of {@code toUpperCase()} and {@code toLowerCase()}.
591    *
592    * @since 16.0
593    */
594   public static boolean equalsIgnoreCase(CharSequence s1, CharSequence s2) {
595     // Calling length() is the null pointer check (so do it before we can exit early).
596     int length = s1.length();
597     if (s1 == s2) {
598       return true;
599     }
600     if (length != s2.length()) {
601       return false;
602     }
603     for (int i = 0; i < length; i++) {
604       char c1 = s1.charAt(i);
605       char c2 = s2.charAt(i);
606       if (c1 == c2) {
607         continue;
608       }
609       int alphaIndex = getAlphaIndex(c1);
610       // This was also benchmarked using '&' to avoid branching (but always evaluate the rhs),
611       // however this showed no obvious improvement.
612       if (alphaIndex < 26 && alphaIndex == getAlphaIndex(c2)) {
613         continue;
614       }
615       return false;
616     }
617     return true;
618   }
619 
620   /**
621    * Returns the non-negative index value of the alpha character {@code c}, regardless of case. Ie,
622    * 'a'/'A' returns 0 and 'z'/'Z' returns 25. Non-alpha characters return a value of 26 or greater.
623    */
624   private static int getAlphaIndex(char c) {
625     // Fold upper-case ASCII to lower-case and make zero-indexed and unsigned (by casting to char).
626     return (char) ((c | 0x20) - 'a');
627   }
628 }