#[stable(feature = "rust1", since = "1.0.0")]
pub const MAX: char = '\u{10ffff}';
-/// Converts from `u32` to a `char`
+/// Converts a `u32` to an `Option<char>`.
+///
+/// # Examples
+///
+/// ```
+/// use std::char;
+///
+/// let c = char::from_u32(10084); // produces `Some(❤)`
+/// assert_eq!(c, Some('❤'));
+/// ```
+///
+/// An invalid character:
+///
+/// ```
+/// use std::char;
+///
+/// let none = char::from_u32(1114112);
+/// assert_eq!(none, None);
+/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn from_u32(i: u32) -> Option<char> {
}
}
-///
-/// Converts a number to the character representing it
+/// Converts a number to the character representing it.
///
/// # Return value
///
///
/// Panics if given an `radix` > 36.
///
+/// # Examples
+///
+/// ```
+/// use std::char;
+///
+/// let c = char::from_digit(4, 10);
+///
+/// assert_eq!(c, '4')
+/// ```
#[inline]
#[unstable(feature = "core", reason = "pending integer conventions")]
pub fn from_digit(num: uint, radix: uint) -> Option<char> {
/// # Panics
///
/// Panics if given a radix > 36.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let c = '1';
+ ///
+ /// assert!(c.is_digit(10));
+ ///
+ /// assert!('f'.is_digit(16));
+ /// ```
#[unstable(feature = "core",
reason = "pending integer conventions")]
fn is_digit(self, radix: uint) -> bool;
/// # Panics
///
/// Panics if given a radix outside the range [0..36].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let c = '1';
+ ///
+ /// assert_eq!(1, c.to_digit(10));
+ ///
+ /// assert_eq!(15, 'f'.to_digit(16));
+ /// ```
#[unstable(feature = "core",
reason = "pending integer conventions")]
fn to_digit(self, radix: uint) -> Option<uint>;
- /// Returns an iterator that yields the hexadecimal Unicode escape
- /// of a character, as `char`s.
+ /// Returns an iterator that yields the hexadecimal Unicode escape of a character, as `char`s.
+ ///
+ /// All characters are escaped with Rust syntax of the form `\\u{NNNN}` where `NNNN` is the
+ /// shortest hexadecimal representation of the code point.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// for i in '❤'.escape_unicode() {
+ /// println!("{}", i);
+ /// }
+ /// ```
///
- /// All characters are escaped with Rust syntax of the form `\\u{NNNN}`
- /// where `NNNN` is the shortest hexadecimal representation of the code
- /// point.
+ /// This prints:
+ ///
+ /// ```text
+ /// \
+ /// u
+ /// {
+ /// 2
+ /// 7
+ /// 6
+ /// 4
+ /// }
+ /// ```
+ ///
+ /// Collecting into a `String`:
+ ///
+ /// ```
+ /// let heart: String = '❤'.escape_unicode().collect();
+ ///
+ /// assert_eq!(heart, r"\u{2764}");
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn escape_unicode(self) -> EscapeUnicode;
/// escaped.
/// * Any other chars in the range [0x20,0x7e] are not escaped.
/// * Any other chars are given hex Unicode escapes; see `escape_unicode`.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// for i in '"'.escape_default() {
+ /// println!("{}", i);
+ /// }
+ /// ```
+ ///
+ /// This prints:
+ ///
+ /// ```text
+ /// \
+ /// "
+ /// ```
+ ///
+ /// Collecting into a `String`:
+ ///
+ /// ```
+ /// let quote: String = '"'.escape_default().collect();
+ ///
+ /// assert_eq!(quote, r"\"");
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn escape_default(self) -> EscapeDefault;
- /// Returns the amount of bytes this character would need if encoded in
- /// UTF-8.
+ /// Returns the number of bytes this character would need if encoded in UTF-8.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let n = 'ß'.len_utf8();
+ ///
+ /// assert_eq!(n, 2);
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn len_utf8(self) -> uint;
- /// Returns the amount of bytes this character would need if encoded in
- /// UTF-16.
+ /// Returns the number of bytes this character would need if encoded in UTF-16.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let n = 'ß'.len_utf16();
+ ///
+ /// assert_eq!(n, 1);
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn len_utf16(self) -> uint;
- /// Encodes this character as UTF-8 into the provided byte buffer,
- /// and then returns the number of bytes written.
+ /// Encodes this character as UTF-8 into the provided byte buffer, and then returns the number
+ /// of bytes written.
+ ///
+ /// If the buffer is not large enough, nothing will be written into it and a `None` will be
+ /// returned.
+ ///
+ /// # Examples
+ ///
+ /// In both of these examples, 'ß' takes two bytes to encode.
+ ///
+ /// ```
+ /// let mut b = [0; 2];
///
- /// If the buffer is not large enough, nothing will be written into it
- /// and a `None` will be returned.
+ /// let result = 'ß'.encode_utf8(&mut b);
+ ///
+ /// assert_eq!(result, Some(2));
+ /// ```
+ ///
+ /// A buffer that's too small:
+ ///
+ /// ```
+ /// let mut b = [0; 1];
+ ///
+ /// let result = 'ß'.encode_utf8(&mut b);
+ ///
+ /// assert_eq!(result, None);
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn encode_utf8(self, dst: &mut [u8]) -> Option<uint>;
- /// Encodes this character as UTF-16 into the provided `u16` buffer,
- /// and then returns the number of `u16`s written.
+ /// Encodes this character as UTF-16 into the provided `u16` buffer, and then returns the
+ /// number of `u16`s written.
+ ///
+ /// If the buffer is not large enough, nothing will be written into it and a `None` will be
+ /// returned.
+ ///
+ /// # Examples
+ ///
+ /// In both of these examples, 'ß' takes one byte to encode.
+ ///
+ /// ```
+ /// let mut b = [0; 1];
+ ///
+ /// let result = 'ß'.encode_utf16(&mut b);
+ ///
+ /// assert_eq!(result, Some(1));
+ /// ```
+ ///
+ /// A buffer that's too small:
+ ///
+ /// ```
+ /// let mut b = [0; 0];
+ ///
+ /// let result = 'ß'.encode_utf8(&mut b);
///
- /// If the buffer is not large enough, nothing will be written into it
- /// and a `None` will be returned.
+ /// assert_eq!(result, None);
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn encode_utf16(self, dst: &mut [u16]) -> Option<uint>;
}
projects / rust.git / commitdiff