src/libstd/primitive_docs.rs

   1 // Copyright 2015 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 #[doc(primitive = "bool")]
  12 //
  13 /// The boolean type.
  14 ///
  15 mod prim_bool { }
  16
  17 #[doc(primitive = "char")]
  18 //
  19 /// A Unicode scalar value.
  20 ///
  21 /// A `char` represents a
  22 /// *[Unicode scalar
  23 /// value](http://www.unicode.org/glossary/#unicode_scalar_value)*, as it can
  24 /// contain any Unicode code point except high-surrogate and low-surrogate code
  25 /// points.
  26 ///
  27 /// As such, only values in the ranges \[0x0,0xD7FF\] and \[0xE000,0x10FFFF\]
  28 /// (inclusive) are allowed. A `char` can always be safely cast to a `u32`;
  29 /// however the converse is not always true due to the above range limits
  30 /// and, as such, should be performed via the `from_u32` function.
  31 ///
  32 /// *[See also the `std::char` module](char/index.html).*
  33 ///
  34 mod prim_char { }
  35
  36 #[doc(primitive = "unit")]
  37 //
  38 /// The `()` type, sometimes called "unit" or "nil".
  39 ///
  40 /// The `()` type has exactly one value `()`, and is used when there
  41 /// is no other meaningful value that could be returned. `()` is most
  42 /// commonly seen implicitly: functions without a `-> ...` implicitly
  43 /// have return type `()`, that is, these are equivalent:
  44 ///
  45 /// ```rust
  46 /// fn long() -> () {}
  47 ///
  48 /// fn short() {}
  49 /// ```
  50 ///
  51 /// The semicolon `;` can be used to discard the result of an
  52 /// expression at the end of a block, making the expression (and thus
  53 /// the block) evaluate to `()`. For example,
  54 ///
  55 /// ```rust
  56 /// fn returns_i64() -> i64 {
  57 ///     1i64
  58 /// }
  59 /// fn returns_unit() {
  60 ///     1i64;
  61 /// }
  62 ///
  63 /// let is_i64 = {
  64 ///     returns_i64()
  65 /// };
  66 /// let is_unit = {
  67 ///     returns_i64();
  68 /// };
  69 /// ```
  70 ///
  71 mod prim_unit { }
  72
  73 #[doc(primitive = "pointer")]
  74 //
  75 /// Raw, unsafe pointers, `*const T`, and `*mut T`.
  76 ///
  77 /// Working with raw pointers in Rust is uncommon,
  78 /// typically limited to a few patterns.
  79 ///
  80 /// Use the `null` function to create null pointers, and the `is_null` method
  81 /// of the `*const T` type  to check for null. The `*const T` type also defines
  82 /// the `offset` method, for pointer math.
  83 ///
  84 /// # Common ways to create raw pointers
  85 ///
  86 /// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`).
  87 ///
  88 /// ```
  89 /// let my_num: i32 = 10;
  90 /// let my_num_ptr: *const i32 = &my_num;
  91 /// let mut my_speed: i32 = 88;
  92 /// let my_speed_ptr: *mut i32 = &mut my_speed;
  93 /// ```
  94 ///
  95 /// To get a pointer to a boxed value, dereference the box:
  96 ///
  97 /// ```
  98 /// let my_num: Box<i32> = Box::new(10);
  99 /// let my_num_ptr: *const i32 = &*my_num;
 100 /// let mut my_speed: Box<i32> = Box::new(88);
 101 /// let my_speed_ptr: *mut i32 = &mut *my_speed;
 102 /// ```
 103 ///
 104 /// This does not take ownership of the original allocation
 105 /// and requires no resource management later,
 106 /// but you must not use the pointer after its lifetime.
 107 ///
 108 /// ## 2. Consume a box (`Box<T>`).
 109 ///
 110 /// The `into_raw` function consumes a box and returns
 111 /// the raw pointer. It doesn't destroy `T` or deallocate any memory.
 112 ///
 113 /// ```
 114 /// let my_speed: Box<i32> = Box::new(88);
 115 /// let my_speed: *mut i32 = Box::into_raw(my_speed);
 116 ///
 117 /// // By taking ownership of the original `Box<T>` though
 118 /// // we are obligated to put it together later to be destroyed.
 119 /// unsafe {
 120 ///     drop(Box::from_raw(my_speed));
 121 /// }
 122 /// ```
 123 ///
 124 /// Note that here the call to `drop` is for clarity - it indicates
 125 /// that we are done with the given value and it should be destroyed.
 126 ///
 127 /// ## 3. Get it from C.
 128 ///
 129 /// ```
 130 /// # #![feature(libc)]
 131 /// extern crate libc;
 132 ///
 133 /// use std::mem;
 134 ///
 135 /// fn main() {
 136 ///     unsafe {
 137 ///         let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32;
 138 ///         if my_num.is_null() {
 139 ///             panic!("failed to allocate memory");
 140 ///         }
 141 ///         libc::free(my_num as *mut libc::c_void);
 142 ///     }
 143 /// }
 144 /// ```
 145 ///
 146 /// Usually you wouldn't literally use `malloc` and `free` from Rust,
 147 /// but C APIs hand out a lot of pointers generally, so are a common source
 148 /// of raw pointers in Rust.
 149 ///
 150 /// *[See also the `std::ptr` module](ptr/index.html).*
 151 ///
 152 mod prim_pointer { }
 153
 154 #[doc(primitive = "array")]
 155 //
 156 /// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and
 157 /// the non-negative compile time constant size, `N`.
 158 ///
 159 /// Arrays values are created either with an explicit expression that lists
 160 /// each element: `[x, y, z]` or a repeat expression: `[x; N]`. The repeat
 161 /// expression requires that the element type is `Copy`.
 162 ///
 163 /// The type `[T; N]` is `Copy` if `T: Copy`.
 164 ///
 165 /// Arrays of sizes from 0 to 32 (inclusive) implement the following traits
 166 /// if the element type allows it:
 167 ///
 168 /// - `Clone` (only if `T: Copy`)
 169 /// - `Debug`
 170 /// - `IntoIterator` (implemented for `&[T; N]` and `&mut [T; N]`)
 171 /// - `PartialEq`, `PartialOrd`, `Ord`, `Eq`
 172 /// - `Hash`
 173 /// - `AsRef`, `AsMut`
 174 /// - `Borrow`, `BorrowMut`
 175 /// - `Default`
 176 ///
 177 /// Arrays dereference to [slices (`[T]`)][slice], so their methods can be called
 178 /// on arrays.
 179 ///
 180 /// [slice]: primitive.slice.html
 181 ///
 182 /// Rust does not currently support generics over the size of an array type.
 183 ///
 184 /// # Examples
 185 ///
 186 /// ```
 187 /// let mut array: [i32; 3] = [0; 3];
 188 ///
 189 /// array[1] = 1;
 190 /// array[2] = 2;
 191 ///
 192 /// assert_eq!([1, 2], &array[1..]);
 193 ///
 194 /// // This loop prints: 0 1 2
 195 /// for x in &array {
 196 ///     print!("{} ", x);
 197 /// }
 198 ///
 199 /// ```
 200 ///
 201 mod prim_array { }
 202
 203 #[doc(primitive = "slice")]
 204 //
 205 /// A dynamically-sized view into a contiguous sequence, `[T]`.
 206 ///
 207 /// Slices are a view into a block of memory represented as a pointer and a
 208 /// length.
 209 ///
 210 /// ```
 211 /// // slicing a Vec
 212 /// let vec = vec![1, 2, 3];
 213 /// let int_slice = &vec[..];
 214 /// // coercing an array to a slice
 215 /// let str_slice: &[&str] = &["one", "two", "three"];
 216 /// ```
 217 ///
 218 /// Slices are either mutable or shared. The shared slice type is `&[T]`,
 219 /// while the mutable slice type is `&mut [T]`, where `T` represents the element
 220 /// type. For example, you can mutate the block of memory that a mutable slice
 221 /// points to:
 222 ///
 223 /// ```
 224 /// let x = &mut [1, 2, 3];
 225 /// x[1] = 7;
 226 /// assert_eq!(x, &[1, 7, 3]);
 227 /// ```
 228 ///
 229 /// *[See also the `std::slice` module](slice/index.html).*
 230 ///
 231 mod prim_slice { }
 232
 233 #[doc(primitive = "str")]
 234 //
 235 /// Unicode string slices.
 236 ///
 237 /// Rust's `str` type is one of the core primitive types of the language. `&str`
 238 /// is the borrowed string type. This type of string can only be created from
 239 /// other strings, unless it is a `&'static str` (see below). It is not possible
 240 /// to move out of borrowed strings because they are owned elsewhere.
 241 ///
 242 /// # Examples
 243 ///
 244 /// Here's some code that uses a `&str`:
 245 ///
 246 /// ```
 247 /// let s = "Hello, world.";
 248 /// ```
 249 ///
 250 /// This `&str` is a `&'static str`, which is the type of string literals.
 251 /// They're `'static` because literals are available for the entire lifetime of
 252 /// the program.
 253 ///
 254 /// You can get a non-`'static` `&str` by taking a slice of a `String`:
 255 ///
 256 /// ```
 257 /// let some_string = "Hello, world.".to_string();
 258 /// let s = &some_string;
 259 /// ```
 260 ///
 261 /// # Representation
 262 ///
 263 /// Rust's string type, `str`, is a sequence of Unicode scalar values encoded as
 264 /// a stream of UTF-8 bytes. All [strings](../../reference.html#literals) are
 265 /// guaranteed to be validly encoded UTF-8 sequences. Additionally, strings are
 266 /// not null-terminated and can thus contain null bytes.
 267 ///
 268 /// The actual representation of `str`s have direct mappings to slices: `&str`
 269 /// is the same as `&[u8]`.
 270 ///
 271 /// *[See also the `std::str` module](str/index.html).*
 272 ///
 273 mod prim_str { }
 274
 275 #[doc(primitive = "tuple")]
 276 //
 277 /// A finite heterogeneous sequence, `(T, U, ..)`.
 278 ///
 279 /// To access the _N_-th element of a tuple one can use `N` itself
 280 /// as a field of the tuple.
 281 ///
 282 /// Indexing starts from zero, so `0` returns first value, `1`
 283 /// returns second value, and so on. In general, a tuple with _S_
 284 /// elements provides aforementioned fields from `0` to `S-1`.
 285 ///
 286 /// If every type inside a tuple implements one of the following
 287 /// traits, then a tuple itself also implements it.
 288 ///
 289 /// * `Clone`
 290 /// * `PartialEq`
 291 /// * `Eq`
 292 /// * `PartialOrd`
 293 /// * `Ord`
 294 /// * `Debug`
 295 /// * `Default`
 296 /// * `Hash`
 297 ///
 298 /// # Examples
 299 ///
 300 /// Accessing elements of a tuple at specified indices:
 301 ///
 302 /// ```
 303 /// let x = ("colorless",  "green", "ideas", "sleep", "furiously");
 304 /// assert_eq!(x.3, "sleep");
 305 ///
 306 /// let v = (3, 3);
 307 /// let u = (1, -5);
 308 /// assert_eq!(v.0 * u.0 + v.1 * u.1, -12);
 309 /// ```
 310 ///
 311 /// Using traits implemented for tuples:
 312 ///
 313 /// ```
 314 /// let a = (1, 2);
 315 /// let b = (3, 4);
 316 /// assert!(a != b);
 317 ///
 318 /// let c = b.clone();
 319 /// assert!(b == c);
 320 ///
 321 /// let d : (u32, f32) = Default::default();
 322 /// assert_eq!(d, (0, 0.0f32));
 323 /// ```
 324 ///
 325 mod prim_tuple { }
 326
 327 #[doc(primitive = "f32")]
 328 /// The 32-bit floating point type.
 329 ///
 330 /// *[See also the `std::f32` module](f32/index.html).*
 331 ///
 332 mod prim_f32 { }
 333
 334 #[doc(primitive = "f64")]
 335 //
 336 /// The 64-bit floating point type.
 337 ///
 338 /// *[See also the `std::f64` module](f64/index.html).*
 339 ///
 340 mod prim_f64 { }
 341
 342 #[doc(primitive = "i8")]
 343 //
 344 /// The 8-bit signed integer type.
 345 ///
 346 /// *[See also the `std::i8` module](i8/index.html).*
 347 ///
 348 mod prim_i8 { }
 349
 350 #[doc(primitive = "i16")]
 351 //
 352 /// The 16-bit signed integer type.
 353 ///
 354 /// *[See also the `std::i16` module](i16/index.html).*
 355 ///
 356 mod prim_i16 { }
 357
 358 #[doc(primitive = "i32")]
 359 //
 360 /// The 32-bit signed integer type.
 361 ///
 362 /// *[See also the `std::i32` module](i32/index.html).*
 363 ///
 364 mod prim_i32 { }
 365
 366 #[doc(primitive = "i64")]
 367 //
 368 /// The 64-bit signed integer type.
 369 ///
 370 /// *[See also the `std::i64` module](i64/index.html).*
 371 ///
 372 mod prim_i64 { }
 373
 374 #[doc(primitive = "u8")]
 375 //
 376 /// The 8-bit unsigned integer type.
 377 ///
 378 /// *[See also the `std::u8` module](u8/index.html).*
 379 ///
 380 mod prim_u8 { }
 381
 382 #[doc(primitive = "u16")]
 383 //
 384 /// The 16-bit unsigned integer type.
 385 ///
 386 /// *[See also the `std::u16` module](u16/index.html).*
 387 ///
 388 mod prim_u16 { }
 389
 390 #[doc(primitive = "u32")]
 391 //
 392 /// The 32-bit unsigned integer type.
 393 ///
 394 /// *[See also the `std::u32` module](u32/index.html).*
 395 ///
 396 mod prim_u32 { }
 397
 398 #[doc(primitive = "u64")]
 399 //
 400 /// The 64-bit unsigned integer type.
 401 ///
 402 /// *[See also the `std::u64` module](u64/index.html).*
 403 ///
 404 mod prim_u64 { }
 405
 406 #[doc(primitive = "isize")]
 407 //
 408 /// The pointer-sized signed integer type.
 409 ///
 410 /// *[See also the `std::isize` module](isize/index.html).*
 411 ///
 412 mod prim_isize { }
 413
 414 #[doc(primitive = "usize")]
 415 //
 416 /// The pointer-sized unsigned integer type.
 417 ///
 418 /// *[See also the `std::usize` module](usize/index.html).*
 419 ///
 420 mod prim_usize { }
 421