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 }