]> git.proxmox.com Git - rustc.git/blob - library/core/src/primitive_docs.rs
New upstream version 1.63.0+dfsg1
[rustc.git] / library / core / src / primitive_docs.rs
1 // `library/{std,core}/src/primitive_docs.rs` should have the same contents.
2 // These are different files so that relative links work properly without
3 // having to have `CARGO_PKG_NAME` set, but conceptually they should always be the same.
4 #[doc(primitive = "bool")]
5 #[doc(alias = "true")]
6 #[doc(alias = "false")]
7 /// The boolean type.
8 ///
9 /// The `bool` represents a value, which could only be either [`true`] or [`false`]. If you cast
10 /// a `bool` into an integer, [`true`] will be 1 and [`false`] will be 0.
11 ///
12 /// # Basic usage
13 ///
14 /// `bool` implements various traits, such as [`BitAnd`], [`BitOr`], [`Not`], etc.,
15 /// which allow us to perform boolean operations using `&`, `|` and `!`.
16 ///
17 /// [`if`] requires a `bool` value as its conditional. [`assert!`], which is an
18 /// important macro in testing, checks whether an expression is [`true`] and panics
19 /// if it isn't.
20 ///
21 /// ```
22 /// let bool_val = true & false | false;
23 /// assert!(!bool_val);
24 /// ```
25 ///
26 /// [`true`]: ../std/keyword.true.html
27 /// [`false`]: ../std/keyword.false.html
28 /// [`BitAnd`]: ops::BitAnd
29 /// [`BitOr`]: ops::BitOr
30 /// [`Not`]: ops::Not
31 /// [`if`]: ../std/keyword.if.html
32 ///
33 /// # Examples
34 ///
35 /// A trivial example of the usage of `bool`:
36 ///
37 /// ```
38 /// let praise_the_borrow_checker = true;
39 ///
40 /// // using the `if` conditional
41 /// if praise_the_borrow_checker {
42 /// println!("oh, yeah!");
43 /// } else {
44 /// println!("what?!!");
45 /// }
46 ///
47 /// // ... or, a match pattern
48 /// match praise_the_borrow_checker {
49 /// true => println!("keep praising!"),
50 /// false => println!("you should praise!"),
51 /// }
52 /// ```
53 ///
54 /// Also, since `bool` implements the [`Copy`] trait, we don't
55 /// have to worry about the move semantics (just like the integer and float primitives).
56 ///
57 /// Now an example of `bool` cast to integer type:
58 ///
59 /// ```
60 /// assert_eq!(true as i32, 1);
61 /// assert_eq!(false as i32, 0);
62 /// ```
63 #[stable(feature = "rust1", since = "1.0.0")]
64 mod prim_bool {}
65
66 #[doc(primitive = "never")]
67 #[doc(alias = "!")]
68 //
69 /// The `!` type, also called "never".
70 ///
71 /// `!` represents the type of computations which never resolve to any value at all. For example,
72 /// the [`exit`] function `fn exit(code: i32) -> !` exits the process without ever returning, and
73 /// so returns `!`.
74 ///
75 /// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to
76 /// write:
77 ///
78 /// ```
79 /// #![feature(never_type)]
80 /// # fn foo() -> u32 {
81 /// let x: ! = {
82 /// return 123
83 /// };
84 /// # }
85 /// ```
86 ///
87 /// Although the `let` is pointless here, it illustrates the meaning of `!`. Since `x` is never
88 /// assigned a value (because `return` returns from the entire function), `x` can be given type
89 /// `!`. We could also replace `return 123` with a `panic!` or a never-ending `loop` and this code
90 /// would still be valid.
91 ///
92 /// A more realistic usage of `!` is in this code:
93 ///
94 /// ```
95 /// # fn get_a_number() -> Option<u32> { None }
96 /// # loop {
97 /// let num: u32 = match get_a_number() {
98 /// Some(num) => num,
99 /// None => break,
100 /// };
101 /// # }
102 /// ```
103 ///
104 /// Both match arms must produce values of type [`u32`], but since `break` never produces a value
105 /// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another
106 /// behaviour of the `!` type - expressions with type `!` will coerce into any other type.
107 ///
108 /// [`u32`]: prim@u32
109 #[doc = concat!("[`exit`]: ", include_str!("../primitive_docs/process_exit.md"))]
110 ///
111 /// # `!` and generics
112 ///
113 /// ## Infallible errors
114 ///
115 /// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`]
116 /// trait:
117 ///
118 /// ```
119 /// trait FromStr: Sized {
120 /// type Err;
121 /// fn from_str(s: &str) -> Result<Self, Self::Err>;
122 /// }
123 /// ```
124 ///
125 /// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since
126 /// converting a string into a string will never result in an error, the appropriate type is `!`.
127 /// (Currently the type actually used is an enum with no variants, though this is only because `!`
128 /// was added to Rust at a later date and it may change in the future.) With an [`Err`] type of
129 /// `!`, if we have to call [`String::from_str`] for some reason the result will be a
130 /// [`Result<String, !>`] which we can unpack like this:
131 ///
132 /// ```
133 /// #![feature(exhaustive_patterns)]
134 /// use std::str::FromStr;
135 /// let Ok(s) = String::from_str("hello");
136 /// ```
137 ///
138 /// Since the [`Err`] variant contains a `!`, it can never occur. If the `exhaustive_patterns`
139 /// feature is present this means we can exhaustively match on [`Result<T, !>`] by just taking the
140 /// [`Ok`] variant. This illustrates another behaviour of `!` - it can be used to "delete" certain
141 /// enum variants from generic types like `Result`.
142 ///
143 /// ## Infinite loops
144 ///
145 /// While [`Result<T, !>`] is very useful for removing errors, `!` can also be used to remove
146 /// successes as well. If we think of [`Result<T, !>`] as "if this function returns, it has not
147 /// errored," we get a very intuitive idea of [`Result<!, E>`] as well: if the function returns, it
148 /// *has* errored.
149 ///
150 /// For example, consider the case of a simple web server, which can be simplified to:
151 ///
152 /// ```ignore (hypothetical-example)
153 /// loop {
154 /// let (client, request) = get_request().expect("disconnected");
155 /// let response = request.process();
156 /// response.send(client);
157 /// }
158 /// ```
159 ///
160 /// Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection.
161 /// Instead, we'd like to keep track of this error, like this:
162 ///
163 /// ```ignore (hypothetical-example)
164 /// loop {
165 /// match get_request() {
166 /// Err(err) => break err,
167 /// Ok((client, request)) => {
168 /// let response = request.process();
169 /// response.send(client);
170 /// },
171 /// }
172 /// }
173 /// ```
174 ///
175 /// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it
176 /// might be intuitive to simply return the error, we might want to wrap it in a [`Result<!, E>`]
177 /// instead:
178 ///
179 /// ```ignore (hypothetical-example)
180 /// fn server_loop() -> Result<!, ConnectionError> {
181 /// loop {
182 /// let (client, request) = get_request()?;
183 /// let response = request.process();
184 /// response.send(client);
185 /// }
186 /// }
187 /// ```
188 ///
189 /// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop
190 /// ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok`
191 /// because `!` coerces to `Result<!, ConnectionError>` automatically.
192 ///
193 /// [`String::from_str`]: str::FromStr::from_str
194 #[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))]
195 /// [`FromStr`]: str::FromStr
196 ///
197 /// # `!` and traits
198 ///
199 /// When writing your own traits, `!` should have an `impl` whenever there is an obvious `impl`
200 /// which doesn't `panic!`. The reason is that functions returning an `impl Trait` where `!`
201 /// does not have an `impl` of `Trait` cannot diverge as their only possible code path. In other
202 /// words, they can't return `!` from every code path. As an example, this code doesn't compile:
203 ///
204 /// ```compile_fail
205 /// use std::ops::Add;
206 ///
207 /// fn foo() -> impl Add<u32> {
208 /// unimplemented!()
209 /// }
210 /// ```
211 ///
212 /// But this code does:
213 ///
214 /// ```
215 /// use std::ops::Add;
216 ///
217 /// fn foo() -> impl Add<u32> {
218 /// if true {
219 /// unimplemented!()
220 /// } else {
221 /// 0
222 /// }
223 /// }
224 /// ```
225 ///
226 /// The reason is that, in the first example, there are many possible types that `!` could coerce
227 /// to, because many types implement `Add<u32>`. However, in the second example,
228 /// the `else` branch returns a `0`, which the compiler infers from the return type to be of type
229 /// `u32`. Since `u32` is a concrete type, `!` can and will be coerced to it. See issue [#36375]
230 /// for more information on this quirk of `!`.
231 ///
232 /// [#36375]: https://github.com/rust-lang/rust/issues/36375
233 ///
234 /// As it turns out, though, most traits can have an `impl` for `!`. Take [`Debug`]
235 /// for example:
236 ///
237 /// ```
238 /// #![feature(never_type)]
239 /// # use std::fmt;
240 /// # trait Debug {
241 /// # fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result;
242 /// # }
243 /// impl Debug for ! {
244 /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
245 /// *self
246 /// }
247 /// }
248 /// ```
249 ///
250 /// Once again we're using `!`'s ability to coerce into any other type, in this case
251 /// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be
252 /// called (because there is no value of type `!` for it to be called with). Writing `*self`
253 /// essentially tells the compiler "We know that this code can never be run, so just treat the
254 /// entire function body as having type [`fmt::Result`]". This pattern can be used a lot when
255 /// implementing traits for `!`. Generally, any trait which only has methods which take a `self`
256 /// parameter should have such an impl.
257 ///
258 /// On the other hand, one trait which would not be appropriate to implement is [`Default`]:
259 ///
260 /// ```
261 /// trait Default {
262 /// fn default() -> Self;
263 /// }
264 /// ```
265 ///
266 /// Since `!` has no values, it has no default value either. It's true that we could write an
267 /// `impl` for this which simply panics, but the same is true for any type (we could `impl
268 /// Default` for (eg.) [`File`] by just making [`default()`] panic.)
269 ///
270 #[doc = concat!("[`File`]: ", include_str!("../primitive_docs/fs_file.md"))]
271 /// [`Debug`]: fmt::Debug
272 /// [`default()`]: Default::default
273 ///
274 #[unstable(feature = "never_type", issue = "35121")]
275 mod prim_never {}
276
277 #[doc(primitive = "char")]
278 #[allow(rustdoc::invalid_rust_codeblocks)]
279 /// A character type.
280 ///
281 /// The `char` type represents a single character. More specifically, since
282 /// 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode
283 /// scalar value]'.
284 ///
285 /// This documentation describes a number of methods and trait implementations on the
286 /// `char` type. For technical reasons, there is additional, separate
287 /// documentation in [the `std::char` module](char/index.html) as well.
288 ///
289 /// # Validity
290 ///
291 /// A `char` is a '[Unicode scalar value]', which is any '[Unicode code point]'
292 /// other than a [surrogate code point]. This has a fixed numerical definition:
293 /// code points are in the range 0 to 0x10FFFF, inclusive.
294 /// Surrogate code points, used by UTF-16, are in the range 0xD800 to 0xDFFF.
295 ///
296 /// No `char` may be constructed, whether as a literal or at runtime, that is not a
297 /// Unicode scalar value:
298 ///
299 /// ```compile_fail
300 /// // Each of these is a compiler error
301 /// ['\u{D800}', '\u{DFFF}', '\u{110000}'];
302 /// ```
303 ///
304 /// ```should_panic
305 /// // Panics; from_u32 returns None.
306 /// char::from_u32(0xDE01).unwrap();
307 /// ```
308 ///
309 /// ```no_run
310 /// // Undefined behaviour
311 /// unsafe { char::from_u32_unchecked(0x110000) };
312 /// ```
313 ///
314 /// USVs are also the exact set of values that may be encoded in UTF-8. Because
315 /// `char` values are USVs and `str` values are valid UTF-8, it is safe to store
316 /// any `char` in a `str` or read any character from a `str` as a `char`.
317 ///
318 /// The gap in valid `char` values is understood by the compiler, so in the
319 /// below example the two ranges are understood to cover the whole range of
320 /// possible `char` values and there is no error for a [non-exhaustive match].
321 ///
322 /// ```
323 /// let c: char = 'a';
324 /// match c {
325 /// '\0' ..= '\u{D7FF}' => false,
326 /// '\u{E000}' ..= '\u{10FFFF}' => true,
327 /// };
328 /// ```
329 ///
330 /// All USVs are valid `char` values, but not all of them represent a real
331 /// character. Many USVs are not currently assigned to a character, but may be
332 /// in the future ("reserved"); some will never be a character
333 /// ("noncharacters"); and some may be given different meanings by different
334 /// users ("private use").
335 ///
336 /// [Unicode code point]: https://www.unicode.org/glossary/#code_point
337 /// [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value
338 /// [non-exhaustive match]: ../book/ch06-02-match.html#matches-are-exhaustive
339 /// [surrogate code point]: https://www.unicode.org/glossary/#surrogate_code_point
340 ///
341 /// # Representation
342 ///
343 /// `char` is always four bytes in size. This is a different representation than
344 /// a given character would have as part of a [`String`]. For example:
345 ///
346 /// ```
347 /// let v = vec!['h', 'e', 'l', 'l', 'o'];
348 ///
349 /// // five elements times four bytes for each element
350 /// assert_eq!(20, v.len() * std::mem::size_of::<char>());
351 ///
352 /// let s = String::from("hello");
353 ///
354 /// // five elements times one byte per element
355 /// assert_eq!(5, s.len() * std::mem::size_of::<u8>());
356 /// ```
357 ///
358 #[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))]
359 ///
360 /// As always, remember that a human intuition for 'character' might not map to
361 /// Unicode's definitions. For example, despite looking similar, the 'é'
362 /// character is one Unicode code point while 'é' is two Unicode code points:
363 ///
364 /// ```
365 /// let mut chars = "é".chars();
366 /// // U+00e9: 'latin small letter e with acute'
367 /// assert_eq!(Some('\u{00e9}'), chars.next());
368 /// assert_eq!(None, chars.next());
369 ///
370 /// let mut chars = "é".chars();
371 /// // U+0065: 'latin small letter e'
372 /// assert_eq!(Some('\u{0065}'), chars.next());
373 /// // U+0301: 'combining acute accent'
374 /// assert_eq!(Some('\u{0301}'), chars.next());
375 /// assert_eq!(None, chars.next());
376 /// ```
377 ///
378 /// This means that the contents of the first string above _will_ fit into a
379 /// `char` while the contents of the second string _will not_. Trying to create
380 /// a `char` literal with the contents of the second string gives an error:
381 ///
382 /// ```text
383 /// error: character literal may only contain one codepoint: 'é'
384 /// let c = 'é';
385 /// ^^^
386 /// ```
387 ///
388 /// Another implication of the 4-byte fixed size of a `char` is that
389 /// per-`char` processing can end up using a lot more memory:
390 ///
391 /// ```
392 /// let s = String::from("love: ❤️");
393 /// let v: Vec<char> = s.chars().collect();
394 ///
395 /// assert_eq!(12, std::mem::size_of_val(&s[..]));
396 /// assert_eq!(32, std::mem::size_of_val(&v[..]));
397 /// ```
398 #[stable(feature = "rust1", since = "1.0.0")]
399 mod prim_char {}
400
401 #[doc(primitive = "unit")]
402 #[doc(alias = "(")]
403 #[doc(alias = ")")]
404 #[doc(alias = "()")]
405 //
406 /// The `()` type, also called "unit".
407 ///
408 /// The `()` type has exactly one value `()`, and is used when there
409 /// is no other meaningful value that could be returned. `()` is most
410 /// commonly seen implicitly: functions without a `-> ...` implicitly
411 /// have return type `()`, that is, these are equivalent:
412 ///
413 /// ```rust
414 /// fn long() -> () {}
415 ///
416 /// fn short() {}
417 /// ```
418 ///
419 /// The semicolon `;` can be used to discard the result of an
420 /// expression at the end of a block, making the expression (and thus
421 /// the block) evaluate to `()`. For example,
422 ///
423 /// ```rust
424 /// fn returns_i64() -> i64 {
425 /// 1i64
426 /// }
427 /// fn returns_unit() {
428 /// 1i64;
429 /// }
430 ///
431 /// let is_i64 = {
432 /// returns_i64()
433 /// };
434 /// let is_unit = {
435 /// returns_i64();
436 /// };
437 /// ```
438 ///
439 #[stable(feature = "rust1", since = "1.0.0")]
440 mod prim_unit {}
441
442 // Required to make auto trait impls render.
443 // See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls
444 #[doc(hidden)]
445 impl () {}
446
447 // Fake impl that's only really used for docs.
448 #[cfg(doc)]
449 #[stable(feature = "rust1", since = "1.0.0")]
450 impl Clone for () {
451 fn clone(&self) -> Self {
452 loop {}
453 }
454 }
455
456 // Fake impl that's only really used for docs.
457 #[cfg(doc)]
458 #[stable(feature = "rust1", since = "1.0.0")]
459 impl Copy for () {
460 // empty
461 }
462
463 #[doc(primitive = "pointer")]
464 #[doc(alias = "ptr")]
465 #[doc(alias = "*")]
466 #[doc(alias = "*const")]
467 #[doc(alias = "*mut")]
468 //
469 /// Raw, unsafe pointers, `*const T`, and `*mut T`.
470 ///
471 /// *[See also the `std::ptr` module](ptr).*
472 ///
473 /// Working with raw pointers in Rust is uncommon, typically limited to a few patterns.
474 /// Raw pointers can be unaligned or [`null`]. However, when a raw pointer is
475 /// dereferenced (using the `*` operator), it must be non-null and aligned.
476 ///
477 /// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so
478 /// [`write`] must be used if the type has drop glue and memory is not already
479 /// initialized - otherwise `drop` would be called on the uninitialized memory.
480 ///
481 /// Use the [`null`] and [`null_mut`] functions to create null pointers, and the
482 /// [`is_null`] method of the `*const T` and `*mut T` types to check for null.
483 /// The `*const T` and `*mut T` types also define the [`offset`] method, for
484 /// pointer math.
485 ///
486 /// # Common ways to create raw pointers
487 ///
488 /// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`).
489 ///
490 /// ```
491 /// let my_num: i32 = 10;
492 /// let my_num_ptr: *const i32 = &my_num;
493 /// let mut my_speed: i32 = 88;
494 /// let my_speed_ptr: *mut i32 = &mut my_speed;
495 /// ```
496 ///
497 /// To get a pointer to a boxed value, dereference the box:
498 ///
499 /// ```
500 /// let my_num: Box<i32> = Box::new(10);
501 /// let my_num_ptr: *const i32 = &*my_num;
502 /// let mut my_speed: Box<i32> = Box::new(88);
503 /// let my_speed_ptr: *mut i32 = &mut *my_speed;
504 /// ```
505 ///
506 /// This does not take ownership of the original allocation
507 /// and requires no resource management later,
508 /// but you must not use the pointer after its lifetime.
509 ///
510 /// ## 2. Consume a box (`Box<T>`).
511 ///
512 /// The [`into_raw`] function consumes a box and returns
513 /// the raw pointer. It doesn't destroy `T` or deallocate any memory.
514 ///
515 /// ```
516 /// let my_speed: Box<i32> = Box::new(88);
517 /// let my_speed: *mut i32 = Box::into_raw(my_speed);
518 ///
519 /// // By taking ownership of the original `Box<T>` though
520 /// // we are obligated to put it together later to be destroyed.
521 /// unsafe {
522 /// drop(Box::from_raw(my_speed));
523 /// }
524 /// ```
525 ///
526 /// Note that here the call to [`drop`] is for clarity - it indicates
527 /// that we are done with the given value and it should be destroyed.
528 ///
529 /// ## 3. Create it using `ptr::addr_of!`
530 ///
531 /// Instead of coercing a reference to a raw pointer, you can use the macros
532 /// [`ptr::addr_of!`] (for `*const T`) and [`ptr::addr_of_mut!`] (for `*mut T`).
533 /// These macros allow you to create raw pointers to fields to which you cannot
534 /// create a reference (without causing undefined behaviour), such as an
535 /// unaligned field. This might be necessary if packed structs or uninitialized
536 /// memory is involved.
537 ///
538 /// ```
539 /// #[derive(Debug, Default, Copy, Clone)]
540 /// #[repr(C, packed)]
541 /// struct S {
542 /// aligned: u8,
543 /// unaligned: u32,
544 /// }
545 /// let s = S::default();
546 /// let p = std::ptr::addr_of!(s.unaligned); // not allowed with coercion
547 /// ```
548 ///
549 /// ## 4. Get it from C.
550 ///
551 /// ```
552 /// # #![feature(rustc_private)]
553 /// extern crate libc;
554 ///
555 /// use std::mem;
556 ///
557 /// unsafe {
558 /// let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>()) as *mut i32;
559 /// if my_num.is_null() {
560 /// panic!("failed to allocate memory");
561 /// }
562 /// libc::free(my_num as *mut libc::c_void);
563 /// }
564 /// ```
565 ///
566 /// Usually you wouldn't literally use `malloc` and `free` from Rust,
567 /// but C APIs hand out a lot of pointers generally, so are a common source
568 /// of raw pointers in Rust.
569 ///
570 /// [`null`]: ptr::null
571 /// [`null_mut`]: ptr::null_mut
572 /// [`is_null`]: pointer::is_null
573 /// [`offset`]: pointer::offset
574 #[doc = concat!("[`into_raw`]: ", include_str!("../primitive_docs/box_into_raw.md"))]
575 /// [`drop`]: mem::drop
576 /// [`write`]: ptr::write
577 #[stable(feature = "rust1", since = "1.0.0")]
578 mod prim_pointer {}
579
580 #[doc(primitive = "array")]
581 #[doc(alias = "[]")]
582 #[doc(alias = "[T;N]")] // unfortunately, rustdoc doesn't have fuzzy search for aliases
583 #[doc(alias = "[T; N]")]
584 /// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and the
585 /// non-negative compile-time constant size, `N`.
586 ///
587 /// There are two syntactic forms for creating an array:
588 ///
589 /// * A list with each element, i.e., `[x, y, z]`.
590 /// * A repeat expression `[x; N]`, which produces an array with `N` copies of `x`.
591 /// The type of `x` must be [`Copy`].
592 ///
593 /// Note that `[expr; 0]` is allowed, and produces an empty array.
594 /// This will still evaluate `expr`, however, and immediately drop the resulting value, so
595 /// be mindful of side effects.
596 ///
597 /// Arrays of *any* size implement the following traits if the element type allows it:
598 ///
599 /// - [`Copy`]
600 /// - [`Clone`]
601 /// - [`Debug`]
602 /// - [`IntoIterator`] (implemented for `[T; N]`, `&[T; N]` and `&mut [T; N]`)
603 /// - [`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`]
604 /// - [`Hash`]
605 /// - [`AsRef`], [`AsMut`]
606 /// - [`Borrow`], [`BorrowMut`]
607 ///
608 /// Arrays of sizes from 0 to 32 (inclusive) implement the [`Default`] trait
609 /// if the element type allows it. As a stopgap, trait implementations are
610 /// statically generated up to size 32.
611 ///
612 /// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on
613 /// an array. Indeed, this provides most of the API for working with arrays.
614 /// Slices have a dynamic size and do not coerce to arrays.
615 ///
616 /// You can move elements out of an array with a [slice pattern]. If you want
617 /// one element, see [`mem::replace`].
618 ///
619 /// # Examples
620 ///
621 /// ```
622 /// let mut array: [i32; 3] = [0; 3];
623 ///
624 /// array[1] = 1;
625 /// array[2] = 2;
626 ///
627 /// assert_eq!([1, 2], &array[1..]);
628 ///
629 /// // This loop prints: 0 1 2
630 /// for x in array {
631 /// print!("{x} ");
632 /// }
633 /// ```
634 ///
635 /// You can also iterate over reference to the array's elements:
636 ///
637 /// ```
638 /// let array: [i32; 3] = [0; 3];
639 ///
640 /// for x in &array { }
641 /// ```
642 ///
643 /// You can use a [slice pattern] to move elements out of an array:
644 ///
645 /// ```
646 /// fn move_away(_: String) { /* Do interesting things. */ }
647 ///
648 /// let [john, roa] = ["John".to_string(), "Roa".to_string()];
649 /// move_away(john);
650 /// move_away(roa);
651 /// ```
652 ///
653 /// # Editions
654 ///
655 /// Prior to Rust 1.53, arrays did not implement [`IntoIterator`] by value, so the method call
656 /// `array.into_iter()` auto-referenced into a [slice iterator](slice::iter). Right now, the old
657 /// behavior is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring
658 /// [`IntoIterator`] by value. In the future, the behavior on the 2015 and 2018 edition
659 /// might be made consistent to the behavior of later editions.
660 ///
661 /// ```rust,edition2018
662 /// // Rust 2015 and 2018:
663 ///
664 /// # #![allow(array_into_iter)] // override our `deny(warnings)`
665 /// let array: [i32; 3] = [0; 3];
666 ///
667 /// // This creates a slice iterator, producing references to each value.
668 /// for item in array.into_iter().enumerate() {
669 /// let (i, x): (usize, &i32) = item;
670 /// println!("array[{i}] = {x}");
671 /// }
672 ///
673 /// // The `array_into_iter` lint suggests this change for future compatibility:
674 /// for item in array.iter().enumerate() {
675 /// let (i, x): (usize, &i32) = item;
676 /// println!("array[{i}] = {x}");
677 /// }
678 ///
679 /// // You can explicitly iterate an array by value using `IntoIterator::into_iter`
680 /// for item in IntoIterator::into_iter(array).enumerate() {
681 /// let (i, x): (usize, i32) = item;
682 /// println!("array[{i}] = {x}");
683 /// }
684 /// ```
685 ///
686 /// Starting in the 2021 edition, `array.into_iter()` uses `IntoIterator` normally to iterate
687 /// by value, and `iter()` should be used to iterate by reference like previous editions.
688 ///
689 /// ```rust,edition2021
690 /// // Rust 2021:
691 ///
692 /// let array: [i32; 3] = [0; 3];
693 ///
694 /// // This iterates by reference:
695 /// for item in array.iter().enumerate() {
696 /// let (i, x): (usize, &i32) = item;
697 /// println!("array[{i}] = {x}");
698 /// }
699 ///
700 /// // This iterates by value:
701 /// for item in array.into_iter().enumerate() {
702 /// let (i, x): (usize, i32) = item;
703 /// println!("array[{i}] = {x}");
704 /// }
705 /// ```
706 ///
707 /// Future language versions might start treating the `array.into_iter()`
708 /// syntax on editions 2015 and 2018 the same as on edition 2021. So code using
709 /// those older editions should still be written with this change in mind, to
710 /// prevent breakage in the future. The safest way to accomplish this is to
711 /// avoid the `into_iter` syntax on those editions. If an edition update is not
712 /// viable/desired, there are multiple alternatives:
713 /// * use `iter`, equivalent to the old behavior, creating references
714 /// * use [`IntoIterator::into_iter`], equivalent to the post-2021 behavior (Rust 1.53+)
715 /// * replace `for ... in array.into_iter() {` with `for ... in array {`,
716 /// equivalent to the post-2021 behavior (Rust 1.53+)
717 ///
718 /// ```rust,edition2018
719 /// // Rust 2015 and 2018:
720 ///
721 /// let array: [i32; 3] = [0; 3];
722 ///
723 /// // This iterates by reference:
724 /// for item in array.iter() {
725 /// let x: &i32 = item;
726 /// println!("{x}");
727 /// }
728 ///
729 /// // This iterates by value:
730 /// for item in IntoIterator::into_iter(array) {
731 /// let x: i32 = item;
732 /// println!("{x}");
733 /// }
734 ///
735 /// // This iterates by value:
736 /// for item in array {
737 /// let x: i32 = item;
738 /// println!("{x}");
739 /// }
740 ///
741 /// // IntoIter can also start a chain.
742 /// // This iterates by value:
743 /// for item in IntoIterator::into_iter(array).enumerate() {
744 /// let (i, x): (usize, i32) = item;
745 /// println!("array[{i}] = {x}");
746 /// }
747 /// ```
748 ///
749 /// [slice]: prim@slice
750 /// [`Debug`]: fmt::Debug
751 /// [`Hash`]: hash::Hash
752 /// [`Borrow`]: borrow::Borrow
753 /// [`BorrowMut`]: borrow::BorrowMut
754 /// [slice pattern]: ../reference/patterns.html#slice-patterns
755 #[stable(feature = "rust1", since = "1.0.0")]
756 mod prim_array {}
757
758 #[doc(primitive = "slice")]
759 #[doc(alias = "[")]
760 #[doc(alias = "]")]
761 #[doc(alias = "[]")]
762 /// A dynamically-sized view into a contiguous sequence, `[T]`. Contiguous here
763 /// means that elements are laid out so that every element is the same
764 /// distance from its neighbors.
765 ///
766 /// *[See also the `std::slice` module](crate::slice).*
767 ///
768 /// Slices are a view into a block of memory represented as a pointer and a
769 /// length.
770 ///
771 /// ```
772 /// // slicing a Vec
773 /// let vec = vec![1, 2, 3];
774 /// let int_slice = &vec[..];
775 /// // coercing an array to a slice
776 /// let str_slice: &[&str] = &["one", "two", "three"];
777 /// ```
778 ///
779 /// Slices are either mutable or shared. The shared slice type is `&[T]`,
780 /// while the mutable slice type is `&mut [T]`, where `T` represents the element
781 /// type. For example, you can mutate the block of memory that a mutable slice
782 /// points to:
783 ///
784 /// ```
785 /// let mut x = [1, 2, 3];
786 /// let x = &mut x[..]; // Take a full slice of `x`.
787 /// x[1] = 7;
788 /// assert_eq!(x, &[1, 7, 3]);
789 /// ```
790 ///
791 /// As slices store the length of the sequence they refer to, they have twice
792 /// the size of pointers to [`Sized`](marker/trait.Sized.html) types.
793 /// Also see the reference on
794 /// [dynamically sized types](../reference/dynamically-sized-types.html).
795 ///
796 /// ```
797 /// # use std::rc::Rc;
798 /// let pointer_size = std::mem::size_of::<&u8>();
799 /// assert_eq!(2 * pointer_size, std::mem::size_of::<&[u8]>());
800 /// assert_eq!(2 * pointer_size, std::mem::size_of::<*const [u8]>());
801 /// assert_eq!(2 * pointer_size, std::mem::size_of::<Box<[u8]>>());
802 /// assert_eq!(2 * pointer_size, std::mem::size_of::<Rc<[u8]>>());
803 /// ```
804 #[stable(feature = "rust1", since = "1.0.0")]
805 mod prim_slice {}
806
807 #[doc(primitive = "str")]
808 //
809 /// String slices.
810 ///
811 /// *[See also the `std::str` module](crate::str).*
812 ///
813 /// The `str` type, also called a 'string slice', is the most primitive string
814 /// type. It is usually seen in its borrowed form, `&str`. It is also the type
815 /// of string literals, `&'static str`.
816 ///
817 /// String slices are always valid UTF-8.
818 ///
819 /// # Examples
820 ///
821 /// String literals are string slices:
822 ///
823 /// ```
824 /// let hello = "Hello, world!";
825 ///
826 /// // with an explicit type annotation
827 /// let hello: &'static str = "Hello, world!";
828 /// ```
829 ///
830 /// They are `'static` because they're stored directly in the final binary, and
831 /// so will be valid for the `'static` duration.
832 ///
833 /// # Representation
834 ///
835 /// A `&str` is made up of two components: a pointer to some bytes, and a
836 /// length. You can look at these with the [`as_ptr`] and [`len`] methods:
837 ///
838 /// ```
839 /// use std::slice;
840 /// use std::str;
841 ///
842 /// let story = "Once upon a time...";
843 ///
844 /// let ptr = story.as_ptr();
845 /// let len = story.len();
846 ///
847 /// // story has nineteen bytes
848 /// assert_eq!(19, len);
849 ///
850 /// // We can re-build a str out of ptr and len. This is all unsafe because
851 /// // we are responsible for making sure the two components are valid:
852 /// let s = unsafe {
853 /// // First, we build a &[u8]...
854 /// let slice = slice::from_raw_parts(ptr, len);
855 ///
856 /// // ... and then convert that slice into a string slice
857 /// str::from_utf8(slice)
858 /// };
859 ///
860 /// assert_eq!(s, Ok(story));
861 /// ```
862 ///
863 /// [`as_ptr`]: str::as_ptr
864 /// [`len`]: str::len
865 ///
866 /// Note: This example shows the internals of `&str`. `unsafe` should not be
867 /// used to get a string slice under normal circumstances. Use `as_str`
868 /// instead.
869 #[stable(feature = "rust1", since = "1.0.0")]
870 mod prim_str {}
871
872 #[doc(primitive = "tuple")]
873 #[doc(alias = "(")]
874 #[doc(alias = ")")]
875 #[doc(alias = "()")]
876 //
877 /// A finite heterogeneous sequence, `(T, U, ..)`.
878 ///
879 /// Let's cover each of those in turn:
880 ///
881 /// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple
882 /// of length `3`:
883 ///
884 /// ```
885 /// ("hello", 5, 'c');
886 /// ```
887 ///
888 /// 'Length' is also sometimes called 'arity' here; each tuple of a different
889 /// length is a different, distinct type.
890 ///
891 /// Tuples are *heterogeneous*. This means that each element of the tuple can
892 /// have a different type. In that tuple above, it has the type:
893 ///
894 /// ```
895 /// # let _:
896 /// (&'static str, i32, char)
897 /// # = ("hello", 5, 'c');
898 /// ```
899 ///
900 /// Tuples are a *sequence*. This means that they can be accessed by position;
901 /// this is called 'tuple indexing', and it looks like this:
902 ///
903 /// ```rust
904 /// let tuple = ("hello", 5, 'c');
905 ///
906 /// assert_eq!(tuple.0, "hello");
907 /// assert_eq!(tuple.1, 5);
908 /// assert_eq!(tuple.2, 'c');
909 /// ```
910 ///
911 /// The sequential nature of the tuple applies to its implementations of various
912 /// traits. For example, in [`PartialOrd`] and [`Ord`], the elements are compared
913 /// sequentially until the first non-equal set is found.
914 ///
915 /// For more about tuples, see [the book](../book/ch03-02-data-types.html#the-tuple-type).
916 ///
917 // Hardcoded anchor in src/librustdoc/html/format.rs
918 // linked to as `#trait-implementations-1`
919 /// # Trait implementations
920 ///
921 /// In this documentation the shorthand `(T₁, T₂, …, Tₙ)` is used to represent tuples of varying
922 /// length. When that is used, any trait bound expressed on `T` applies to each element of the
923 /// tuple independently. Note that this is a convenience notation to avoid repetitive
924 /// documentation, not valid Rust syntax.
925 ///
926 /// Due to a temporary restriction in Rust’s type system, the following traits are only
927 /// implemented on tuples of arity 12 or less. In the future, this may change:
928 ///
929 /// * [`PartialEq`]
930 /// * [`Eq`]
931 /// * [`PartialOrd`]
932 /// * [`Ord`]
933 /// * [`Debug`]
934 /// * [`Default`]
935 /// * [`Hash`]
936 ///
937 /// [`Debug`]: fmt::Debug
938 /// [`Hash`]: hash::Hash
939 ///
940 /// The following traits are implemented for tuples of any length. These traits have
941 /// implementations that are automatically generated by the compiler, so are not limited by
942 /// missing language features.
943 ///
944 /// * [`Clone`]
945 /// * [`Copy`]
946 /// * [`Send`]
947 /// * [`Sync`]
948 /// * [`Unpin`]
949 /// * [`UnwindSafe`]
950 /// * [`RefUnwindSafe`]
951 ///
952 /// [`Unpin`]: marker::Unpin
953 /// [`UnwindSafe`]: panic::UnwindSafe
954 /// [`RefUnwindSafe`]: panic::RefUnwindSafe
955 ///
956 /// # Examples
957 ///
958 /// Basic usage:
959 ///
960 /// ```
961 /// let tuple = ("hello", 5, 'c');
962 ///
963 /// assert_eq!(tuple.0, "hello");
964 /// ```
965 ///
966 /// Tuples are often used as a return type when you want to return more than
967 /// one value:
968 ///
969 /// ```
970 /// fn calculate_point() -> (i32, i32) {
971 /// // Don't do a calculation, that's not the point of the example
972 /// (4, 5)
973 /// }
974 ///
975 /// let point = calculate_point();
976 ///
977 /// assert_eq!(point.0, 4);
978 /// assert_eq!(point.1, 5);
979 ///
980 /// // Combining this with patterns can be nicer.
981 ///
982 /// let (x, y) = calculate_point();
983 ///
984 /// assert_eq!(x, 4);
985 /// assert_eq!(y, 5);
986 /// ```
987 ///
988 #[stable(feature = "rust1", since = "1.0.0")]
989 mod prim_tuple {}
990
991 // Required to make auto trait impls render.
992 // See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls
993 #[doc(hidden)]
994 impl<T> (T,) {}
995
996 // Fake impl that's only really used for docs.
997 #[cfg(doc)]
998 #[stable(feature = "rust1", since = "1.0.0")]
999 #[cfg_attr(not(bootstrap), doc(tuple_variadic))]
1000 /// This trait is implemented on arbitrary-length tuples.
1001 impl<T: Clone> Clone for (T,) {
1002 fn clone(&self) -> Self {
1003 loop {}
1004 }
1005 }
1006
1007 // Fake impl that's only really used for docs.
1008 #[cfg(doc)]
1009 #[stable(feature = "rust1", since = "1.0.0")]
1010 #[cfg_attr(not(bootstrap), doc(tuple_variadic))]
1011 /// This trait is implemented on arbitrary-length tuples.
1012 impl<T: Copy> Copy for (T,) {
1013 // empty
1014 }
1015
1016 #[doc(primitive = "f32")]
1017 /// A 32-bit floating point type (specifically, the "binary32" type defined in IEEE 754-2008).
1018 ///
1019 /// This type can represent a wide range of decimal numbers, like `3.5`, `27`,
1020 /// `-113.75`, `0.0078125`, `34359738368`, `0`, `-1`. So unlike integer types
1021 /// (such as `i32`), floating point types can represent non-integer numbers,
1022 /// too.
1023 ///
1024 /// However, being able to represent this wide range of numbers comes at the
1025 /// cost of precision: floats can only represent some of the real numbers and
1026 /// calculation with floats round to a nearby representable number. For example,
1027 /// `5.0` and `1.0` can be exactly represented as `f32`, but `1.0 / 5.0` results
1028 /// in `0.20000000298023223876953125` since `0.2` cannot be exactly represented
1029 /// as `f32`. Note, however, that printing floats with `println` and friends will
1030 /// often discard insignificant digits: `println!("{}", 1.0f32 / 5.0f32)` will
1031 /// print `0.2`.
1032 ///
1033 /// Additionally, `f32` can represent some special values:
1034 ///
1035 /// - −0.0: IEEE 754 floating point numbers have a bit that indicates their sign, so −0.0 is a
1036 /// possible value. For comparison −0.0 = +0.0, but floating point operations can carry
1037 /// the sign bit through arithmetic operations. This means −0.0 × +0.0 produces −0.0 and
1038 /// a negative number rounded to a value smaller than a float can represent also produces −0.0.
1039 /// - [∞](#associatedconstant.INFINITY) and
1040 /// [−∞](#associatedconstant.NEG_INFINITY): these result from calculations
1041 /// like `1.0 / 0.0`.
1042 /// - [NaN (not a number)](#associatedconstant.NAN): this value results from
1043 /// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected
1044 /// behavior:
1045 /// - It is unequal to any float, including itself! This is the reason `f32`
1046 /// doesn't implement the `Eq` trait.
1047 /// - It is also neither smaller nor greater than any float, making it
1048 /// impossible to sort by the default comparison operation, which is the
1049 /// reason `f32` doesn't implement the `Ord` trait.
1050 /// - It is also considered *infectious* as almost all calculations where one
1051 /// of the operands is NaN will also result in NaN. The explanations on this
1052 /// page only explicitly document behavior on NaN operands if this default
1053 /// is deviated from.
1054 /// - Lastly, there are multiple bit patterns that are considered NaN.
1055 /// Rust does not currently guarantee that the bit patterns of NaN are
1056 /// preserved over arithmetic operations, and they are not guaranteed to be
1057 /// portable or even fully deterministic! This means that there may be some
1058 /// surprising results upon inspecting the bit patterns,
1059 /// as the same calculations might produce NaNs with different bit patterns.
1060 ///
1061 /// When the number resulting from a primitive operation (addition,
1062 /// subtraction, multiplication, or division) on this type is not exactly
1063 /// representable as `f32`, it is rounded according to the roundTiesToEven
1064 /// direction defined in IEEE 754-2008. That means:
1065 ///
1066 /// - The result is the representable value closest to the true value, if there
1067 /// is a unique closest representable value.
1068 /// - If the true value is exactly half-way between two representable values,
1069 /// the result is the one with an even least-significant binary digit.
1070 /// - If the true value's magnitude is ≥ `f32::MAX` + 2<sup>(`f32::MAX_EXP` −
1071 /// `f32::MANTISSA_DIGITS` − 1)</sup>, the result is ∞ or −∞ (preserving the
1072 /// true value's sign).
1073 ///
1074 /// For more information on floating point numbers, see [Wikipedia][wikipedia].
1075 ///
1076 /// *[See also the `std::f32::consts` module](crate::f32::consts).*
1077 ///
1078 /// [wikipedia]: https://en.wikipedia.org/wiki/Single-precision_floating-point_format
1079 #[stable(feature = "rust1", since = "1.0.0")]
1080 mod prim_f32 {}
1081
1082 #[doc(primitive = "f64")]
1083 /// A 64-bit floating point type (specifically, the "binary64" type defined in IEEE 754-2008).
1084 ///
1085 /// This type is very similar to [`f32`], but has increased
1086 /// precision by using twice as many bits. Please see [the documentation for
1087 /// `f32`][`f32`] or [Wikipedia on double precision
1088 /// values][wikipedia] for more information.
1089 ///
1090 /// *[See also the `std::f64::consts` module](crate::f64::consts).*
1091 ///
1092 /// [`f32`]: prim@f32
1093 /// [wikipedia]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format
1094 #[stable(feature = "rust1", since = "1.0.0")]
1095 mod prim_f64 {}
1096
1097 #[doc(primitive = "i8")]
1098 //
1099 /// The 8-bit signed integer type.
1100 #[stable(feature = "rust1", since = "1.0.0")]
1101 mod prim_i8 {}
1102
1103 #[doc(primitive = "i16")]
1104 //
1105 /// The 16-bit signed integer type.
1106 #[stable(feature = "rust1", since = "1.0.0")]
1107 mod prim_i16 {}
1108
1109 #[doc(primitive = "i32")]
1110 //
1111 /// The 32-bit signed integer type.
1112 #[stable(feature = "rust1", since = "1.0.0")]
1113 mod prim_i32 {}
1114
1115 #[doc(primitive = "i64")]
1116 //
1117 /// The 64-bit signed integer type.
1118 #[stable(feature = "rust1", since = "1.0.0")]
1119 mod prim_i64 {}
1120
1121 #[doc(primitive = "i128")]
1122 //
1123 /// The 128-bit signed integer type.
1124 #[stable(feature = "i128", since = "1.26.0")]
1125 mod prim_i128 {}
1126
1127 #[doc(primitive = "u8")]
1128 //
1129 /// The 8-bit unsigned integer type.
1130 #[stable(feature = "rust1", since = "1.0.0")]
1131 mod prim_u8 {}
1132
1133 #[doc(primitive = "u16")]
1134 //
1135 /// The 16-bit unsigned integer type.
1136 #[stable(feature = "rust1", since = "1.0.0")]
1137 mod prim_u16 {}
1138
1139 #[doc(primitive = "u32")]
1140 //
1141 /// The 32-bit unsigned integer type.
1142 #[stable(feature = "rust1", since = "1.0.0")]
1143 mod prim_u32 {}
1144
1145 #[doc(primitive = "u64")]
1146 //
1147 /// The 64-bit unsigned integer type.
1148 #[stable(feature = "rust1", since = "1.0.0")]
1149 mod prim_u64 {}
1150
1151 #[doc(primitive = "u128")]
1152 //
1153 /// The 128-bit unsigned integer type.
1154 #[stable(feature = "i128", since = "1.26.0")]
1155 mod prim_u128 {}
1156
1157 #[doc(primitive = "isize")]
1158 //
1159 /// The pointer-sized signed integer type.
1160 ///
1161 /// The size of this primitive is how many bytes it takes to reference any
1162 /// location in memory. For example, on a 32 bit target, this is 4 bytes
1163 /// and on a 64 bit target, this is 8 bytes.
1164 #[stable(feature = "rust1", since = "1.0.0")]
1165 mod prim_isize {}
1166
1167 #[doc(primitive = "usize")]
1168 //
1169 /// The pointer-sized unsigned integer type.
1170 ///
1171 /// The size of this primitive is how many bytes it takes to reference any
1172 /// location in memory. For example, on a 32 bit target, this is 4 bytes
1173 /// and on a 64 bit target, this is 8 bytes.
1174 #[stable(feature = "rust1", since = "1.0.0")]
1175 mod prim_usize {}
1176
1177 #[doc(primitive = "reference")]
1178 #[doc(alias = "&")]
1179 #[doc(alias = "&mut")]
1180 //
1181 /// References, both shared and mutable.
1182 ///
1183 /// A reference represents a borrow of some owned value. You can get one by using the `&` or `&mut`
1184 /// operators on a value, or by using a [`ref`](../std/keyword.ref.html) or
1185 /// <code>[ref](../std/keyword.ref.html) [mut](../std/keyword.mut.html)</code> pattern.
1186 ///
1187 /// For those familiar with pointers, a reference is just a pointer that is assumed to be
1188 /// aligned, not null, and pointing to memory containing a valid value of `T` - for example,
1189 /// <code>&[bool]</code> can only point to an allocation containing the integer values `1`
1190 /// ([`true`](../std/keyword.true.html)) or `0` ([`false`](../std/keyword.false.html)), but
1191 /// creating a <code>&[bool]</code> that points to an allocation containing
1192 /// the value `3` causes undefined behaviour.
1193 /// In fact, <code>[Option]\<&T></code> has the same memory representation as a
1194 /// nullable but aligned pointer, and can be passed across FFI boundaries as such.
1195 ///
1196 /// In most cases, references can be used much like the original value. Field access, method
1197 /// calling, and indexing work the same (save for mutability rules, of course). In addition, the
1198 /// comparison operators transparently defer to the referent's implementation, allowing references
1199 /// to be compared the same as owned values.
1200 ///
1201 /// References have a lifetime attached to them, which represents the scope for which the borrow is
1202 /// valid. A lifetime is said to "outlive" another one if its representative scope is as long or
1203 /// longer than the other. The `'static` lifetime is the longest lifetime, which represents the
1204 /// total life of the program. For example, string literals have a `'static` lifetime because the
1205 /// text data is embedded into the binary of the program, rather than in an allocation that needs
1206 /// to be dynamically managed.
1207 ///
1208 /// `&mut T` references can be freely coerced into `&T` references with the same referent type, and
1209 /// references with longer lifetimes can be freely coerced into references with shorter ones.
1210 ///
1211 /// Reference equality by address, instead of comparing the values pointed to, is accomplished via
1212 /// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while
1213 /// [`PartialEq`] compares values.
1214 ///
1215 /// ```
1216 /// use std::ptr;
1217 ///
1218 /// let five = 5;
1219 /// let other_five = 5;
1220 /// let five_ref = &five;
1221 /// let same_five_ref = &five;
1222 /// let other_five_ref = &other_five;
1223 ///
1224 /// assert!(five_ref == same_five_ref);
1225 /// assert!(five_ref == other_five_ref);
1226 ///
1227 /// assert!(ptr::eq(five_ref, same_five_ref));
1228 /// assert!(!ptr::eq(five_ref, other_five_ref));
1229 /// ```
1230 ///
1231 /// For more information on how to use references, see [the book's section on "References and
1232 /// Borrowing"][book-refs].
1233 ///
1234 /// [book-refs]: ../book/ch04-02-references-and-borrowing.html
1235 ///
1236 /// # Trait implementations
1237 ///
1238 /// The following traits are implemented for all `&T`, regardless of the type of its referent:
1239 ///
1240 /// * [`Copy`]
1241 /// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!)
1242 /// * [`Deref`]
1243 /// * [`Borrow`]
1244 /// * [`fmt::Pointer`]
1245 ///
1246 /// [`Deref`]: ops::Deref
1247 /// [`Borrow`]: borrow::Borrow
1248 ///
1249 /// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating
1250 /// multiple simultaneous mutable borrows), plus the following, regardless of the type of its
1251 /// referent:
1252 ///
1253 /// * [`DerefMut`]
1254 /// * [`BorrowMut`]
1255 ///
1256 /// [`DerefMut`]: ops::DerefMut
1257 /// [`BorrowMut`]: borrow::BorrowMut
1258 /// [bool]: prim@bool
1259 ///
1260 /// The following traits are implemented on `&T` references if the underlying `T` also implements
1261 /// that trait:
1262 ///
1263 /// * All the traits in [`std::fmt`] except [`fmt::Pointer`] (which is implemented regardless of the type of its referent) and [`fmt::Write`]
1264 /// * [`PartialOrd`]
1265 /// * [`Ord`]
1266 /// * [`PartialEq`]
1267 /// * [`Eq`]
1268 /// * [`AsRef`]
1269 /// * [`Fn`] \(in addition, `&T` references get [`FnMut`] and [`FnOnce`] if `T: Fn`)
1270 /// * [`Hash`]
1271 /// * [`ToSocketAddrs`]
1272 /// * [`Send`] \(`&T` references also require <code>T: [Sync]</code>)
1273 ///
1274 /// [`std::fmt`]: fmt
1275 /// [`Hash`]: hash::Hash
1276 #[doc = concat!("[`ToSocketAddrs`]: ", include_str!("../primitive_docs/net_tosocketaddrs.md"))]
1277 ///
1278 /// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T`
1279 /// implements that trait:
1280 ///
1281 /// * [`AsMut`]
1282 /// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`)
1283 /// * [`fmt::Write`]
1284 /// * [`Iterator`]
1285 /// * [`DoubleEndedIterator`]
1286 /// * [`ExactSizeIterator`]
1287 /// * [`FusedIterator`]
1288 /// * [`TrustedLen`]
1289 /// * [`io::Write`]
1290 /// * [`Read`]
1291 /// * [`Seek`]
1292 /// * [`BufRead`]
1293 ///
1294 /// [`FusedIterator`]: iter::FusedIterator
1295 /// [`TrustedLen`]: iter::TrustedLen
1296 #[doc = concat!("[`Seek`]: ", include_str!("../primitive_docs/io_seek.md"))]
1297 #[doc = concat!("[`BufRead`]: ", include_str!("../primitive_docs/io_bufread.md"))]
1298 #[doc = concat!("[`Read`]: ", include_str!("../primitive_docs/io_read.md"))]
1299 #[doc = concat!("[`io::Write`]: ", include_str!("../primitive_docs/io_write.md"))]
1300 ///
1301 /// Note that due to method call deref coercion, simply calling a trait method will act like they
1302 /// work on references as well as they do on owned values! The implementations described here are
1303 /// meant for generic contexts, where the final type `T` is a type parameter or otherwise not
1304 /// locally known.
1305 #[stable(feature = "rust1", since = "1.0.0")]
1306 mod prim_ref {}
1307
1308 #[doc(primitive = "fn")]
1309 //
1310 /// Function pointers, like `fn(usize) -> bool`.
1311 ///
1312 /// *See also the traits [`Fn`], [`FnMut`], and [`FnOnce`].*
1313 ///
1314 /// [`Fn`]: ops::Fn
1315 /// [`FnMut`]: ops::FnMut
1316 /// [`FnOnce`]: ops::FnOnce
1317 ///
1318 /// Function pointers are pointers that point to *code*, not data. They can be called
1319 /// just like functions. Like references, function pointers are, among other things, assumed to
1320 /// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null
1321 /// pointers, make your type [`Option<fn()>`](core::option#options-and-pointers-nullable-pointers)
1322 /// with your required signature.
1323 ///
1324 /// ### Safety
1325 ///
1326 /// Plain function pointers are obtained by casting either plain functions, or closures that don't
1327 /// capture an environment:
1328 ///
1329 /// ```
1330 /// fn add_one(x: usize) -> usize {
1331 /// x + 1
1332 /// }
1333 ///
1334 /// let ptr: fn(usize) -> usize = add_one;
1335 /// assert_eq!(ptr(5), 6);
1336 ///
1337 /// let clos: fn(usize) -> usize = |x| x + 5;
1338 /// assert_eq!(clos(5), 10);
1339 /// ```
1340 ///
1341 /// In addition to varying based on their signature, function pointers come in two flavors: safe
1342 /// and unsafe. Plain `fn()` function pointers can only point to safe functions,
1343 /// while `unsafe fn()` function pointers can point to safe or unsafe functions.
1344 ///
1345 /// ```
1346 /// fn add_one(x: usize) -> usize {
1347 /// x + 1
1348 /// }
1349 ///
1350 /// unsafe fn add_one_unsafely(x: usize) -> usize {
1351 /// x + 1
1352 /// }
1353 ///
1354 /// let safe_ptr: fn(usize) -> usize = add_one;
1355 ///
1356 /// //ERROR: mismatched types: expected normal fn, found unsafe fn
1357 /// //let bad_ptr: fn(usize) -> usize = add_one_unsafely;
1358 ///
1359 /// let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely;
1360 /// let really_safe_ptr: unsafe fn(usize) -> usize = add_one;
1361 /// ```
1362 ///
1363 /// ### ABI
1364 ///
1365 /// On top of that, function pointers can vary based on what ABI they use. This
1366 /// is achieved by adding the `extern` keyword before the type, followed by the
1367 /// ABI in question. The default ABI is "Rust", i.e., `fn()` is the exact same
1368 /// type as `extern "Rust" fn()`. A pointer to a function with C ABI would have
1369 /// type `extern "C" fn()`.
1370 ///
1371 /// `extern "ABI" { ... }` blocks declare functions with ABI "ABI". The default
1372 /// here is "C", i.e., functions declared in an `extern {...}` block have "C"
1373 /// ABI.
1374 ///
1375 /// For more information and a list of supported ABIs, see [the nomicon's
1376 /// section on foreign calling conventions][nomicon-abi].
1377 ///
1378 /// [nomicon-abi]: ../nomicon/ffi.html#foreign-calling-conventions
1379 ///
1380 /// ### Variadic functions
1381 ///
1382 /// Extern function declarations with the "C" or "cdecl" ABIs can also be *variadic*, allowing them
1383 /// to be called with a variable number of arguments. Normal Rust functions, even those with an
1384 /// `extern "ABI"`, cannot be variadic. For more information, see [the nomicon's section on
1385 /// variadic functions][nomicon-variadic].
1386 ///
1387 /// [nomicon-variadic]: ../nomicon/ffi.html#variadic-functions
1388 ///
1389 /// ### Creating function pointers
1390 ///
1391 /// When `bar` is the name of a function, then the expression `bar` is *not* a
1392 /// function pointer. Rather, it denotes a value of an unnameable type that
1393 /// uniquely identifies the function `bar`. The value is zero-sized because the
1394 /// type already identifies the function. This has the advantage that "calling"
1395 /// the value (it implements the `Fn*` traits) does not require dynamic
1396 /// dispatch.
1397 ///
1398 /// This zero-sized type *coerces* to a regular function pointer. For example:
1399 ///
1400 /// ```rust
1401 /// use std::mem;
1402 ///
1403 /// fn bar(x: i32) {}
1404 ///
1405 /// let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar`
1406 /// assert_eq!(mem::size_of_val(&not_bar_ptr), 0);
1407 ///
1408 /// let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer
1409 /// assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::<usize>());
1410 ///
1411 /// let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar`
1412 /// ```
1413 ///
1414 /// The last line shows that `&bar` is not a function pointer either. Rather, it
1415 /// is a reference to the function-specific ZST. `&bar` is basically never what you
1416 /// want when `bar` is a function.
1417 ///
1418 /// ### Casting to and from integers
1419 ///
1420 /// You cast function pointers directly to integers:
1421 ///
1422 /// ```rust
1423 /// let fnptr: fn(i32) -> i32 = |x| x+2;
1424 /// let fnptr_addr = fnptr as usize;
1425 /// ```
1426 ///
1427 /// However, a direct cast back is not possible. You need to use `transmute`:
1428 ///
1429 /// ```rust
1430 /// # let fnptr: fn(i32) -> i32 = |x| x+2;
1431 /// # let fnptr_addr = fnptr as usize;
1432 /// let fnptr = fnptr_addr as *const ();
1433 /// let fnptr: fn(i32) -> i32 = unsafe { std::mem::transmute(fnptr) };
1434 /// assert_eq!(fnptr(40), 42);
1435 /// ```
1436 ///
1437 /// Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
1438 /// This avoids an integer-to-pointer `transmute`, which can be problematic.
1439 /// Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
1440 ///
1441 /// Note that all of this is not portable to platforms where function pointers and data pointers
1442 /// have different sizes.
1443 ///
1444 /// ### Traits
1445 ///
1446 /// Function pointers implement the following traits:
1447 ///
1448 /// * [`Clone`]
1449 /// * [`PartialEq`]
1450 /// * [`Eq`]
1451 /// * [`PartialOrd`]
1452 /// * [`Ord`]
1453 /// * [`Hash`]
1454 /// * [`Pointer`]
1455 /// * [`Debug`]
1456 ///
1457 /// [`Hash`]: hash::Hash
1458 /// [`Pointer`]: fmt::Pointer
1459 ///
1460 /// Due to a temporary restriction in Rust's type system, these traits are only implemented on
1461 /// functions that take 12 arguments or less, with the `"Rust"` and `"C"` ABIs. In the future, this
1462 /// may change.
1463 ///
1464 /// In addition, function pointers of *any* signature, ABI, or safety are [`Copy`], and all *safe*
1465 /// function pointers implement [`Fn`], [`FnMut`], and [`FnOnce`]. This works because these traits
1466 /// are specially known to the compiler.
1467 #[stable(feature = "rust1", since = "1.0.0")]
1468 mod prim_fn {}