Merge crate collections into alloc by murarth · Pull Request #42648 · rust-lang/rust (original) (raw)

Nit: Could update liballoc/lib.rs to mention that collections stuff is included in there as well.

Here's my late-night first-draft suggestion.

diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs index c70d823..d175fa4 100644 --- a/src/liballoc/lib.rs +++ b/src/liballoc/lib.rs @@ -10,17 +10,20 @@

//! # The Rust core allocation library //! -//! This is the lowest level library through which allocation in Rust can be -//! performed. +//! This is a low-level library which builds on libcore to add data structures +//! which require dynamic memory allocation. //! //! This library, like libcore, is not intended for general usage, but rather as //! a building block of other libraries. The types and interfaces in this //! library are reexported through the standard library, //! and should not be used through this library. //! -//! Currently, there are four major definitions in this library. +//! The components of this library can be divided into two major groups: smart +//! pointers, and collections (from the old libcollections). //! -//! ## Boxed values +//! ## Smart Pointers and Memory Allocation +//! +//! ### Boxed values //! //! The Box type is a smart pointer type. There can //! only be one owner of a Box, and the owner can decide to mutate the @@ -30,7 +33,7 @@ //! is the same as that of a pointer. Tree-like data structures are often built //! with boxes because each node often has only one owner, the parent. //! -//! ## Reference counted pointers +//! ### Reference counted pointers //! //! The Rc type is a non-threadsafe reference-counted pointer //! type intended for sharing memory within a thread. An Rc pointer wraps a @@ -40,7 +43,7 @@ //! constraining for an application, and is often paired with the Cell or //! RefCell types in order to allow mutation. //! -//! ## Atomically reference counted pointers +//! ### Atomically reference counted pointers //! //! The Arc type is the threadsafe equivalent of the Rc //! type. It provides all the same functionality of Rc, except it requires @@ -51,10 +54,57 @@ //! paired with synchronization primitives such as mutexes to allow mutation of //! shared resources. //! -//! ## Heap interfaces +//! ### Heap interfaces //! //! The heap module defines the low-level interface to the //! default global allocator. It is not compatible with the libc allocator API. +//! +//! ## Collections +//! +//! ### Vectors +//! +//! The vec module defines a "vector", a contiguous growable array +//! type with heap-allocated contents. +//! +//! ### Deques +//! +//! The vec_deque module defines a double-ended queue implemented +//! with a growable ring buffer. +//! +//! ### Strings +//! +//! The string module defines a growable, heap-allocated string +//! with a known length. Rust strings are always encoded in valid UTF-8. +//! +//! The str module defines operations on "string slices", +//! borrowed references to UTF-8 string data. +//! +//! ### Linked Lists +//! +//! The linked_list module defines a doubly-linked list, with +//! constant-time inserts at both ends. In most cases, [Vec] or +//! [VecDeque] offer better performance. +//! +//! ### Binary Heaps +//! +//! The binary_heap module defines a A priority queue implemented +//! with a binary heap. +//! +//! ### Ranges +//! +//! The range module defines range types and traits. These are +//! usually created with the .. and ..= operators. +//! +//! ### Slices +//! +//! The slice module defines operations on "slices", borrowed +//! views into contiguous sequences. +//! +//! ### B-Trees +//! +//! The btree module defines various types implemented using +//! binary trees. This module includes implementations of maps, sets, and +//! search algorithms on B-Trees.

#![crate_name = "alloc"] #![crate_type = "rlib"]