001/*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.base;
018
019import com.google.common.annotations.Beta;
020import com.google.common.annotations.GwtCompatible;
021
022/**
023 * Static methods pertaining to ASCII characters (those in the range of values
024 * {@code 0x00} through {@code 0x7F}), and to strings containing such
025 * characters.
026 *
027 * <p>ASCII utilities also exist in other classes of this package:
028 * <ul>
029 * <li>{@link Charsets#US_ASCII} specifies the {@code Charset} of ASCII characters.
030 * <li>{@link CharMatcher#ASCII} matches ASCII characters and provides text processing methods
031 *     which operate only on the ASCII characters of a string.
032 * </ul>
033 *
034 * @author Craig Berry
035 * @author Gregory Kick
036 * @since 7
037 */
038@GwtCompatible
039public final class Ascii {
040
041  private Ascii() {}
042
043  /* The ASCII control characters, per RFC 20. */
044  /**
045   * Null ('\0'): The all-zeros character which may serve to accomplish
046   * time fill and media fill.  Normally used as a C string terminator.
047   * <p>Although RFC 20 names this as "Null", note that it is distinct
048   * from the C/C++ "NULL" pointer.
049   *
050   * @since 8
051   */
052  public static final byte NUL = 0;
053
054  /**
055   * Start of Heading: A communication control character used at
056   * the beginning of a sequence of characters which constitute a
057   * machine-sensible address or routing information.  Such a sequence is
058   * referred to as the "heading."  An STX character has the effect of
059   * terminating a heading.
060   *
061   * @since 8
062   */
063  public static final byte SOH = 1;
064
065  /**
066   * Start of Text: A communication control character which
067   * precedes a sequence of characters that is to be treated as an entity
068   * and entirely transmitted through to the ultimate destination.  Such a
069   * sequence is referred to as "text."  STX may be used to terminate a
070   * sequence of characters started by SOH.
071   *
072   * @since 8
073   */
074  public static final byte STX = 2;
075
076  /**
077   * End of Text: A communication control character used to
078   * terminate a sequence of characters started with STX and transmitted
079   * as an entity.
080   *
081   * @since 8
082   */
083  public static final byte ETX = 3;
084
085  /**
086   * End of Transmission: A communication control character used
087   * to indicate the conclusion of a transmission, which may have
088   * contained one or more texts and any associated headings.
089   *
090   * @since 8
091   */
092  public static final byte EOT = 4;
093
094  /**
095   * Enquiry: A communication control character used in data
096   * communication systems as a request for a response from a remote
097   * station.  It may be used as a "Who Are You" (WRU) to obtain
098   * identification, or may be used to obtain station status, or both.
099   *
100   * @since 8
101   */
102  public static final byte ENQ = 5;
103
104  /**
105   * Acknowledge: A communication control character transmitted
106   * by a receiver as an affirmative response to a sender.
107   *
108   * @since 8
109   */
110  public static final byte ACK = 6;
111
112  /**
113   * Bell ('\a'): A character for use when there is a need to call for
114   * human attention.  It may control alarm or attention devices.
115   *
116   * @since 8
117   */
118  public static final byte BEL = 7;
119
120  /**
121   * Backspace ('\b'): A format effector which controls the movement of
122   * the printing position one printing space backward on the same
123   * printing line.  (Applicable also to display devices.)
124   *
125   * @since 8
126   */
127  public static final byte BS = 8;
128
129  /**
130   * Horizontal Tabulation ('\t'): A format effector which controls the
131   * movement of the printing position to the next in a series of
132   * predetermined positions along the printing line.  (Applicable also to
133   * display devices and the skip function on punched cards.)
134   *
135   * @since 8
136   */
137  public static final byte HT = 9;
138
139  /**
140   * Line Feed ('\n'): A format effector which controls the movement of
141   * the printing position to the next printing line.  (Applicable also to
142   * display devices.) Where appropriate, this character may have the
143   * meaning "New Line" (NL), a format effector which controls the
144   * movement of the printing point to the first printing position on the
145   * next printing line.  Use of this convention requires agreement
146   * between sender and recipient of data.
147   *
148   * @since 8
149   */
150  public static final byte LF = 10;
151
152  /**
153   * Alternate name for {@link #LF}.  ({@code LF} is preferred.)
154   *
155   * @since 8
156   */
157  public static final byte NL = 10;
158
159  /**
160   * Vertical Tabulation ('\v'): A format effector which controls the
161   * movement of the printing position to the next in a series of
162   * predetermined printing lines.  (Applicable also to display devices.)
163   *
164   * @since 8
165   */
166  public static final byte VT = 11;
167
168  /**
169   * Form Feed ('\f'): A format effector which controls the movement of
170   * the printing position to the first pre-determined printing line on
171   * the next form or page.  (Applicable also to display devices.)
172   *
173   * @since 8
174   */
175  public static final byte FF = 12;
176
177  /**
178   * Carriage Return ('\r'): A format effector which controls the
179   * movement of the printing position to the first printing position on
180   * the same printing line.  (Applicable also to display devices.)
181   *
182   * @since 8
183   */
184  public static final byte CR = 13;
185
186  /**
187   * Shift Out: A control character indicating that the code
188   * combinations which follow shall be interpreted as outside of the
189   * character set of the standard code table until a Shift In character
190   * is reached.
191   *
192   * @since 8
193   */
194  public static final byte SO = 14;
195
196  /**
197   * Shift In: A control character indicating that the code
198   * combinations which follow shall be interpreted according to the
199   * standard code table.
200   *
201   * @since 8
202   */
203  public static final byte SI = 15;
204
205  /**
206   * Data Link Escape: A communication control character which
207   * will change the meaning of a limited number of contiguously following
208   * characters.  It is used exclusively to provide supplementary controls
209   * in data communication networks.
210   *
211   * @since 8
212   */
213  public static final byte DLE = 16;
214
215  /**
216   * Device Controls: Characters for the control
217   * of ancillary devices associated with data processing or
218   * telecommunication systems, more especially switching devices "on" or
219   * "off."  (If a single "stop" control is required to interrupt or turn
220   * off ancillary devices, DC4 is the preferred assignment.)
221   *
222   * @since 8
223   */
224  public static final byte DC1 = 17; // aka XON
225
226  /**
227   * Transmission on/off: Although originally defined as DC1, this ASCII
228   * control character is now better known as the XON code used for software
229   * flow control in serial communications.  The main use is restarting
230   * the transmission after the communication has been stopped by the XOFF
231   * control code.
232   *
233   * @since 8
234   */
235  public static final byte XON = 17; // aka DC1
236
237  /**
238   * @see #DC1
239   *
240   * @since 8
241   */
242  public static final byte DC2 = 18;
243
244  /**
245   * @see #DC1
246   *
247   * @since 8
248   */
249  public static final byte DC3 = 19; // aka XOFF
250
251  /**
252   * Transmission off. @see #XON
253   *
254   * @since 8
255   */
256  public static final byte XOFF = 19; // aka DC3
257
258  /**
259   * @see #DC1
260   *
261   * @since 8
262   */
263  public static final byte DC4 = 20;
264
265  /**
266   * Negative Acknowledge: A communication control character
267   * transmitted by a receiver as a negative response to the sender.
268   *
269   * @since 8
270   */
271  public static final byte NAK = 21;
272
273  /**
274   * Synchronous Idle: A communication control character used by
275   * a synchronous transmission system in the absence of any other
276   * character to provide a signal from which synchronism may be achieved
277   * or retained.
278   *
279   * @since 8
280   */
281  public static final byte SYN = 22;
282
283  /**
284   * End of Transmission Block: A communication control character
285   * used to indicate the end of a block of data for communication
286   * purposes.  ETB is used for blocking data where the block structure is
287   * not necessarily related to the processing format.
288   *
289   * @since 8
290   */
291  public static final byte ETB = 23;
292
293  /**
294   * Cancel: A control character used to indicate that the data
295   * with which it is sent is in error or is to be disregarded.
296   *
297   * @since 8
298   */
299  public static final byte CAN = 24;
300
301  /**
302   * End of Medium: A control character associated with the sent
303   * data which may be used to identify the physical end of the medium, or
304   * the end of the used, or wanted, portion of information recorded on a
305   * medium.  (The position of this character does not necessarily
306   * correspond to the physical end of the medium.)
307   *
308   * @since 8
309   */
310  public static final byte EM = 25;
311
312  /**
313   * Substitute: A character that may be substituted for a
314   * character which is determined to be invalid or in error.
315   *
316   * @since 8
317   */
318  public static final byte SUB = 26;
319
320  /**
321   * Escape: A control character intended to provide code
322   * extension (supplementary characters) in general information
323   * interchange.  The Escape character itself is a prefix affecting the
324   * interpretation of a limited number of contiguously following
325   * characters.
326   *
327   * @since 8
328   */
329  public static final byte ESC = 27;
330
331  /**
332   * File/Group/Record/Unit Separator: These information separators may be
333   * used within data in optional fashion, except that their hierarchical
334   * relationship shall be: FS is the most inclusive, then GS, then RS,
335   * and US is least inclusive.  (The content and length of a File, Group,
336   * Record, or Unit are not specified.)
337   *
338   * @since 8
339   */
340  public static final byte FS = 28;
341
342  /**
343   * @see #FS
344   *
345   * @since 8
346   */
347  public static final byte GS = 29;
348
349  /**
350   * @see #FS
351   *
352   * @since 8
353   */
354  public static final byte RS = 30;
355
356  /**
357   * @see #FS
358   *
359   * @since 8
360   */
361  public static final byte US = 31;
362
363  /**
364   * Space: A normally non-printing graphic character used to
365   * separate words.  It is also a format effector which controls the
366   * movement of the printing position, one printing position forward.
367   * (Applicable also to display devices.)
368   *
369   * @since 8
370   */
371  public static final byte SP = 32;
372
373  /**
374   * Alternate name for {@link #SP}.
375   *
376   * @since 8
377   */
378  public static final byte SPACE = 32;
379
380  /**
381   * Delete: This character is used primarily to "erase" or
382   * "obliterate" erroneous or unwanted characters in perforated tape.
383   *
384   * @since 8
385   */
386  public static final byte DEL = 127;
387
388  /**
389   * The minimum value of an ASCII character.
390   *
391   * @since 9
392   */
393  @Beta
394  public static final int MIN = 0;
395
396  /**
397   * The maximum value of an ASCII character.
398   *
399   * @since 9
400   */
401  @Beta
402  public static final int MAX = 127;
403
404  /**
405   * Returns a copy of the input string in which all {@linkplain #isUpperCase(char) uppercase ASCII
406   * characters} have been converted to lowercase. All other characters are copied without
407   * modification.
408   */
409  public static String toLowerCase(String string) {
410    int length = string.length();
411    StringBuilder builder = new StringBuilder(length);
412    for (int i = 0; i < length; i++) {
413      builder.append(toLowerCase(string.charAt(i)));
414    }
415    return builder.toString();
416  }
417
418  /**
419   * If the argument is an {@linkplain #isUpperCase(char) uppercase ASCII character} returns the
420   * lowercase equivalent. Otherwise returns the argument.
421   */
422  public static char toLowerCase(char c) {
423    return isUpperCase(c) ? (char) (c ^ 0x20) : c;
424  }
425
426  /**
427   * Returns a copy of the input string in which all {@linkplain #isLowerCase(char) lowercase ASCII
428   * characters} have been converted to uppercase. All other characters are copied without
429   * modification.
430   */
431  public static String toUpperCase(String string) {
432    int length = string.length();
433    StringBuilder builder = new StringBuilder(length);
434    for (int i = 0; i < length; i++) {
435      builder.append(toUpperCase(string.charAt(i)));
436    }
437    return builder.toString();
438  }
439
440  /**
441   * If the argument is a {@linkplain #isLowerCase(char) lowercase ASCII character} returns the
442   * uppercase equivalent. Otherwise returns the argument.
443   */
444  public static char toUpperCase(char c) {
445    return isLowerCase(c) ? (char) (c & 0x5f) : c;
446  }
447
448  /**
449   * Indicates whether {@code c} is one of the twenty-six lowercase ASCII alphabetic characters
450   * between {@code 'a'} and {@code 'z'} inclusive. All others (including non-ASCII characters)
451   * return {@code false}.
452   */
453  public static boolean isLowerCase(char c) {
454    return (c >= 'a') && (c <= 'z');
455  }
456
457  /**
458   * Indicates whether {@code c} is one of the twenty-six uppercase ASCII alphabetic characters
459   * between {@code 'A'} and {@code 'Z'} inclusive. All others (including non-ASCII characters)
460   * return {@code false}.
461   */
462  public static boolean isUpperCase(char c) {
463    return (c >= 'A') && (c <= 'Z');
464  }
465}