1 #[doc(primitive = "bool")]
3 #[doc(alias = "false")]
6 /// The `bool` represents a value, which could only be either `true` or `false`. If you cast
7 /// a `bool` into an integer, `true` will be 1 and `false` will be 0.
11 /// `bool` implements various traits, such as [`BitAnd`], [`BitOr`], [`Not`], etc.,
12 /// which allow us to perform boolean operations using `&`, `|` and `!`.
14 /// `if` requires a `bool` value as its conditional. [`assert!`], which is an
15 /// important macro in testing, checks whether an expression is `true` and panics
19 /// let bool_val = true & false | false;
20 /// assert!(!bool_val);
23 /// [`BitAnd`]: ops::BitAnd
24 /// [`BitOr`]: ops::BitOr
29 /// A trivial example of the usage of `bool`:
32 /// let praise_the_borrow_checker = true;
34 /// // using the `if` conditional
35 /// if praise_the_borrow_checker {
36 /// println!("oh, yeah!");
38 /// println!("what?!!");
41 /// // ... or, a match pattern
42 /// match praise_the_borrow_checker {
43 /// true => println!("keep praising!"),
44 /// false => println!("you should praise!"),
48 /// Also, since `bool` implements the [`Copy`] trait, we don't
49 /// have to worry about the move semantics (just like the integer and float primitives).
51 /// Now an example of `bool` cast to integer type:
54 /// assert_eq!(true as i32, 1);
55 /// assert_eq!(false as i32, 0);
57 #[stable(feature = "rust1", since = "1.0.0")]
60 #[doc(primitive = "never")]
63 /// The `!` type, also called "never".
65 /// `!` represents the type of computations which never resolve to any value at all. For example,
66 /// the [`exit`] function `fn exit(code: i32) -> !` exits the process without ever returning, and
69 /// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to
73 /// #![feature(never_type)]
74 /// # fn foo() -> u32 {
81 /// Although the `let` is pointless here, it illustrates the meaning of `!`. Since `x` is never
82 /// assigned a value (because `return` returns from the entire function), `x` can be given type
83 /// `!`. We could also replace `return 123` with a `panic!` or a never-ending `loop` and this code
84 /// would still be valid.
86 /// A more realistic usage of `!` is in this code:
89 /// # fn get_a_number() -> Option<u32> { None }
91 /// let num: u32 = match get_a_number() {
98 /// Both match arms must produce values of type [`u32`], but since `break` never produces a value
99 /// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another
100 /// behaviour of the `!` type - expressions with type `!` will coerce into any other type.
102 /// [`u32`]: prim@u32
103 /// [`exit`]: process::exit
105 /// # `!` and generics
107 /// ## Infallible errors
109 /// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`]
113 /// trait FromStr: Sized {
115 /// fn from_str(s: &str) -> Result<Self, Self::Err>;
119 /// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since
120 /// converting a string into a string will never result in an error, the appropriate type is `!`.
121 /// (Currently the type actually used is an enum with no variants, though this is only because `!`
122 /// was added to Rust at a later date and it may change in the future.) With an [`Err`] type of
123 /// `!`, if we have to call [`String::from_str`] for some reason the result will be a
124 /// [`Result<String, !>`] which we can unpack like this:
127 /// #![feature(exhaustive_patterns)]
128 /// use std::str::FromStr;
129 /// let Ok(s) = String::from_str("hello");
132 /// Since the [`Err`] variant contains a `!`, it can never occur. If the `exhaustive_patterns`
133 /// feature is present this means we can exhaustively match on [`Result<T, !>`] by just taking the
134 /// [`Ok`] variant. This illustrates another behaviour of `!` - it can be used to "delete" certain
135 /// enum variants from generic types like `Result`.
137 /// ## Infinite loops
139 /// While [`Result<T, !>`] is very useful for removing errors, `!` can also be used to remove
140 /// successes as well. If we think of [`Result<T, !>`] as "if this function returns, it has not
141 /// errored," we get a very intuitive idea of [`Result<!, E>`] as well: if the function returns, it
144 /// For example, consider the case of a simple web server, which can be simplified to:
146 /// ```ignore (hypothetical-example)
148 /// let (client, request) = get_request().expect("disconnected");
149 /// let response = request.process();
150 /// response.send(client);
154 /// Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection.
155 /// Instead, we'd like to keep track of this error, like this:
157 /// ```ignore (hypothetical-example)
159 /// match get_request() {
160 /// Err(err) => break err,
161 /// Ok((client, request)) => {
162 /// let response = request.process();
163 /// response.send(client);
169 /// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it
170 /// might be intuitive to simply return the error, we might want to wrap it in a [`Result<!, E>`]
173 /// ```ignore (hypothetical-example)
174 /// fn server_loop() -> Result<!, ConnectionError> {
176 /// let (client, request) = get_request()?;
177 /// let response = request.process();
178 /// response.send(client);
183 /// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop
184 /// ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok`
185 /// because `!` coerces to `Result<!, ConnectionError>` automatically.
187 /// [`String::from_str`]: str::FromStr::from_str
188 /// [`String`]: string::String
189 /// [`FromStr`]: str::FromStr
193 /// When writing your own traits, `!` should have an `impl` whenever there is an obvious `impl`
194 /// which doesn't `panic!`. The reason is that functions returning an `impl Trait` where `!`
195 /// does not have an `impl` of `Trait` cannot diverge as their only possible code path. In other
196 /// words, they can't return `!` from every code path. As an example, this code doesn't compile:
199 /// use std::ops::Add;
201 /// fn foo() -> impl Add<u32> {
206 /// But this code does:
209 /// use std::ops::Add;
211 /// fn foo() -> impl Add<u32> {
220 /// The reason is that, in the first example, there are many possible types that `!` could coerce
221 /// to, because many types implement `Add<u32>`. However, in the second example,
222 /// the `else` branch returns a `0`, which the compiler infers from the return type to be of type
223 /// `u32`. Since `u32` is a concrete type, `!` can and will be coerced to it. See issue [#36375]
224 /// for more information on this quirk of `!`.
226 /// [#36375]: https://github.com/rust-lang/rust/issues/36375
228 /// As it turns out, though, most traits can have an `impl` for `!`. Take [`Debug`]
232 /// #![feature(never_type)]
235 /// # fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result;
237 /// impl Debug for ! {
238 /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
244 /// Once again we're using `!`'s ability to coerce into any other type, in this case
245 /// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be
246 /// called (because there is no value of type `!` for it to be called with). Writing `*self`
247 /// essentially tells the compiler "We know that this code can never be run, so just treat the
248 /// entire function body as having type [`fmt::Result`]". This pattern can be used a lot when
249 /// implementing traits for `!`. Generally, any trait which only has methods which take a `self`
250 /// parameter should have such an impl.
252 /// On the other hand, one trait which would not be appropriate to implement is [`Default`]:
256 /// fn default() -> Self;
260 /// Since `!` has no values, it has no default value either. It's true that we could write an
261 /// `impl` for this which simply panics, but the same is true for any type (we could `impl
262 /// Default` for (eg.) [`File`] by just making [`default()`] panic.)
264 /// [`File`]: fs::File
265 /// [`Debug`]: fmt::Debug
266 /// [`default()`]: Default::default
268 #[unstable(feature = "never_type", issue = "35121")]
271 #[doc(primitive = "char")]
273 /// A character type.
275 /// The `char` type represents a single character. More specifically, since
276 /// 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode
277 /// scalar value]', which is similar to, but not the same as, a '[Unicode code
280 /// [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
281 /// [Unicode code point]: http://www.unicode.org/glossary/#code_point
283 /// This documentation describes a number of methods and trait implementations on the
284 /// `char` type. For technical reasons, there is additional, separate
285 /// documentation in [the `std::char` module](char/index.html) as well.
289 /// `char` is always four bytes in size. This is a different representation than
290 /// a given character would have as part of a [`String`]. For example:
293 /// let v = vec!['h', 'e', 'l', 'l', 'o'];
295 /// // five elements times four bytes for each element
296 /// assert_eq!(20, v.len() * std::mem::size_of::<char>());
298 /// let s = String::from("hello");
300 /// // five elements times one byte per element
301 /// assert_eq!(5, s.len() * std::mem::size_of::<u8>());
304 /// [`String`]: string/struct.String.html
306 /// As always, remember that a human intuition for 'character' may not map to
307 /// Unicode's definitions. For example, despite looking similar, the 'é'
308 /// character is one Unicode code point while 'é' is two Unicode code points:
311 /// let mut chars = "é".chars();
312 /// // U+00e9: 'latin small letter e with acute'
313 /// assert_eq!(Some('\u{00e9}'), chars.next());
314 /// assert_eq!(None, chars.next());
316 /// let mut chars = "é".chars();
317 /// // U+0065: 'latin small letter e'
318 /// assert_eq!(Some('\u{0065}'), chars.next());
319 /// // U+0301: 'combining acute accent'
320 /// assert_eq!(Some('\u{0301}'), chars.next());
321 /// assert_eq!(None, chars.next());
324 /// This means that the contents of the first string above _will_ fit into a
325 /// `char` while the contents of the second string _will not_. Trying to create
326 /// a `char` literal with the contents of the second string gives an error:
329 /// error: character literal may only contain one codepoint: 'é'
334 /// Another implication of the 4-byte fixed size of a `char` is that
335 /// per-`char` processing can end up using a lot more memory:
338 /// let s = String::from("love: ❤️");
339 /// let v: Vec<char> = s.chars().collect();
341 /// assert_eq!(12, std::mem::size_of_val(&s[..]));
342 /// assert_eq!(32, std::mem::size_of_val(&v[..]));
344 #[stable(feature = "rust1", since = "1.0.0")]
347 #[doc(primitive = "unit")]
349 /// The `()` type, also called "unit".
351 /// The `()` type has exactly one value `()`, and is used when there
352 /// is no other meaningful value that could be returned. `()` is most
353 /// commonly seen implicitly: functions without a `-> ...` implicitly
354 /// have return type `()`, that is, these are equivalent:
357 /// fn long() -> () {}
362 /// The semicolon `;` can be used to discard the result of an
363 /// expression at the end of a block, making the expression (and thus
364 /// the block) evaluate to `()`. For example,
367 /// fn returns_i64() -> i64 {
370 /// fn returns_unit() {
382 #[stable(feature = "rust1", since = "1.0.0")]
385 #[doc(alias = "ptr")]
386 #[doc(primitive = "pointer")]
388 /// Raw, unsafe pointers, `*const T`, and `*mut T`.
390 /// *[See also the `std::ptr` module](ptr).*
392 /// Working with raw pointers in Rust is uncommon, typically limited to a few patterns.
393 /// Raw pointers can be unaligned or [`null`]. However, when a raw pointer is
394 /// dereferenced (using the `*` operator), it must be non-null and aligned.
396 /// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so
397 /// [`write`] must be used if the type has drop glue and memory is not already
398 /// initialized - otherwise `drop` would be called on the uninitialized memory.
400 /// Use the [`null`] and [`null_mut`] functions to create null pointers, and the
401 /// [`is_null`] method of the `*const T` and `*mut T` types to check for null.
402 /// The `*const T` and `*mut T` types also define the [`offset`] method, for
405 /// # Common ways to create raw pointers
407 /// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`).
410 /// let my_num: i32 = 10;
411 /// let my_num_ptr: *const i32 = &my_num;
412 /// let mut my_speed: i32 = 88;
413 /// let my_speed_ptr: *mut i32 = &mut my_speed;
416 /// To get a pointer to a boxed value, dereference the box:
419 /// let my_num: Box<i32> = Box::new(10);
420 /// let my_num_ptr: *const i32 = &*my_num;
421 /// let mut my_speed: Box<i32> = Box::new(88);
422 /// let my_speed_ptr: *mut i32 = &mut *my_speed;
425 /// This does not take ownership of the original allocation
426 /// and requires no resource management later,
427 /// but you must not use the pointer after its lifetime.
429 /// ## 2. Consume a box (`Box<T>`).
431 /// The [`into_raw`] function consumes a box and returns
432 /// the raw pointer. It doesn't destroy `T` or deallocate any memory.
435 /// let my_speed: Box<i32> = Box::new(88);
436 /// let my_speed: *mut i32 = Box::into_raw(my_speed);
438 /// // By taking ownership of the original `Box<T>` though
439 /// // we are obligated to put it together later to be destroyed.
441 /// drop(Box::from_raw(my_speed));
445 /// Note that here the call to [`drop`] is for clarity - it indicates
446 /// that we are done with the given value and it should be destroyed.
448 /// ## 3. Get it from C.
451 /// # #![feature(rustc_private)]
452 /// extern crate libc;
457 /// let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>()) as *mut i32;
458 /// if my_num.is_null() {
459 /// panic!("failed to allocate memory");
461 /// libc::free(my_num as *mut libc::c_void);
465 /// Usually you wouldn't literally use `malloc` and `free` from Rust,
466 /// but C APIs hand out a lot of pointers generally, so are a common source
467 /// of raw pointers in Rust.
469 /// [`null`]: ptr::null
470 /// [`null_mut`]: ptr::null_mut
471 /// [`is_null`]: pointer::is_null
472 /// [`offset`]: pointer::offset
473 /// [`into_raw`]: Box::into_raw
474 /// [`drop`]: mem::drop
475 /// [`write`]: ptr::write
476 #[stable(feature = "rust1", since = "1.0.0")]
480 #[doc(alias = "[T;N]")] // unfortunately, rustdoc doesn't have fuzzy search for aliases
481 #[doc(alias = "[T; N]")]
482 #[doc(primitive = "array")]
483 /// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and the
484 /// non-negative compile-time constant size, `N`.
486 /// There are two syntactic forms for creating an array:
488 /// * A list with each element, i.e., `[x, y, z]`.
489 /// * A repeat expression `[x; N]`, which produces an array with `N` copies of `x`.
490 /// The type of `x` must be [`Copy`].
492 /// Note that `[expr; 0]` is allowed, and produces an empty array.
493 /// This will still evaluate `expr`, however, and immediately drop the resulting value, so
494 /// be mindful of side effects.
496 /// Arrays of *any* size implement the following traits if the element type allows it:
501 /// - [`IntoIterator`] (implemented for `&[T; N]` and `&mut [T; N]`)
502 /// - [`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`]
504 /// - [`AsRef`], [`AsMut`]
505 /// - [`Borrow`], [`BorrowMut`]
507 /// Arrays of sizes from 0 to 32 (inclusive) implement the [`Default`] trait
508 /// if the element type allows it. As a stopgap, trait implementations are
509 /// statically generated up to size 32.
511 /// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on
512 /// an array. Indeed, this provides most of the API for working with arrays.
513 /// Slices have a dynamic size and do not coerce to arrays.
515 /// You can move elements out of an array with a [slice pattern]. If you want
516 /// one element, see [`mem::replace`].
521 /// let mut array: [i32; 3] = [0; 3];
526 /// assert_eq!([1, 2], &array[1..]);
528 /// // This loop prints: 0 1 2
529 /// for x in &array {
530 /// print!("{} ", x);
534 /// An array itself is not iterable:
536 /// ```compile_fail,E0277
537 /// let array: [i32; 3] = [0; 3];
539 /// for x in array { }
540 /// // error: the trait bound `[i32; 3]: std::iter::Iterator` is not satisfied
543 /// The solution is to coerce the array to a slice by calling a slice method:
546 /// # let array: [i32; 3] = [0; 3];
547 /// for x in array.iter() { }
550 /// You can also use the array reference's [`IntoIterator`] implementation:
553 /// # let array: [i32; 3] = [0; 3];
554 /// for x in &array { }
557 /// You can use a [slice pattern] to move elements out of an array:
560 /// fn move_away(_: String) { /* Do interesting things. */ }
562 /// let [john, roa] = ["John".to_string(), "Roa".to_string()];
567 /// [slice]: prim@slice
568 /// [`Debug`]: fmt::Debug
569 /// [`Hash`]: hash::Hash
570 /// [`Borrow`]: borrow::Borrow
571 /// [`BorrowMut`]: borrow::BorrowMut
572 /// [slice pattern]: ../reference/patterns.html#slice-patterns
573 #[stable(feature = "rust1", since = "1.0.0")]
576 #[doc(primitive = "slice")]
580 /// A dynamically-sized view into a contiguous sequence, `[T]`. Contiguous here
581 /// means that elements are laid out so that every element is the same
582 /// distance from its neighbors.
584 /// *[See also the `std::slice` module](crate::slice).*
586 /// Slices are a view into a block of memory represented as a pointer and a
591 /// let vec = vec![1, 2, 3];
592 /// let int_slice = &vec[..];
593 /// // coercing an array to a slice
594 /// let str_slice: &[&str] = &["one", "two", "three"];
597 /// Slices are either mutable or shared. The shared slice type is `&[T]`,
598 /// while the mutable slice type is `&mut [T]`, where `T` represents the element
599 /// type. For example, you can mutate the block of memory that a mutable slice
603 /// let mut x = [1, 2, 3];
604 /// let x = &mut x[..]; // Take a full slice of `x`.
606 /// assert_eq!(x, &[1, 7, 3]);
609 /// As slices store the length of the sequence they refer to, they have twice
610 /// the size of pointers to [`Sized`](marker/trait.Sized.html) types.
611 /// Also see the reference on
612 /// [dynamically sized types](../reference/dynamically-sized-types.html).
615 /// # use std::rc::Rc;
616 /// let pointer_size = std::mem::size_of::<&u8>();
617 /// assert_eq!(2 * pointer_size, std::mem::size_of::<&[u8]>());
618 /// assert_eq!(2 * pointer_size, std::mem::size_of::<*const [u8]>());
619 /// assert_eq!(2 * pointer_size, std::mem::size_of::<Box<[u8]>>());
620 /// assert_eq!(2 * pointer_size, std::mem::size_of::<Rc<[u8]>>());
622 #[stable(feature = "rust1", since = "1.0.0")]
625 #[doc(primitive = "str")]
629 /// *[See also the `std::str` module](crate::str).*
631 /// The `str` type, also called a 'string slice', is the most primitive string
632 /// type. It is usually seen in its borrowed form, `&str`. It is also the type
633 /// of string literals, `&'static str`.
635 /// String slices are always valid UTF-8.
639 /// String literals are string slices:
642 /// let hello = "Hello, world!";
644 /// // with an explicit type annotation
645 /// let hello: &'static str = "Hello, world!";
648 /// They are `'static` because they're stored directly in the final binary, and
649 /// so will be valid for the `'static` duration.
653 /// A `&str` is made up of two components: a pointer to some bytes, and a
654 /// length. You can look at these with the [`as_ptr`] and [`len`] methods:
660 /// let story = "Once upon a time...";
662 /// let ptr = story.as_ptr();
663 /// let len = story.len();
665 /// // story has nineteen bytes
666 /// assert_eq!(19, len);
668 /// // We can re-build a str out of ptr and len. This is all unsafe because
669 /// // we are responsible for making sure the two components are valid:
671 /// // First, we build a &[u8]...
672 /// let slice = slice::from_raw_parts(ptr, len);
674 /// // ... and then convert that slice into a string slice
675 /// str::from_utf8(slice)
678 /// assert_eq!(s, Ok(story));
681 /// [`as_ptr`]: str::as_ptr
682 /// [`len`]: str::len
684 /// Note: This example shows the internals of `&str`. `unsafe` should not be
685 /// used to get a string slice under normal circumstances. Use `as_str`
687 #[stable(feature = "rust1", since = "1.0.0")]
690 #[doc(primitive = "tuple")]
695 /// A finite heterogeneous sequence, `(T, U, ..)`.
697 /// Let's cover each of those in turn:
699 /// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple
703 /// ("hello", 5, 'c');
706 /// 'Length' is also sometimes called 'arity' here; each tuple of a different
707 /// length is a different, distinct type.
709 /// Tuples are *heterogeneous*. This means that each element of the tuple can
710 /// have a different type. In that tuple above, it has the type:
714 /// (&'static str, i32, char)
715 /// # = ("hello", 5, 'c');
718 /// Tuples are a *sequence*. This means that they can be accessed by position;
719 /// this is called 'tuple indexing', and it looks like this:
722 /// let tuple = ("hello", 5, 'c');
724 /// assert_eq!(tuple.0, "hello");
725 /// assert_eq!(tuple.1, 5);
726 /// assert_eq!(tuple.2, 'c');
729 /// The sequential nature of the tuple applies to its implementations of various
730 /// traits. For example, in `PartialOrd` and `Ord`, the elements are compared
731 /// sequentially until the first non-equal set is found.
733 /// For more about tuples, see [the book](../book/ch03-02-data-types.html#the-tuple-type).
735 /// # Trait implementations
737 /// If every type inside a tuple implements one of the following traits, then a
738 /// tuple itself also implements it.
750 /// [`Debug`]: fmt::Debug
751 /// [`Hash`]: hash::Hash
753 /// Due to a temporary restriction in Rust's type system, these traits are only
754 /// implemented on tuples of arity 12 or less. In the future, this may change.
761 /// let tuple = ("hello", 5, 'c');
763 /// assert_eq!(tuple.0, "hello");
766 /// Tuples are often used as a return type when you want to return more than
770 /// fn calculate_point() -> (i32, i32) {
771 /// // Don't do a calculation, that's not the point of the example
775 /// let point = calculate_point();
777 /// assert_eq!(point.0, 4);
778 /// assert_eq!(point.1, 5);
780 /// // Combining this with patterns can be nicer.
782 /// let (x, y) = calculate_point();
784 /// assert_eq!(x, 4);
785 /// assert_eq!(y, 5);
788 #[stable(feature = "rust1", since = "1.0.0")]
791 #[doc(primitive = "f32")]
792 /// A 32-bit floating point type (specifically, the "binary32" type defined in IEEE 754-2008).
794 /// This type can represent a wide range of decimal numbers, like `3.5`, `27`,
795 /// `-113.75`, `0.0078125`, `34359738368`, `0`, `-1`. So unlike integer types
796 /// (such as `i32`), floating point types can represent non-integer numbers,
799 /// However, being able to represent this wide range of numbers comes at the
800 /// cost of precision: floats can only represent some of the real numbers and
801 /// calculation with floats round to a nearby representable number. For example,
802 /// `5.0` and `1.0` can be exactly represented as `f32`, but `1.0 / 5.0` results
803 /// in `0.20000000298023223876953125` since `0.2` cannot be exactly represented
804 /// as `f32`. Note, however, that printing floats with `println` and friends will
805 /// often discard insignificant digits: `println!("{}", 1.0f32 / 5.0f32)` will
808 /// Additionally, `f32` can represent some special values:
810 /// - -0.0: IEEE 754 floating point numbers have a bit that indicates their sign, so -0.0 is a
811 /// possible value. For comparison `-0.0 == +0.0` is true but floating point operations can
812 /// carry the sign bit through arithmetic operations. This means `-1.0 * 0.0` produces -0.0 and
813 /// a negative number rounded to a value smaller than a float can represent also produces -0.0.
814 /// - [∞](#associatedconstant.INFINITY) and
815 /// [−∞](#associatedconstant.NEG_INFINITY): these result from calculations
816 /// like `1.0 / 0.0`.
817 /// - [NaN (not a number)](#associatedconstant.NAN): this value results from
818 /// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected
819 /// behavior: it is unequal to any float, including itself! It is also neither
820 /// smaller nor greater than any float, making it impossible to sort. Lastly,
821 /// it is considered infectious as almost all calculations where one of the
822 /// operands is NaN will also result in NaN.
824 /// For more information on floating point numbers, see [Wikipedia][wikipedia].
826 /// *[See also the `std::f32::consts` module](crate::f32::consts).*
828 /// [wikipedia]: https://en.wikipedia.org/wiki/Single-precision_floating-point_format
829 #[stable(feature = "rust1", since = "1.0.0")]
832 #[doc(primitive = "f64")]
833 /// A 64-bit floating point type (specifically, the "binary64" type defined in IEEE 754-2008).
835 /// This type is very similar to [`f32`], but has increased
836 /// precision by using twice as many bits. Please see [the documentation for
837 /// `f32`][`f32`] or [Wikipedia on double precision
838 /// values][wikipedia] for more information.
840 /// *[See also the `std::f64::consts` module](crate::f64::consts).*
842 /// [`f32`]: prim@f32
843 /// [wikipedia]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format
844 #[stable(feature = "rust1", since = "1.0.0")]
847 #[doc(primitive = "i8")]
849 /// The 8-bit signed integer type.
850 #[stable(feature = "rust1", since = "1.0.0")]
853 #[doc(primitive = "i16")]
855 /// The 16-bit signed integer type.
856 #[stable(feature = "rust1", since = "1.0.0")]
859 #[doc(primitive = "i32")]
861 /// The 32-bit signed integer type.
862 #[stable(feature = "rust1", since = "1.0.0")]
865 #[doc(primitive = "i64")]
867 /// The 64-bit signed integer type.
868 #[stable(feature = "rust1", since = "1.0.0")]
871 #[doc(primitive = "i128")]
873 /// The 128-bit signed integer type.
874 #[stable(feature = "i128", since = "1.26.0")]
877 #[doc(primitive = "u8")]
879 /// The 8-bit unsigned integer type.
880 #[stable(feature = "rust1", since = "1.0.0")]
883 #[doc(primitive = "u16")]
885 /// The 16-bit unsigned integer type.
886 #[stable(feature = "rust1", since = "1.0.0")]
889 #[doc(primitive = "u32")]
891 /// The 32-bit unsigned integer type.
892 #[stable(feature = "rust1", since = "1.0.0")]
895 #[doc(primitive = "u64")]
897 /// The 64-bit unsigned integer type.
898 #[stable(feature = "rust1", since = "1.0.0")]
901 #[doc(primitive = "u128")]
903 /// The 128-bit unsigned integer type.
904 #[stable(feature = "i128", since = "1.26.0")]
907 #[doc(primitive = "isize")]
909 /// The pointer-sized signed integer type.
911 /// The size of this primitive is how many bytes it takes to reference any
912 /// location in memory. For example, on a 32 bit target, this is 4 bytes
913 /// and on a 64 bit target, this is 8 bytes.
914 #[stable(feature = "rust1", since = "1.0.0")]
917 #[doc(primitive = "usize")]
919 /// The pointer-sized unsigned integer type.
921 /// The size of this primitive is how many bytes it takes to reference any
922 /// location in memory. For example, on a 32 bit target, this is 4 bytes
923 /// and on a 64 bit target, this is 8 bytes.
924 #[stable(feature = "rust1", since = "1.0.0")]
927 #[doc(primitive = "reference")]
929 #[doc(alias = "&mut")]
931 /// References, both shared and mutable.
933 /// A reference represents a borrow of some owned value. You can get one by using the `&` or `&mut`
934 /// operators on a value, or by using a `ref` or `ref mut` pattern.
936 /// For those familiar with pointers, a reference is just a pointer that is assumed to be
937 /// aligned, not null, and pointing to memory containing a valid value of `T` - for example,
938 /// `&bool` can only point to an allocation containing the integer values `1` (`true`) or `0`
939 /// (`false`), but creating a `&bool` that points to an allocation containing
940 /// the value `3` causes undefined behaviour.
941 /// In fact, `Option<&T>` has the same memory representation as a
942 /// nullable but aligned pointer, and can be passed across FFI boundaries as such.
944 /// In most cases, references can be used much like the original value. Field access, method
945 /// calling, and indexing work the same (save for mutability rules, of course). In addition, the
946 /// comparison operators transparently defer to the referent's implementation, allowing references
947 /// to be compared the same as owned values.
949 /// References have a lifetime attached to them, which represents the scope for which the borrow is
950 /// valid. A lifetime is said to "outlive" another one if its representative scope is as long or
951 /// longer than the other. The `'static` lifetime is the longest lifetime, which represents the
952 /// total life of the program. For example, string literals have a `'static` lifetime because the
953 /// text data is embedded into the binary of the program, rather than in an allocation that needs
954 /// to be dynamically managed.
956 /// `&mut T` references can be freely coerced into `&T` references with the same referent type, and
957 /// references with longer lifetimes can be freely coerced into references with shorter ones.
959 /// Reference equality by address, instead of comparing the values pointed to, is accomplished via
960 /// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while
961 /// [`PartialEq`] compares values.
967 /// let other_five = 5;
968 /// let five_ref = &five;
969 /// let same_five_ref = &five;
970 /// let other_five_ref = &other_five;
972 /// assert!(five_ref == same_five_ref);
973 /// assert!(five_ref == other_five_ref);
975 /// assert!(ptr::eq(five_ref, same_five_ref));
976 /// assert!(!ptr::eq(five_ref, other_five_ref));
979 /// For more information on how to use references, see [the book's section on "References and
980 /// Borrowing"][book-refs].
982 /// [book-refs]: ../book/ch04-02-references-and-borrowing.html
984 /// # Trait implementations
986 /// The following traits are implemented for all `&T`, regardless of the type of its referent:
989 /// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!)
994 /// [`Deref`]: ops::Deref
995 /// [`Borrow`]: borrow::Borrow
996 /// [`Pointer`]: fmt::Pointer
998 /// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating
999 /// multiple simultaneous mutable borrows), plus the following, regardless of the type of its
1005 /// [`DerefMut`]: ops::DerefMut
1006 /// [`BorrowMut`]: borrow::BorrowMut
1008 /// The following traits are implemented on `&T` references if the underlying `T` also implements
1011 /// * All the traits in [`std::fmt`] except [`Pointer`] and [`fmt::Write`]
1012 /// * [`PartialOrd`]
1017 /// * [`Fn`] \(in addition, `&T` references get [`FnMut`] and [`FnOnce`] if `T: Fn`)
1019 /// * [`ToSocketAddrs`]
1021 /// [`std::fmt`]: fmt
1022 /// ['Pointer`]: fmt::Pointer
1023 /// [`Hash`]: hash::Hash
1024 /// [`ToSocketAddrs`]: net::ToSocketAddrs
1026 /// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T`
1027 /// implements that trait:
1030 /// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`)
1031 /// * [`fmt::Write`]
1033 /// * [`DoubleEndedIterator`]
1034 /// * [`ExactSizeIterator`]
1035 /// * [`FusedIterator`]
1036 /// * [`TrustedLen`]
1037 /// * [`Send`] \(note that `&T` references only get `Send` if `T: Sync`)
1043 /// [`FusedIterator`]: iter::FusedIterator
1044 /// [`TrustedLen`]: iter::TrustedLen
1045 /// [`Seek`]: io::Seek
1046 /// [`BufRead`]: io::BufRead
1047 /// [`Read`]: io::Read
1049 /// Note that due to method call deref coercion, simply calling a trait method will act like they
1050 /// work on references as well as they do on owned values! The implementations described here are
1051 /// meant for generic contexts, where the final type `T` is a type parameter or otherwise not
1053 #[stable(feature = "rust1", since = "1.0.0")]
1056 #[doc(primitive = "fn")]
1058 /// Function pointers, like `fn(usize) -> bool`.
1060 /// *See also the traits [`Fn`], [`FnMut`], and [`FnOnce`].*
1063 /// [`FnMut`]: ops::FnMut
1064 /// [`FnOnce`]: ops::FnOnce
1066 /// Function pointers are pointers that point to *code*, not data. They can be called
1067 /// just like functions. Like references, function pointers are, among other things, assumed to
1068 /// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null
1069 /// pointers, make your type `Option<fn()>` with your required signature.
1073 /// Plain function pointers are obtained by casting either plain functions, or closures that don't
1074 /// capture an environment:
1077 /// fn add_one(x: usize) -> usize {
1081 /// let ptr: fn(usize) -> usize = add_one;
1082 /// assert_eq!(ptr(5), 6);
1084 /// let clos: fn(usize) -> usize = |x| x + 5;
1085 /// assert_eq!(clos(5), 10);
1088 /// In addition to varying based on their signature, function pointers come in two flavors: safe
1089 /// and unsafe. Plain `fn()` function pointers can only point to safe functions,
1090 /// while `unsafe fn()` function pointers can point to safe or unsafe functions.
1093 /// fn add_one(x: usize) -> usize {
1097 /// unsafe fn add_one_unsafely(x: usize) -> usize {
1101 /// let safe_ptr: fn(usize) -> usize = add_one;
1103 /// //ERROR: mismatched types: expected normal fn, found unsafe fn
1104 /// //let bad_ptr: fn(usize) -> usize = add_one_unsafely;
1106 /// let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely;
1107 /// let really_safe_ptr: unsafe fn(usize) -> usize = add_one;
1112 /// On top of that, function pointers can vary based on what ABI they use. This
1113 /// is achieved by adding the `extern` keyword before the type, followed by the
1114 /// ABI in question. The default ABI is "Rust", i.e., `fn()` is the exact same
1115 /// type as `extern "Rust" fn()`. A pointer to a function with C ABI would have
1116 /// type `extern "C" fn()`.
1118 /// `extern "ABI" { ... }` blocks declare functions with ABI "ABI". The default
1119 /// here is "C", i.e., functions declared in an `extern {...}` block have "C"
1122 /// For more information and a list of supported ABIs, see [the nomicon's
1123 /// section on foreign calling conventions][nomicon-abi].
1125 /// [nomicon-abi]: ../nomicon/ffi.html#foreign-calling-conventions
1127 /// ### Variadic functions
1129 /// Extern function declarations with the "C" or "cdecl" ABIs can also be *variadic*, allowing them
1130 /// to be called with a variable number of arguments. Normal Rust functions, even those with an
1131 /// `extern "ABI"`, cannot be variadic. For more information, see [the nomicon's section on
1132 /// variadic functions][nomicon-variadic].
1134 /// [nomicon-variadic]: ../nomicon/ffi.html#variadic-functions
1136 /// ### Creating function pointers
1138 /// When `bar` is the name of a function, then the expression `bar` is *not* a
1139 /// function pointer. Rather, it denotes a value of an unnameable type that
1140 /// uniquely identifies the function `bar`. The value is zero-sized because the
1141 /// type already identifies the function. This has the advantage that "calling"
1142 /// the value (it implements the `Fn*` traits) does not require dynamic
1145 /// This zero-sized type *coerces* to a regular function pointer. For example:
1150 /// fn bar(x: i32) {}
1152 /// let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar`
1153 /// assert_eq!(mem::size_of_val(¬_bar_ptr), 0);
1155 /// let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer
1156 /// assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::<usize>());
1158 /// let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar`
1161 /// The last line shows that `&bar` is not a function pointer either. Rather, it
1162 /// is a reference to the function-specific ZST. `&bar` is basically never what you
1163 /// want when `bar` is a function.
1167 /// Function pointers implement the following traits:
1172 /// * [`PartialOrd`]
1178 /// [`Hash`]: hash::Hash
1179 /// [`Pointer`]: fmt::Pointer
1181 /// Due to a temporary restriction in Rust's type system, these traits are only implemented on
1182 /// functions that take 12 arguments or less, with the `"Rust"` and `"C"` ABIs. In the future, this
1185 /// In addition, function pointers of *any* signature, ABI, or safety are [`Copy`], and all *safe*
1186 /// function pointers implement [`Fn`], [`FnMut`], and [`FnOnce`]. This works because these traits
1187 /// are specially known to the compiler.
1188 #[stable(feature = "rust1", since = "1.0.0")]