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