Merge crate collections into alloc

[murarth]

This is a necessary step in order to merge #42565

[rust-highfive]

r? @sfackler

(rust_highfive has picked a reviewer for you, use r? to override)

[murarth]

r? @alexcrichton

[alexcrichton]

Looks great to me, thanks @murarth!

Just to make sure it's written here, the rationale for this is:

• In Implement From<&[T]> and others for Arc/Rc (RFC 1845) #42565 the Rc and Vec types need to know about each other, specifically we want to write down From<Vec<T>> for Rc<T>
• Historically there were plans to keep collections separate from alloc, but that never panned out.
• Nowadays both alloc and collections add one additional assumption over libcore, dynamic memory allocation. There's not much reason any more to keep them separate as given one you can always have all of the other.

[alexcrichton]

Oh and let's just wait for a green travis build on this, then I'll r+

[alexcrichton]

cc @rust-lang/libs

[bors]

☔ The latest upstream changes (presumably #42644) made this pull request unmergeable. Please resolve the merge conflicts.

[alexcrichton]

Looks like the linkchecker also turned up errors :(

[mattico]

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](../std/index.html),
 //! 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`](boxed/index.html) 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`](rc/index.html) 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`](arc/index.html) 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`](heap/index.html) module defines the low-level interface to the
 //! default global allocator. It is not compatible with the libc allocator API.
+//!
+//! ## Collections
+//!
+//! ### Vectors
+//!
+//! The [`vec`](FIXME) module defines a "vector", a contiguous growable array
+//! type with heap-allocated contents.
+//!
+//! ### Deques
+//!
+//! The [`vec_deque`](FIXME) module defines a double-ended queue implemented
+//! with a growable ring buffer.
+//!
+//! ### Strings
+//!
+//! The [`string`](FIXME) module defines a growable, heap-allocated string
+//! with a known length. Rust strings are always encoded in valid UTF-8.
+//!
+//! The [`str`](FIXME) module defines operations on "string slices",
+//! borrowed references to UTF-8 string data.
+//!
+//! ### Linked Lists
+//!
+//! The [`linked_list`](FIXME) 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`](FIXME) module defines a A priority queue implemented
+//! with a binary heap.
+//!
+//! ### Ranges
+//!
+//! The [`range`](FIXME) module defines range types and traits. These are
+//! usually created with the `..` and `..=` operators.
+//!
+//! ### Slices
+//!
+//! The [`slice`](FIXME) module defines operations on "slices", borrowed
+//! views into contiguous sequences.
+//!
+//! ### B-Trees
+//!
+//! The [`btree`](FIXME) 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"]

[murarth]

I think I've fixed the linkchecker issues now. It seems I can't test it locally without building all the way to stage2, so I hope this does it.

@mattico: It could use a mention of collections types. I don't want to try to compete with the wonderful documentation in std::collections, so I just put a brief note and a link over there.

[alexcrichton]

@bors: r+

[bors]

📌 Commit eadda76 has been approved by alexcrichton

[joshlf]

Sorry to be a wet blanked - and maybe there's something I'm missing here - but wouldn't it be better if collections were a separate no_std crate with each type taking an Allocator parameter so that they could be used in kernels/embedded/etc? Then maybe there could be another crate (maybe alloc itself) that re-exports all of the types with the standard allocator as the default value for the Allocator type parameter?

[alexcrichton]

@joshlf perhaps one day, but the crates as-is today are nowhere near architected for that. These are all unstable, we can change them at any time.

[joshlf]

@alexcrichton Fair enough; as long as we leave open the possibility :)

[mattico]

@joshlf take a look at #42313

(sorry for the noise)

[joshlf]

@mattico Yep, I've been making plenty of noise over there too :)

[bors]

⌛ Testing commit eadda76 with merge 258ae6d...

[Ericson2314]

Woah. Really scared about the end of fine-grain crates behind the facade.

[Ericson2314]

One thing I talked about in the local Allocator RFC is using an empty associated error type for infallibile allocation, and then immediately and easily using that for converting collections.

[Ericson2314]

For the stated problem, I think it makes more sense to simply move Vec to alloc. It is argubaly the most more fundamental data structure, and I'll guess we could get rid of this RawVec too.

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing 258ae6d to master...

[whitequark]

I'm somewhat overloaded right now, so that will have to be someone else...

[murarth]

I wouldn't mind handling that. ~~~Should be a simple copy/paste of the re-exports in std.~~~ Err, it would actually need to mimic the former collections crate, but it should be relatively straightforward, anyway.

@alexcrichton: One question, though: Should the re-exports of the new collections be marked deprecated? Does the compiler even recognize and issue warnings for stability attributes on re-exports?

[alexcrichton]

We can't handle the reexports themselves being deprecated, but I think it's fine to deprecate the collections crate as a whole.