mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-23 23:34:48 +00:00
Rollup merge of #71334 - ehuss:pattern-docs, r=kennytm
Update pattern docs. A few changes to help clarify string pattern usage: * Add some examples and stability information in the `pattern` module. * Fixes the links at https://doc.rust-lang.org/std/str/pattern/ because intra-doc-links don't work with re-exported modules (#65983 I think?). * Consistently use the same phrasing for `str` methods taking a pattern. * Also mention that array of `char` is also accepted. When `Pattern` is stabilized, the phrasing in the `str` methods can be updated to be more general to reflect the exact behavior. I'm reluctant to do this now because the stability story for `Pattern` is uncertain. It may perhaps look something like: > The pattern can be any type that implements the [`Pattern`] trait. Notable examples are `&str`, [`char`], arrays of [`char`], or functions or closures that determines if a character matches. Additional libraries might provide more complex patterns like regular expressions. This is complicated because methods like `trim_matches` have bounds, which for example don't support `str`, so those methods may need more elaboration.
This commit is contained in:
Dylan DPC
GitHub
commit
b921587c91
@ -3010,6 +3010,12 @@ impl str {
|
||||
///
|
||||
/// Returns `false` if it does not.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Basic usage:
|
||||
@ -3031,6 +3037,12 @@ impl str {
|
||||
///
|
||||
/// Returns `false` if it does not.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Basic usage:
|
||||
@ -3051,6 +3063,12 @@ impl str {
|
||||
///
|
||||
/// Returns `false` if it does not.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Basic usage:
|
||||
@ -3074,10 +3092,12 @@ impl str {
|
||||
///
|
||||
/// Returns [`None`] if the pattern doesn't match.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`None`]: option/enum.Option.html#variant.None
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -3121,10 +3141,12 @@ impl str {
|
||||
///
|
||||
/// Returns [`None`] if the pattern doesn't match.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`None`]: option/enum.Option.html#variant.None
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -3166,8 +3188,11 @@ impl str {
|
||||
/// An iterator over substrings of this string slice, separated by
|
||||
/// characters matched by a pattern.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3285,6 +3310,12 @@ impl str {
|
||||
/// `split` in that `split_inclusive` leaves the matched part as the
|
||||
/// terminator of the substring.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -3319,8 +3350,11 @@ impl str {
|
||||
/// An iterator over substrings of the given string slice, separated by
|
||||
/// characters matched by a pattern and yielded in reverse order.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3370,8 +3404,11 @@ impl str {
|
||||
/// An iterator over substrings of the given string slice, separated by
|
||||
/// characters matched by a pattern.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// Equivalent to [`split`], except that the trailing substring
|
||||
/// is skipped if empty.
|
||||
@ -3414,10 +3451,11 @@ impl str {
|
||||
/// An iterator over substrings of `self`, separated by characters
|
||||
/// matched by a pattern and yielded in reverse order.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// Additional libraries might provide more complex patterns like
|
||||
/// regular expressions.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// Equivalent to [`split`], except that the trailing substring is
|
||||
/// skipped if empty.
|
||||
@ -3462,8 +3500,11 @@ impl str {
|
||||
/// If `n` substrings are returned, the last substring (the `n`th substring)
|
||||
/// will contain the remainder of the string.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3512,8 +3553,11 @@ impl str {
|
||||
/// If `n` substrings are returned, the last substring (the `n`th substring)
|
||||
/// will contain the remainder of the string.
|
||||
///
|
||||
/// The pattern can be any type that implements the Pattern trait. Notable
|
||||
/// examples are `&str`, [`char`], and closures that determines the split.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3557,8 +3601,11 @@ impl str {
|
||||
/// An iterator over the disjoint matches of a pattern within the given string
|
||||
/// slice.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3593,8 +3640,11 @@ impl str {
|
||||
/// An iterator over the disjoint matches of a pattern within this string slice,
|
||||
/// yielded in reverse order.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3634,8 +3684,11 @@ impl str {
|
||||
/// For matches of `pat` within `self` that overlap, only the indices
|
||||
/// corresponding to the first match are returned.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines
|
||||
/// if a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3676,8 +3729,11 @@ impl str {
|
||||
/// For matches of `pat` within `self` that overlap, only the indices
|
||||
/// corresponding to the last match are returned.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if a
|
||||
/// character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Iterator behavior
|
||||
///
|
||||
@ -3894,8 +3950,11 @@ impl str {
|
||||
/// Returns a string slice with all prefixes and suffixes that match a
|
||||
/// pattern repeatedly removed.
|
||||
///
|
||||
/// The pattern can be a [`char`] or a closure that determines if a
|
||||
/// character matches.
|
||||
/// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
|
||||
/// or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -3939,8 +3998,11 @@ impl str {
|
||||
/// Returns a string slice with all prefixes that match a pattern
|
||||
/// repeatedly removed.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Text directionality
|
||||
///
|
||||
@ -3981,6 +4043,12 @@ impl str {
|
||||
///
|
||||
/// If the string does not start with `prefix`, `None` is returned.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -4005,6 +4073,12 @@ impl str {
|
||||
///
|
||||
/// If the string does not end with `suffix`, `None` is returned.
|
||||
///
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -4027,8 +4101,11 @@ impl str {
|
||||
/// Returns a string slice with all suffixes that match a pattern
|
||||
/// repeatedly removed.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that
|
||||
/// determines if a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Text directionality
|
||||
///
|
||||
@ -4073,10 +4150,11 @@ impl str {
|
||||
/// Returns a string slice with all prefixes that match a pattern
|
||||
/// repeatedly removed.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that determines if
|
||||
/// a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Text directionality
|
||||
///
|
||||
@ -4109,10 +4187,11 @@ impl str {
|
||||
/// Returns a string slice with all suffixes that match a pattern
|
||||
/// repeatedly removed.
|
||||
///
|
||||
/// The pattern can be a `&str`, [`char`], or a closure that
|
||||
/// determines if a character matches.
|
||||
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
|
||||
/// function or closure that determines if a character matches.
|
||||
///
|
||||
/// [`char`]: primitive.char.html
|
||||
/// [pattern]: str/pattern/index.html
|
||||
///
|
||||
/// # Text directionality
|
||||
///
|
||||
|
||||
@ -1,7 +1,41 @@
|
||||
//! The string Pattern API.
|
||||
//!
|
||||
//! The Pattern API provides a generic mechanism for using different pattern
|
||||
//! types when searching through a string.
|
||||
//!
|
||||
//! For more details, see the traits [`Pattern`], [`Searcher`],
|
||||
//! [`ReverseSearcher`], and [`DoubleEndedSearcher`].
|
||||
//!
|
||||
//! Although this API is unstable, it is exposed via stable APIs on the
|
||||
//! [`str`] type.
|
||||
//!
|
||||
//! # Examples
|
||||
//!
|
||||
//! [`Pattern`] is [implemented][pattern-impls] in the stable API for
|
||||
//! [`&str`], [`char`], slices of [`char`], and functions and closures
|
||||
//! implementing `FnMut(char) -> bool`.
|
||||
//!
|
||||
//! ```
|
||||
//! let s = "Can you find a needle in a haystack?";
|
||||
//!
|
||||
//! // &str pattern
|
||||
//! assert_eq!(s.find("you"), Some(4));
|
||||
//! // char pattern
|
||||
//! assert_eq!(s.find('n'), Some(2));
|
||||
//! // slice of chars pattern
|
||||
//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u'][..]), Some(1));
|
||||
//! // closure pattern
|
||||
//! assert_eq!(s.find(|c: char| c.is_ascii_punctuation()), Some(35));
|
||||
//! ```
|
||||
//!
|
||||
//! [`&str`]: ../../../std/primitive.str.html
|
||||
//! [`char`]: ../../../std/primitive.char.html
|
||||
//! [`str`]: ../../../std/primitive.str.html
|
||||
//! [`DoubleEndedSearcher`]: trait.DoubleEndedSearcher.html
|
||||
//! [`Pattern`]: trait.Pattern.html
|
||||
//! [`ReverseSearcher`]: trait.ReverseSearcher.html
|
||||
//! [`Searcher`]: trait.Searcher.html
|
||||
//! [pattern-impls]: trait.Pattern.html#implementors
|
||||
|
||||
#![unstable(
|
||||
feature = "pattern",
|
||||
@ -702,7 +736,7 @@ unsafe impl<'a, 'b> ReverseSearcher<'a> for CharSliceSearcher<'a, 'b> {
|
||||
|
||||
impl<'a, 'b> DoubleEndedSearcher<'a> for CharSliceSearcher<'a, 'b> {}
|
||||
|
||||
/// Searches for chars that are equal to any of the chars in the array.
|
||||
/// Searches for chars that are equal to any of the chars in the slice.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
||||
Loading…
Reference in New Issue
Block a user