    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.GwtCompatible;
    020
    021    /**
    022     * Static methods pertaining to ASCII characters (those in the range of values
    023     * {@code 0x00} through {@code 0x7F}), and to strings containing such
    024     * characters.
    025     *
    026     * <p>ASCII utilities also exist in other classes of this package:
    027     * <ul>
    028     * <!-- TODO(kevinb): how can we make this not produce a warning when building gwt javadoc? -->
    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.0
    037     */
    038    @GwtCompatible
    039    public 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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    149       */
    150      public static final byte LF = 10;
    151
    152      /**
    153       * Alternate name for {@link #LF}.  ({@code LF} is preferred.)
    154       *
    155       * @since 8.0
    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.0
    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.0
    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.0
    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.0
    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.0
    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.0
    212       */
    213      public static final byte DLE = 16;
    214
    215      /**
    216       * Device Control 1. 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.0
    223       */
    224      public static final byte DC1 = 17; // aka XON
    225
    226      /**
    227       * Transmission On: 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.0
    234       */
    235      public static final byte XON = 17; // aka DC1
    236
    237      /**
    238       * Device Control 2. Characters for the control
    239       * of ancillary devices associated with data processing or
    240       * telecommunication systems, more especially switching devices "on" or
    241       * "off."  (If a single "stop" control is required to interrupt or turn
    242       * off ancillary devices, DC4 is the preferred assignment.)
    243       *
    244       * @since 8.0
    245       */
    246      public static final byte DC2 = 18;
    247
    248      /**
    249       * Device Control 3. Characters for the control
    250       * of ancillary devices associated with data processing or
    251       * telecommunication systems, more especially switching devices "on" or
    252       * "off."  (If a single "stop" control is required to interrupt or turn
    253       * off ancillary devices, DC4 is the preferred assignment.)
    254       *
    255       * @since 8.0
    256       */
    257      public static final byte DC3 = 19; // aka XOFF
    258
    259      /**
    260       * Transmission off. See {@link #XON} for explanation.
    261       *
    262       * @since 8.0
    263       */
    264      public static final byte XOFF = 19; // aka DC3
    265
    266      /**
    267       * Device Control 4. Characters for the control
    268       * of ancillary devices associated with data processing or
    269       * telecommunication systems, more especially switching devices "on" or
    270       * "off."  (If a single "stop" control is required to interrupt or turn
    271       * off ancillary devices, DC4 is the preferred assignment.)
    272       *
    273       * @since 8.0
    274       */
    275      public static final byte DC4 = 20;
    276
    277      /**
    278       * Negative Acknowledge: A communication control character
    279       * transmitted by a receiver as a negative response to the sender.
    280       *
    281       * @since 8.0
    282       */
    283      public static final byte NAK = 21;
    284
    285      /**
    286       * Synchronous Idle: A communication control character used by
    287       * a synchronous transmission system in the absence of any other
    288       * character to provide a signal from which synchronism may be achieved
    289       * or retained.
    290       *
    291       * @since 8.0
    292       */
    293      public static final byte SYN = 22;
    294
    295      /**
    296       * End of Transmission Block: A communication control character
    297       * used to indicate the end of a block of data for communication
    298       * purposes.  ETB is used for blocking data where the block structure is
    299       * not necessarily related to the processing format.
    300       *
    301       * @since 8.0
    302       */
    303      public static final byte ETB = 23;
    304
    305      /**
    306       * Cancel: A control character used to indicate that the data
    307       * with which it is sent is in error or is to be disregarded.
    308       *
    309       * @since 8.0
    310       */
    311      public static final byte CAN = 24;
    312
    313      /**
    314       * End of Medium: A control character associated with the sent
    315       * data which may be used to identify the physical end of the medium, or
    316       * the end of the used, or wanted, portion of information recorded on a
    317       * medium.  (The position of this character does not necessarily
    318       * correspond to the physical end of the medium.)
    319       *
    320       * @since 8.0
    321       */
    322      public static final byte EM = 25;
    323
    324      /**
    325       * Substitute: A character that may be substituted for a
    326       * character which is determined to be invalid or in error.
    327       *
    328       * @since 8.0
    329       */
    330      public static final byte SUB = 26;
    331
    332      /**
    333       * Escape: A control character intended to provide code
    334       * extension (supplementary characters) in general information
    335       * interchange.  The Escape character itself is a prefix affecting the
    336       * interpretation of a limited number of contiguously following
    337       * characters.
    338       *
    339       * @since 8.0
    340       */
    341      public static final byte ESC = 27;
    342
    343      /**
    344       * File Separator: These four information separators may be
    345       * used within data in optional fashion, except that their hierarchical
    346       * relationship shall be: FS is the most inclusive, then GS, then RS,
    347       * and US is least inclusive.  (The content and length of a File, Group,
    348       * Record, or Unit are not specified.)
    349       *
    350       * @since 8.0
    351       */
    352      public static final byte FS = 28;
    353
    354      /**
    355       * Group Separator: These four information separators may be
    356       * used within data in optional fashion, except that their hierarchical
    357       * relationship shall be: FS is the most inclusive, then GS, then RS,
    358       * and US is least inclusive.  (The content and length of a File, Group,
    359       * Record, or Unit are not specified.)
    360       *
    361       * @since 8.0
    362       */
    363      public static final byte GS = 29;
    364
    365      /**
    366       * Record Separator: These four information separators may be
    367       * used within data in optional fashion, except that their hierarchical
    368       * relationship shall be: FS is the most inclusive, then GS, then RS,
    369       * and US is least inclusive.  (The content and length of a File, Group,
    370       * Record, or Unit are not specified.)
    371       *
    372       * @since 8.0
    373       */
    374      public static final byte RS = 30;
    375
    376      /**
    377       * Unit Separator: These four information separators may be
    378       * used within data in optional fashion, except that their hierarchical
    379       * relationship shall be: FS is the most inclusive, then GS, then RS,
    380       * and US is least inclusive.  (The content and length of a File, Group,
    381       * Record, or Unit are not specified.)
    382       *
    383       * @since 8.0
    384       */
    385      public static final byte US = 31;
    386
    387      /**
    388       * Space: A normally non-printing graphic character used to
    389       * separate words.  It is also a format effector which controls the
    390       * movement of the printing position, one printing position forward.
    391       * (Applicable also to display devices.)
    392       *
    393       * @since 8.0
    394       */
    395      public static final byte SP = 32;
    396
    397      /**
    398       * Alternate name for {@link #SP}.
    399       *
    400       * @since 8.0
    401       */
    402      public static final byte SPACE = 32;
    403
    404      /**
    405       * Delete: This character is used primarily to "erase" or
    406       * "obliterate" erroneous or unwanted characters in perforated tape.
    407       *
    408       * @since 8.0
    409       */
    410      public static final byte DEL = 127;
    411
    412      /**
    413       * The minimum value of an ASCII character.
    414       *
    415       * @since 9.0 (was type {@code int} before 12.0)
    416       */
    417      public static final char MIN = 0;
    418
    419      /**
    420       * The maximum value of an ASCII character.
    421       *
    422       * @since 9.0 (was type {@code int} before 12.0)
    423       */
    424      public static final char MAX = 127;
    425
    426      /**
    427       * Returns a copy of the input string in which all {@linkplain #isUpperCase(char) uppercase ASCII
    428       * characters} have been converted to lowercase. All other characters are copied without
    429       * modification.
    430       */
    431      public static String toLowerCase(String string) {
    432        int length = string.length();
    433        StringBuilder builder = new StringBuilder(length);
    434        for (int i = 0; i < length; i++) {
    435          builder.append(toLowerCase(string.charAt(i)));
    436        }
    437        return builder.toString();
    438      }
    439
    440      /**
    441       * If the argument is an {@linkplain #isUpperCase(char) uppercase ASCII character} returns the
    442       * lowercase equivalent. Otherwise returns the argument.
    443       */
    444      public static char toLowerCase(char c) {
    445        return isUpperCase(c) ? (char) (c ^ 0x20) : c;
    446      }
    447
    448      /**
    449       * Returns a copy of the input string in which all {@linkplain #isLowerCase(char) lowercase ASCII
    450       * characters} have been converted to uppercase. All other characters are copied without
    451       * modification.
    452       */
    453      public static String toUpperCase(String string) {
    454        int length = string.length();
    455        StringBuilder builder = new StringBuilder(length);
    456        for (int i = 0; i < length; i++) {
    457          builder.append(toUpperCase(string.charAt(i)));
    458        }
    459        return builder.toString();
    460      }
    461
    462      /**
    463       * If the argument is a {@linkplain #isLowerCase(char) lowercase ASCII character} returns the
    464       * uppercase equivalent. Otherwise returns the argument.
    465       */
    466      public static char toUpperCase(char c) {
    467        return isLowerCase(c) ? (char) (c & 0x5f) : c;
    468      }
    469
    470      /**
    471       * Indicates whether {@code c} is one of the twenty-six lowercase ASCII alphabetic characters
    472       * between {@code 'a'} and {@code 'z'} inclusive. All others (including non-ASCII characters)
    473       * return {@code false}.
    474       */
    475      public static boolean isLowerCase(char c) {
    476        return (c >= 'a') && (c <= 'z');
    477      }
    478
    479      /**
    480       * Indicates whether {@code c} is one of the twenty-six uppercase ASCII alphabetic characters
    481       * between {@code 'A'} and {@code 'Z'} inclusive. All others (including non-ASCII characters)
    482       * return {@code false}.
    483       */
    484      public static boolean isUpperCase(char c) {
    485        return (c >= 'A') && (c <= 'Z');
    486      }
    487    }