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