async_fn_traits
)AsyncFn::async_call
.async_fn_traits
)AsyncFn
, returning a future which may borrow from the called closure.async_fn_traits
)AsyncFnMut::async_call_mut
.async_fn_traits
)AsyncFnMut
, returning a future which may borrow from the called closure.async_fn_traits
)async_fn_traits
)AsyncFnOnce::async_call_once
.async_fn_traits
)AsyncFnOnce
, returning a future which may move out of the called closure.async_iterator
)async_iterator
)None
if the async iterator is exhausted. Read moreAllocates memory on the heap and then places x
into it.
This doesn’t actually allocate if T
is zero-sized.
let five = Box::new(5);
new_uninit
)Constructs a new box with uninitialized contents.
\n#![feature(new_uninit)]\n\nlet mut five = Box::<u32>::new_uninit();\n\nlet five = unsafe {\n // Deferred initialization:\n five.as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5)
new_uninit
)Constructs a new Box
with uninitialized contents, with the memory\nbeing filled with 0
bytes.
See MaybeUninit::zeroed
for examples of correct and incorrect usage\nof this method.
#![feature(new_uninit)]\n\nlet zero = Box::<u32>::new_zeroed();\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)
Constructs a new Pin<Box<T>>
. If T
does not implement Unpin
, then\nx
will be pinned in memory and unable to be moved.
Constructing and pinning of the Box
can also be done in two steps: Box::pin(x)
\ndoes the same as Box::into_pin(Box::new(x))
. Consider using\ninto_pin
if you already have a Box<T>
, or if you want to\nconstruct a (pinned) Box
in a different way than with Box::new
.
allocator_api
)Allocates memory on the heap then places x
into it,\nreturning an error if the allocation fails
This doesn’t actually allocate if T
is zero-sized.
#![feature(allocator_api)]\n\nlet five = Box::try_new(5)?;
allocator_api
)Constructs a new box with uninitialized contents on the heap,\nreturning an error if the allocation fails
\n#![feature(allocator_api, new_uninit)]\n\nlet mut five = Box::<u32>::try_new_uninit()?;\n\nlet five = unsafe {\n // Deferred initialization:\n five.as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5);
allocator_api
)Constructs a new Box
with uninitialized contents, with the memory\nbeing filled with 0
bytes on the heap
See MaybeUninit::zeroed
for examples of correct and incorrect usage\nof this method.
#![feature(allocator_api, new_uninit)]\n\nlet zero = Box::<u32>::try_new_zeroed()?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);
Constructs a box from a raw pointer.
\nAfter calling this function, the raw pointer is owned by the\nresulting Box
. Specifically, the Box
destructor will call\nthe destructor of T
and free the allocated memory. For this\nto be safe, the memory must have been allocated in accordance\nwith the memory layout used by Box
.
This function is unsafe because improper use may lead to\nmemory problems. For example, a double-free may occur if the\nfunction is called twice on the same raw pointer.
\nThe safety conditions are described in the memory layout section.
\nRecreate a Box
which was previously converted to a raw pointer\nusing Box::into_raw
:
let x = Box::new(5);\nlet ptr = Box::into_raw(x);\nlet x = unsafe { Box::from_raw(ptr) };
Manually create a Box
from scratch by using the global allocator:
use std::alloc::{alloc, Layout};\n\nunsafe {\n let ptr = alloc(Layout::new::<i32>()) as *mut i32;\n // In general .write is required to avoid attempting to destruct\n // the (uninitialized) previous contents of `ptr`, though for this\n // simple example `*ptr = 5` would have worked as well.\n ptr.write(5);\n let x = Box::from_raw(ptr);\n}
allocator_api
)Allocates memory in the given allocator then places x
into it.
This doesn’t actually allocate if T
is zero-sized.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet five = Box::new_in(5, System);
allocator_api
)Allocates memory in the given allocator then places x
into it,\nreturning an error if the allocation fails
This doesn’t actually allocate if T
is zero-sized.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet five = Box::try_new_in(5, System)?;
allocator_api
)Constructs a new box with uninitialized contents in the provided allocator.
\n#![feature(allocator_api, new_uninit)]\n\nuse std::alloc::System;\n\nlet mut five = Box::<u32, _>::new_uninit_in(System);\n\nlet five = unsafe {\n // Deferred initialization:\n five.as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5)
allocator_api
)Constructs a new box with uninitialized contents in the provided allocator,\nreturning an error if the allocation fails
\n#![feature(allocator_api, new_uninit)]\n\nuse std::alloc::System;\n\nlet mut five = Box::<u32, _>::try_new_uninit_in(System)?;\n\nlet five = unsafe {\n // Deferred initialization:\n five.as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5);
allocator_api
)Constructs a new Box
with uninitialized contents, with the memory\nbeing filled with 0
bytes in the provided allocator.
See MaybeUninit::zeroed
for examples of correct and incorrect usage\nof this method.
#![feature(allocator_api, new_uninit)]\n\nuse std::alloc::System;\n\nlet zero = Box::<u32, _>::new_zeroed_in(System);\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)
allocator_api
)Constructs a new Box
with uninitialized contents, with the memory\nbeing filled with 0
bytes in the provided allocator,\nreturning an error if the allocation fails,
See MaybeUninit::zeroed
for examples of correct and incorrect usage\nof this method.
#![feature(allocator_api, new_uninit)]\n\nuse std::alloc::System;\n\nlet zero = Box::<u32, _>::try_new_zeroed_in(System)?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);
allocator_api
)Constructs a new Pin<Box<T, A>>
. If T
does not implement Unpin
, then\nx
will be pinned in memory and unable to be moved.
Constructing and pinning of the Box
can also be done in two steps: Box::pin_in(x, alloc)
\ndoes the same as Box::into_pin(Box::new_in(x, alloc))
. Consider using\ninto_pin
if you already have a Box<T, A>
, or if you want to\nconstruct a (pinned) Box
in a different way than with Box::new_in
.
box_into_boxed_slice
)Converts a Box<T>
into a Box<[T]>
This conversion does not allocate on the heap and happens in place.
\nbox_into_inner
)Consumes the Box
, returning the wrapped value.
#![feature(box_into_inner)]\n\nlet c = Box::new(5);\n\nassert_eq!(Box::into_inner(c), 5);
allocator_api
)Constructs a box from a raw pointer in the given allocator.
\nAfter calling this function, the raw pointer is owned by the\nresulting Box
. Specifically, the Box
destructor will call\nthe destructor of T
and free the allocated memory. For this\nto be safe, the memory must have been allocated in accordance\nwith the memory layout used by Box
.
This function is unsafe because improper use may lead to\nmemory problems. For example, a double-free may occur if the\nfunction is called twice on the same raw pointer.
\nRecreate a Box
which was previously converted to a raw pointer\nusing Box::into_raw_with_allocator
:
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet x = Box::new_in(5, System);\nlet (ptr, alloc) = Box::into_raw_with_allocator(x);\nlet x = unsafe { Box::from_raw_in(ptr, alloc) };
Manually create a Box
from scratch by using the system allocator:
#![feature(allocator_api, slice_ptr_get)]\n\nuse std::alloc::{Allocator, Layout, System};\n\nunsafe {\n let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;\n // In general .write is required to avoid attempting to destruct\n // the (uninitialized) previous contents of `ptr`, though for this\n // simple example `*ptr = 5` would have worked as well.\n ptr.write(5);\n let x = Box::from_raw_in(ptr, System);\n}
Consumes the Box
, returning a wrapped raw pointer.
The pointer will be properly aligned and non-null.
\nAfter calling this function, the caller is responsible for the\nmemory previously managed by the Box
. In particular, the\ncaller should properly destroy T
and release the memory, taking\ninto account the memory layout used by Box
. The easiest way to\ndo this is to convert the raw pointer back into a Box
with the\nBox::from_raw
function, allowing the Box
destructor to perform\nthe cleanup.
Note: this is an associated function, which means that you have\nto call it as Box::into_raw(b)
instead of b.into_raw()
. This\nis so that there is no conflict with a method on the inner type.
Converting the raw pointer back into a Box
with Box::from_raw
\nfor automatic cleanup:
let x = Box::new(String::from(\"Hello\"));\nlet ptr = Box::into_raw(x);\nlet x = unsafe { Box::from_raw(ptr) };
Manual cleanup by explicitly running the destructor and deallocating\nthe memory:
\n\nuse std::alloc::{dealloc, Layout};\nuse std::ptr;\n\nlet x = Box::new(String::from(\"Hello\"));\nlet ptr = Box::into_raw(x);\nunsafe {\n ptr::drop_in_place(ptr);\n dealloc(ptr as *mut u8, Layout::new::<String>());\n}
Note: This is equivalent to the following:
\n\nlet x = Box::new(String::from(\"Hello\"));\nlet ptr = Box::into_raw(x);\nunsafe {\n drop(Box::from_raw(ptr));\n}
allocator_api
)Consumes the Box
, returning a wrapped raw pointer and the allocator.
The pointer will be properly aligned and non-null.
\nAfter calling this function, the caller is responsible for the\nmemory previously managed by the Box
. In particular, the\ncaller should properly destroy T
and release the memory, taking\ninto account the memory layout used by Box
. The easiest way to\ndo this is to convert the raw pointer back into a Box
with the\nBox::from_raw_in
function, allowing the Box
destructor to perform\nthe cleanup.
Note: this is an associated function, which means that you have\nto call it as Box::into_raw_with_allocator(b)
instead of b.into_raw_with_allocator()
. This\nis so that there is no conflict with a method on the inner type.
Converting the raw pointer back into a Box
with Box::from_raw_in
\nfor automatic cleanup:
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet x = Box::new_in(String::from(\"Hello\"), System);\nlet (ptr, alloc) = Box::into_raw_with_allocator(x);\nlet x = unsafe { Box::from_raw_in(ptr, alloc) };
Manual cleanup by explicitly running the destructor and deallocating\nthe memory:
\n\n#![feature(allocator_api)]\n\nuse std::alloc::{Allocator, Layout, System};\nuse std::ptr::{self, NonNull};\n\nlet x = Box::new_in(String::from(\"Hello\"), System);\nlet (ptr, alloc) = Box::into_raw_with_allocator(x);\nunsafe {\n ptr::drop_in_place(ptr);\n let non_null = NonNull::new_unchecked(ptr);\n alloc.deallocate(non_null.cast(), Layout::new::<String>());\n}
allocator_api
)Returns a reference to the underlying allocator.
\nNote: this is an associated function, which means that you have\nto call it as Box::allocator(&b)
instead of b.allocator()
. This\nis so that there is no conflict with a method on the inner type.
Consumes and leaks the Box
, returning a mutable reference,\n&'a mut T
. Note that the type T
must outlive the chosen lifetime\n'a
. If the type has only static references, or none at all, then this\nmay be chosen to be 'static
.
This function is mainly useful for data that lives for the remainder of\nthe program’s life. Dropping the returned reference will cause a memory\nleak. If this is not acceptable, the reference should first be wrapped\nwith the Box::from_raw
function producing a Box
. This Box
can\nthen be dropped which will properly destroy T
and release the\nallocated memory.
Note: this is an associated function, which means that you have\nto call it as Box::leak(b)
instead of b.leak()
. This\nis so that there is no conflict with a method on the inner type.
Simple usage:
\n\nlet x = Box::new(41);\nlet static_ref: &'static mut usize = Box::leak(x);\n*static_ref += 1;\nassert_eq!(*static_ref, 42);
Unsized data:
\n\nlet x = vec![1, 2, 3].into_boxed_slice();\nlet static_ref = Box::leak(x);\nstatic_ref[0] = 4;\nassert_eq!(*static_ref, [4, 2, 3]);
Converts a Box<T>
into a Pin<Box<T>>
. If T
does not implement Unpin
, then\n*boxed
will be pinned in memory and unable to be moved.
This conversion does not allocate on the heap and happens in place.
\nThis is also available via From
.
Constructing and pinning a Box
with Box::into_pin(Box::new(x))
\ncan also be written more concisely using Box::pin(x)
.\nThis into_pin
method is useful if you already have a Box<T>
, or you are\nconstructing a (pinned) Box
in a different way than with Box::new
.
It’s not recommended that crates add an impl like From<Box<T>> for Pin<T>
,\nas it’ll introduce an ambiguity when calling Pin::from
.\nA demonstration of such a poor impl is shown below.
struct Foo; // A type defined in this crate.\nimpl From<Box<()>> for Pin<Foo> {\n fn from(_: Box<()>) -> Pin<Foo> {\n Pin::new(Foo)\n }\n}\n\nlet foo = Box::new(());\nlet bar = Pin::from(foo);
amt
bytes have been consumed from the buffer,\nso they should no longer be returned in calls to read
. Read more0xA
byte) is reached, and append\nthem to the provided String
buffer. Read morebuf_read_has_data_left
)Read
has any data left to be read. Read morebufread_skip_until
)byte
or EOF is reached. Read moreReturns a new box with a clone()
of this box’s contents.
let x = Box::new(5);\nlet y = x.clone();\n\n// The value is the same\nassert_eq!(x, y);\n\n// But they are unique objects\nassert_ne!(&*x as *const i32, &*y as *const i32);
Copies source
’s contents into self
without creating a new allocation.
let x = Box::new(5);\nlet mut y = Box::new(10);\nlet yp: *const i32 = &*y;\n\ny.clone_from(&x);\n\n// The value is the same\nassert_eq!(x, y);\n\n// And no allocation occurred\nassert_eq!(yp, &*y);
coroutine_trait
)n
th element from the end of the iterator. Read moreiter_advance_by
)n
elements. Read moreIterator::try_fold()
: it takes\nelements starting from the back of the iterator. Read moreu128
into this hasher.usize
into this hasher.i128
into this hasher.isize
into this hasher.hasher_prefixfree_extras
)n
th element of the iterator. Read moreiter_next_chunk
)N
values. Read moreiter_advance_by
)n
elements. Read moreiter_intersperse
)separator
\nbetween adjacent items of the original iterator. Read moren
elements. Read moren
elements, or fewer\nif the underlying iterator ends sooner. Read moreiter_map_windows
)f
for each contiguous window of size N
over\nself
and returns an iterator over the outputs of f
. Like slice::windows()
,\nthe windows during mapping overlap as well. Read moreiter_collect_into
)iter_is_partitioned
)true
precede all those that return false
. Read moreiterator_try_reduce
)try_find
)iter_array_chunks
)N
elements of the iterator at a time. Read moreiter_order_by
)Iterator
with those\nof another with respect to the specified comparison function. Read morePartialOrd
elements of\nthis Iterator
with those of another. The comparison works like short-circuit\nevaluation, returning a result without comparing the remaining elements.\nAs soon as an order can be determined, the evaluation stops and a result is returned. Read moreiter_order_by
)Iterator
with those\nof another with respect to the specified comparison function. Read moreiter_order_by
)Iterator
are lexicographically\nless than those of another. Read moreIterator
are lexicographically\nless or equal to those of another. Read moreIterator
are lexicographically\ngreater than those of another. Read moreIterator
are lexicographically\ngreater than or equal to those of another. Read moreis_sorted
)is_sorted
)self
and other
) and is used by the <=
\noperator. Read moreread_buf
)read
, except that it reads into a slice of buffers. Read morecan_vector
)buf
. Read morebuf
. Read morebuf
. Read moreread_buf
)cursor
. Read moreRead
. Read morecan_vector
)