Skip to content

Commit

Permalink
Clarify behavior of slice prefix/suffix operations in case of equality
Browse files Browse the repository at this point in the history
Operations such as starts_with, ends_with, strip_prefix and strip_suffix
can be either strict (do not consider a slice to be a prefix/suffix of
itself) or not. In Rust's case, they are not strict. Add a few phrases to
the documentation to clarify this.
  • Loading branch information
RavuAlHemio committed Feb 26, 2024
1 parent ee933f6 commit c9a4a4a
Showing 1 changed file with 10 additions and 4 deletions.
14 changes: 10 additions & 4 deletions library/core/src/slice/mod.rs
Expand Up @@ -2519,14 +2519,15 @@ impl<T> [T] {
cmp::SliceContains::slice_contains(x, self)
}

/// Returns `true` if `needle` is a prefix of the slice.
/// Returns `true` if `needle` is a prefix of the slice or equal to the slice.
///
/// # Examples
///
/// ```
/// let v = [10, 40, 30];
/// assert!(v.starts_with(&[10]));
/// assert!(v.starts_with(&[10, 40]));
/// assert!(v.starts_with(&v));
/// assert!(!v.starts_with(&[50]));
/// assert!(!v.starts_with(&[10, 50]));
/// ```
Expand All @@ -2549,14 +2550,15 @@ impl<T> [T] {
self.len() >= n && needle == &self[..n]
}

/// Returns `true` if `needle` is a suffix of the slice.
/// Returns `true` if `needle` is a suffix of the slice or equal to the slice.
///
/// # Examples
///
/// ```
/// let v = [10, 40, 30];
/// assert!(v.ends_with(&[30]));
/// assert!(v.ends_with(&[40, 30]));
/// assert!(v.ends_with(&v));
/// assert!(!v.ends_with(&[50]));
/// assert!(!v.ends_with(&[50, 30]));
/// ```
Expand All @@ -2582,7 +2584,8 @@ impl<T> [T] {
/// Returns a subslice with the prefix removed.
///
/// If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`.
/// If `prefix` is empty, simply returns the original slice.
/// If `prefix` is empty, simply returns the original slice. If `prefix` is equal to the
/// original slice, returns an empty slice.
///
/// If the slice does not start with `prefix`, returns `None`.
///
Expand All @@ -2592,6 +2595,7 @@ impl<T> [T] {
/// let v = &[10, 40, 30];
/// assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
/// assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
/// assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
/// assert_eq!(v.strip_prefix(&[50]), None);
/// assert_eq!(v.strip_prefix(&[10, 50]), None);
///
Expand Down Expand Up @@ -2620,7 +2624,8 @@ impl<T> [T] {
/// Returns a subslice with the suffix removed.
///
/// If the slice ends with `suffix`, returns the subslice before the suffix, wrapped in `Some`.
/// If `suffix` is empty, simply returns the original slice.
/// If `suffix` is empty, simply returns the original slice. If `suffix` is equal to the
/// original slice, returns an empty slice.
///
/// If the slice does not end with `suffix`, returns `None`.
///
Expand All @@ -2630,6 +2635,7 @@ impl<T> [T] {
/// let v = &[10, 40, 30];
/// assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
/// assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
/// assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
/// assert_eq!(v.strip_suffix(&[50]), None);
/// assert_eq!(v.strip_suffix(&[50, 30]), None);
/// ```
Expand Down

0 comments on commit c9a4a4a

Please sign in to comment.