Implemented the Needle API (RFC 2500).

Author: kennytm

src/libcore/lib.rs

@@ -211,6 +211,7 @@ pub mod fmt;
 pub mod time;
 
 pub mod unicode;
+pub mod needle;
 
 /* Async */
 pub mod future;

src/libcore/needle/ext.rs

@@ -0,0 +1,36 @@
+#![unstable(feature = "needle", issue = "56345")]
+
+//! The Needle API, support generalized searching on strings, arrays and more.
+//!
+//! This module provides traits to facilitate searching [`Needle`] in a [`Haystack`].
+//!
+//! Haystacks
+//! =========
+//!
+//! A *haystack* refers to any linear structure which can be split or sliced
+//! into smaller, non-overlapping parts. Examples are strings and vectors.
+//!
+//! ```rust
+//! let haystack: &str = "hello";       // a string slice (`&str`) is a haystack.
+//! let (a, b) = haystack.split_at(4);  // it can be split into two strings.
+//! let c = &a[1..3];                   // it can be sliced.
+//! ```
+//!
+//! The minimal haystack which cannot be further sliced is called a *codeword*.
+//! For instance, the codeword of a string would be a UTF-8 sequence. A haystack
+//! can therefore be viewed as a consecutive list of codewords.
+//!
+//! The boundary between codewords can be addressed using an *index*. The
+//! numbers 1, 3 and 4 in the snippet above are sample indices of a string. An
+//! index is usually a `usize`.
+//!
+//! An arbitrary number may point outside of a haystack, or in the interior of a
+//! codeword. These indices are invalid. A *valid index* of a certain haystack
+//! would only point to the boundaries.
+
+mod haystack;
+mod needle;
+pub mod ext;
+
+pub use self::haystack::*;
+pub use self::needle::*;

src/libcore/needle/haystack.rs

@@ -274,6 +274,7 @@
 #![feature(link_args)]
 #![feature(linkage)]
 #![feature(maybe_uninit)]
+#![feature(needle)]
 #![feature(needs_panic_runtime)]
 #![feature(never_type)]
 #![feature(nll)]
@@ -437,6 +438,8 @@ pub use core::char;
 pub use core::u128;
 #[stable(feature = "core_hint", since = "1.27.0")]
 pub use core::hint;
+#[unstable(feature = "needle", issue = "56345")]
+pub use core::needle;
 
 pub mod f32;
 pub mod f64;