src/libstd/ascii.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Operations on ASCII strings and characters.
  12 //!
  13 //! Most string operations in Rust act on UTF-8 strings. However, at times it
  14 //! makes more sense to only consider the ASCII character set for a specific
  15 //! operation.
  16 //!
  17 //! The [`AsciiExt`] trait provides methods that allow for character
  18 //! operations that only act on the ASCII subset and leave non-ASCII characters
  19 //! alone.
  20 //!
  21 //! The [`escape_default`] function provides an iterator over the bytes of an
  22 //! escaped version of the character given.
  23 //!
  24 //! [`AsciiExt`]: trait.AsciiExt.html
  25 //! [`escape_default`]: fn.escape_default.html
  26
  27 #![stable(feature = "rust1", since = "1.0.0")]
  28
  29 #[stable(feature = "rust1", since = "1.0.0")]
  30 pub use core::ascii::{EscapeDefault, escape_default};
  31
  32 /// Extension methods for ASCII-subset only operations.
  33 ///
  34 /// Be aware that operations on seemingly non-ASCII characters can sometimes
  35 /// have unexpected results. Consider this example:
  36 ///
  37 /// ```
  38 /// use std::ascii::AsciiExt;
  39 ///
  40 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
  41 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
  42 /// ```
  43 ///
  44 /// In the first example, the lowercased string is represented `"cafe\u{301}"`
  45 /// (the last character is an acute accent [combining character]). Unlike the
  46 /// other characters in the string, the combining character will not get mapped
  47 /// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second
  48 /// example, the lowercased string is represented `"caf\u{e9}"` (the last
  49 /// character is a single Unicode character representing an 'e' with an acute
  50 /// accent). Since the last character is defined outside the scope of ASCII,
  51 /// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`.
  52 ///
  53 /// [combining character]: https://en.wikipedia.org/wiki/Combining_character
  54 #[stable(feature = "rust1", since = "1.0.0")]
  55 #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
  56 pub trait AsciiExt {
  57     /// Container type for copied ASCII characters.
  58     #[stable(feature = "rust1", since = "1.0.0")]
  59     type Owned;
  60
  61     /// Checks if the value is within the ASCII range.
  62     ///
  63     /// # Note
  64     ///
  65     /// This method will be deprecated in favor of the identically-named
  66     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  67     #[stable(feature = "rust1", since = "1.0.0")]
  68     fn is_ascii(&self) -> bool;
  69
  70     /// Makes a copy of the value in its ASCII upper case equivalent.
  71     ///
  72     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
  73     /// but non-ASCII letters are unchanged.
  74     ///
  75     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
  76     ///
  77     /// To uppercase ASCII characters in addition to non-ASCII characters, use
  78     /// [`str::to_uppercase`].
  79     ///
  80     /// # Note
  81     ///
  82     /// This method will be deprecated in favor of the identically-named
  83     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  84     ///
  85     /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase
  86     /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
  87     #[stable(feature = "rust1", since = "1.0.0")]
  88     #[allow(deprecated)]
  89     fn to_ascii_uppercase(&self) -> Self::Owned;
  90
  91     /// Makes a copy of the value in its ASCII lower case equivalent.
  92     ///
  93     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
  94     /// but non-ASCII letters are unchanged.
  95     ///
  96     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
  97     ///
  98     /// To lowercase ASCII characters in addition to non-ASCII characters, use
  99     /// [`str::to_lowercase`].
 100     ///
 101     /// # Note
 102     ///
 103     /// This method will be deprecated in favor of the identically-named
 104     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 105     ///
 106     /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase
 107     /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
 108     #[stable(feature = "rust1", since = "1.0.0")]
 109     #[allow(deprecated)]
 110     fn to_ascii_lowercase(&self) -> Self::Owned;
 111
 112     /// Checks that two values are an ASCII case-insensitive match.
 113     ///
 114     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
 115     /// but without allocating and copying temporaries.
 116     ///
 117     /// # Note
 118     ///
 119     /// This method will be deprecated in favor of the identically-named
 120     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 121     #[stable(feature = "rust1", since = "1.0.0")]
 122     fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
 123
 124     /// Converts this type to its ASCII upper case equivalent in-place.
 125     ///
 126     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 127     /// but non-ASCII letters are unchanged.
 128     ///
 129     /// To return a new uppercased value without modifying the existing one, use
 130     /// [`to_ascii_uppercase`].
 131     ///
 132     /// # Note
 133     ///
 134     /// This method will be deprecated in favor of the identically-named
 135     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 136     ///
 137     /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
 138     #[stable(feature = "ascii", since = "1.9.0")]
 139     fn make_ascii_uppercase(&mut self);
 140
 141     /// Converts this type to its ASCII lower case equivalent in-place.
 142     ///
 143     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 144     /// but non-ASCII letters are unchanged.
 145     ///
 146     /// To return a new lowercased value without modifying the existing one, use
 147     /// [`to_ascii_lowercase`].
 148     ///
 149     /// # Note
 150     ///
 151     /// This method will be deprecated in favor of the identically-named
 152     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 153     ///
 154     /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
 155     #[stable(feature = "ascii", since = "1.9.0")]
 156     fn make_ascii_lowercase(&mut self);
 157
 158     /// Checks if the value is an ASCII alphabetic character:
 159     /// U+0041 'A' ... U+005A 'Z' or U+0061 'a' ... U+007A 'z'.
 160     /// For strings, true if all characters in the string are
 161     /// ASCII alphabetic.
 162     ///
 163     /// # Note
 164     ///
 165     /// This method will be deprecated in favor of the identically-named
 166     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 167     #[unstable(feature = "ascii_ctype", issue = "39658")]
 168     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 169     fn is_ascii_alphabetic(&self) -> bool { unimplemented!(); }
 170
 171     /// Checks if the value is an ASCII uppercase character:
 172     /// U+0041 'A' ... U+005A 'Z'.
 173     /// For strings, true if all characters in the string are
 174     /// ASCII uppercase.
 175     ///
 176     /// # Note
 177     ///
 178     /// This method will be deprecated in favor of the identically-named
 179     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 180     #[unstable(feature = "ascii_ctype", issue = "39658")]
 181     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 182     fn is_ascii_uppercase(&self) -> bool { unimplemented!(); }
 183
 184     /// Checks if the value is an ASCII lowercase character:
 185     /// U+0061 'a' ... U+007A 'z'.
 186     /// For strings, true if all characters in the string are
 187     /// ASCII lowercase.
 188     ///
 189     /// # Note
 190     ///
 191     /// This method will be deprecated in favor of the identically-named
 192     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 193     #[unstable(feature = "ascii_ctype", issue = "39658")]
 194     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 195     fn is_ascii_lowercase(&self) -> bool { unimplemented!(); }
 196
 197     /// Checks if the value is an ASCII alphanumeric character:
 198     /// U+0041 'A' ... U+005A 'Z', U+0061 'a' ... U+007A 'z', or
 199     /// U+0030 '0' ... U+0039 '9'.
 200     /// For strings, true if all characters in the string are
 201     /// ASCII alphanumeric.
 202     ///
 203     /// # Note
 204     ///
 205     /// This method will be deprecated in favor of the identically-named
 206     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 207     #[unstable(feature = "ascii_ctype", issue = "39658")]
 208     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 209     fn is_ascii_alphanumeric(&self) -> bool { unimplemented!(); }
 210
 211     /// Checks if the value is an ASCII decimal digit:
 212     /// U+0030 '0' ... U+0039 '9'.
 213     /// For strings, true if all characters in the string are
 214     /// ASCII digits.
 215     ///
 216     /// # Note
 217     ///
 218     /// This method will be deprecated in favor of the identically-named
 219     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 220     #[unstable(feature = "ascii_ctype", issue = "39658")]
 221     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 222     fn is_ascii_digit(&self) -> bool { unimplemented!(); }
 223
 224     /// Checks if the value is an ASCII hexadecimal digit:
 225     /// U+0030 '0' ... U+0039 '9', U+0041 'A' ... U+0046 'F', or
 226     /// U+0061 'a' ... U+0066 'f'.
 227     /// For strings, true if all characters in the string are
 228     /// ASCII hex digits.
 229     ///
 230     /// # Note
 231     ///
 232     /// This method will be deprecated in favor of the identically-named
 233     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 234     #[unstable(feature = "ascii_ctype", issue = "39658")]
 235     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 236     fn is_ascii_hexdigit(&self) -> bool { unimplemented!(); }
 237
 238     /// Checks if the value is an ASCII punctuation character:
 239     ///
 240     /// U+0021 ... U+002F `! " # $ % & ' ( ) * + , - . /`
 241     /// U+003A ... U+0040 `: ; < = > ? @`
 242     /// U+005B ... U+0060 ``[ \\ ] ^ _ ` ``
 243     /// U+007B ... U+007E `{ | } ~`
 244     ///
 245     /// For strings, true if all characters in the string are
 246     /// ASCII punctuation.
 247     ///
 248     /// # Note
 249     ///
 250     /// This method will be deprecated in favor of the identically-named
 251     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 252     #[unstable(feature = "ascii_ctype", issue = "39658")]
 253     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 254     fn is_ascii_punctuation(&self) -> bool { unimplemented!(); }
 255
 256     /// Checks if the value is an ASCII graphic character:
 257     /// U+0021 '!' ... U+007E '~'.
 258     /// For strings, true if all characters in the string are
 259     /// ASCII graphic characters.
 260     ///
 261     /// # Note
 262     ///
 263     /// This method will be deprecated in favor of the identically-named
 264     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 265     #[unstable(feature = "ascii_ctype", issue = "39658")]
 266     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 267     fn is_ascii_graphic(&self) -> bool { unimplemented!(); }
 268
 269     /// Checks if the value is an ASCII whitespace character:
 270     /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
 271     /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
 272     /// For strings, true if all characters in the string are
 273     /// ASCII whitespace.
 274     ///
 275     /// Rust uses the WhatWG Infra Standard's [definition of ASCII
 276     /// whitespace][infra-aw].  There are several other definitions in
 277     /// wide use.  For instance, [the POSIX locale][pct] includes
 278     /// U+000B VERTICAL TAB as well as all the above characters,
 279     /// but—from the very same specification—[the default rule for
 280     /// "field splitting" in the Bourne shell][bfs] considers *only*
 281     /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
 282     ///
 283     /// If you are writing a program that will process an existing
 284     /// file format, check what that format's definition of whitespace is
 285     /// before using this function.
 286     ///
 287     /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
 288     /// [pct]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
 289     /// [bfs]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
 290     ///
 291     /// # Note
 292     ///
 293     /// This method will be deprecated in favor of the identically-named
 294     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 295     #[unstable(feature = "ascii_ctype", issue = "39658")]
 296     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 297     fn is_ascii_whitespace(&self) -> bool { unimplemented!(); }
 298
 299     /// Checks if the value is an ASCII control character:
 300     /// U+0000 NUL ... U+001F UNIT SEPARATOR, or U+007F DELETE.
 301     /// Note that most ASCII whitespace characters are control
 302     /// characters, but SPACE is not.
 303     ///
 304     /// # Note
 305     ///
 306     /// This method will be deprecated in favor of the identically-named
 307     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 308     #[unstable(feature = "ascii_ctype", issue = "39658")]
 309     #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
 310     fn is_ascii_control(&self) -> bool { unimplemented!(); }
 311 }
 312
 313 macro_rules! delegating_ascii_methods {
 314     () => {
 315         #[inline]
 316         fn is_ascii(&self) -> bool { self.is_ascii() }
 317
 318         #[inline]
 319         fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() }
 320
 321         #[inline]
 322         fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() }
 323
 324         #[inline]
 325         fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) }
 326
 327         #[inline]
 328         fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); }
 329
 330         #[inline]
 331         fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); }
 332     }
 333 }
 334
 335 macro_rules! delegating_ascii_ctype_methods {
 336     () => {
 337         #[inline]
 338         fn is_ascii_alphabetic(&self) -> bool { self.is_ascii_alphabetic() }
 339
 340         #[inline]
 341         fn is_ascii_uppercase(&self) -> bool { self.is_ascii_uppercase() }
 342
 343         #[inline]
 344         fn is_ascii_lowercase(&self) -> bool { self.is_ascii_lowercase() }
 345
 346         #[inline]
 347         fn is_ascii_alphanumeric(&self) -> bool { self.is_ascii_alphanumeric() }
 348
 349         #[inline]
 350         fn is_ascii_digit(&self) -> bool { self.is_ascii_digit() }
 351
 352         #[inline]
 353         fn is_ascii_hexdigit(&self) -> bool { self.is_ascii_hexdigit() }
 354
 355         #[inline]
 356         fn is_ascii_punctuation(&self) -> bool { self.is_ascii_punctuation() }
 357
 358         #[inline]
 359         fn is_ascii_graphic(&self) -> bool { self.is_ascii_graphic() }
 360
 361         #[inline]
 362         fn is_ascii_whitespace(&self) -> bool { self.is_ascii_whitespace() }
 363
 364         #[inline]
 365         fn is_ascii_control(&self) -> bool { self.is_ascii_control() }
 366     }
 367 }
 368
 369 #[stable(feature = "rust1", since = "1.0.0")]
 370 #[allow(deprecated)]
 371 impl AsciiExt for u8 {
 372     type Owned = u8;
 373
 374     delegating_ascii_methods!();
 375     delegating_ascii_ctype_methods!();
 376 }
 377
 378 #[stable(feature = "rust1", since = "1.0.0")]
 379 #[allow(deprecated)]
 380 impl AsciiExt for char {
 381     type Owned = char;
 382
 383     delegating_ascii_methods!();
 384     delegating_ascii_ctype_methods!();
 385 }
 386
 387 #[stable(feature = "rust1", since = "1.0.0")]
 388 #[allow(deprecated)]
 389 impl AsciiExt for [u8] {
 390     type Owned = Vec<u8>;
 391
 392     delegating_ascii_methods!();
 393
 394     #[inline]
 395     fn is_ascii_alphabetic(&self) -> bool {
 396         self.iter().all(|b| b.is_ascii_alphabetic())
 397     }
 398
 399     #[inline]
 400     fn is_ascii_uppercase(&self) -> bool {
 401         self.iter().all(|b| b.is_ascii_uppercase())
 402     }
 403
 404     #[inline]
 405     fn is_ascii_lowercase(&self) -> bool {
 406         self.iter().all(|b| b.is_ascii_lowercase())
 407     }
 408
 409     #[inline]
 410     fn is_ascii_alphanumeric(&self) -> bool {
 411         self.iter().all(|b| b.is_ascii_alphanumeric())
 412     }
 413
 414     #[inline]
 415     fn is_ascii_digit(&self) -> bool {
 416         self.iter().all(|b| b.is_ascii_digit())
 417     }
 418
 419     #[inline]
 420     fn is_ascii_hexdigit(&self) -> bool {
 421         self.iter().all(|b| b.is_ascii_hexdigit())
 422     }
 423
 424     #[inline]
 425     fn is_ascii_punctuation(&self) -> bool {
 426         self.iter().all(|b| b.is_ascii_punctuation())
 427     }
 428
 429     #[inline]
 430     fn is_ascii_graphic(&self) -> bool {
 431         self.iter().all(|b| b.is_ascii_graphic())
 432     }
 433
 434     #[inline]
 435     fn is_ascii_whitespace(&self) -> bool {
 436         self.iter().all(|b| b.is_ascii_whitespace())
 437     }
 438
 439     #[inline]
 440     fn is_ascii_control(&self) -> bool {
 441         self.iter().all(|b| b.is_ascii_control())
 442     }
 443 }
 444
 445 #[stable(feature = "rust1", since = "1.0.0")]
 446 #[allow(deprecated)]
 447 impl AsciiExt for str {
 448     type Owned = String;
 449
 450     delegating_ascii_methods!();
 451
 452     #[inline]
 453     fn is_ascii_alphabetic(&self) -> bool {
 454         self.bytes().all(|b| b.is_ascii_alphabetic())
 455     }
 456
 457     #[inline]
 458     fn is_ascii_uppercase(&self) -> bool {
 459         self.bytes().all(|b| b.is_ascii_uppercase())
 460     }
 461
 462     #[inline]
 463     fn is_ascii_lowercase(&self) -> bool {
 464         self.bytes().all(|b| b.is_ascii_lowercase())
 465     }
 466
 467     #[inline]
 468     fn is_ascii_alphanumeric(&self) -> bool {
 469         self.bytes().all(|b| b.is_ascii_alphanumeric())
 470     }
 471
 472     #[inline]
 473     fn is_ascii_digit(&self) -> bool {
 474         self.bytes().all(|b| b.is_ascii_digit())
 475     }
 476
 477     #[inline]
 478     fn is_ascii_hexdigit(&self) -> bool {
 479         self.bytes().all(|b| b.is_ascii_hexdigit())
 480     }
 481
 482     #[inline]
 483     fn is_ascii_punctuation(&self) -> bool {
 484         self.bytes().all(|b| b.is_ascii_punctuation())
 485     }
 486
 487     #[inline]
 488     fn is_ascii_graphic(&self) -> bool {
 489         self.bytes().all(|b| b.is_ascii_graphic())
 490     }
 491
 492     #[inline]
 493     fn is_ascii_whitespace(&self) -> bool {
 494         self.bytes().all(|b| b.is_ascii_whitespace())
 495     }
 496
 497     #[inline]
 498     fn is_ascii_control(&self) -> bool {
 499         self.bytes().all(|b| b.is_ascii_control())
 500     }
 501 }