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 }