Trait SliceExt

pub trait SliceExt {
    type Elem;

    // Required methods
    fn contains_slice(&self, other: &Self) -> bool;
    fn is_slice(&self, other: &Self) -> bool;
    fn offset_of_slice(&self, other: &Self) -> usize;
    fn get_offset_of_slice(&self, other: &Self) -> Option<usize>;
    fn index_of(&self, other: *const Self::Elem) -> usize;
    fn get_index_of(&self, other: *const Self::Elem) -> Option<usize>;
    fn slice_lossy<SB>(&self, range: Range<usize>, bias: SB) -> &Self
       where SB: Into<SliceBias>;
    fn slice_lossy_mut<SB>(
        &mut self,
        range: Range<usize>,
        bias: SB,
    ) -> &mut Self
       where SB: Into<SliceBias>;
}

Extension trait for [T] and str.

Required Associated Types

type Elem

The type of a slice element.

Required Methods

fn contains_slice(&self, other: &Self) -> bool

Checks whether self fully contains the other slice in memory.

If other is a zero-length slice it is not contained inside self.

Example

Called on slices

use core_extensions::SliceExt;

let list = vec![0, 1, 2, 3, 4, 5];
 
let another = [6, 7, 8];
 
assert!(list.contains_slice(&list[..1]));
assert!(list.contains_slice(&list[3..]));

// Empty slices aren't considered contained by any other slice
assert!(!list.contains_slice(&list[..0]));
assert!(!list.contains_slice(&another[..0]));

assert!(!list.contains_slice(&another));

Called on strs

use core_extensions::SliceExt;

let string = "foo bar baz";
 
let another = String::from(string);
 
let foo = &string[..3];
let bar = &string[4..7];
let baz = &string[8..11];
 
assert!(string.contains_slice(foo));
assert!(string.contains_slice(bar));
assert!(string.contains_slice(baz));

// Empty slices aren't considered contained by any other slice
assert!(!string.contains_slice(&string[..0]));

assert!(!string.contains_slice(&another));

fn is_slice(&self, other: &Self) -> bool

Checks whether self is exactly the other slice in memory.

Example

Called on slices

use core_extensions::SliceExt;

let list = [0, 1, 2, 3, 4, 5];
let slice_0 = &list[..0];
let slice_1 = &list[..];

let other = [0, 1, 2, 3, 4, 5];

assert!( slice_0.is_slice(slice_0));
assert!( slice_0.is_slice(&list[..0]));
assert!(!slice_0.is_slice(slice_1));
assert!(!slice_0.is_slice(&[]));

assert!(!list.is_slice(&other));

Called on strs

use core_extensions::SliceExt;

let string = "foo bar baz";
 
let another = String::from(string);
 
let foo = &string[..3];
let bar = &string[4..7];
let baz = &string[8..11];
 
assert!(!string.is_slice(foo));
assert!(!string.is_slice(bar));
assert!(!string.is_slice(baz));
assert!(string.is_slice(string));

assert!(string[..0].is_slice(&string[..0]));

assert!(!string.is_slice(&another));

fn offset_of_slice(&self, other: &Self) -> usize

Returns the index at which other starts.

If other is not inside self, this returns self.len()

Example

Called on slices

use core_extensions::SliceExt;

let list = vec![0, 1, 2, 3, 4, 5];
 
let other = [0, 1, 2, 3];

assert_eq!(list.offset_of_slice(&list[..0]), 0);
assert_eq!(list.offset_of_slice(&list[3..]), 3);
assert_eq!(list.offset_of_slice(&list[5..]), 5);
assert_eq!(list.offset_of_slice(&list[6..]), list.len());
assert_eq!(list.offset_of_slice(&[]), list.len());

assert_eq!(list.offset_of_slice(&other), list.len());

Called on strs

use core_extensions::SliceExt;

let string = "foo bar baz";
 
let another = String::from(string);
 
let foo = &string[..3];
let bar = &string[4..7];
let baz = &string[8..11];
 
assert_eq!(string.offset_of_slice(string), 0);
assert_eq!(string.offset_of_slice(&string[..0]), 0);
assert_eq!(string.offset_of_slice(foo), 0);
assert_eq!(string.offset_of_slice(bar), 4);
assert_eq!(string.offset_of_slice(baz), 8);
assert_eq!(string.offset_of_slice(&string[11..]), 11);

assert_eq!(string.offset_of_slice(&another), string.len());

fn get_offset_of_slice(&self, other: &Self) -> Option<usize>

Returns the index at which other starts.

If other is a zero-length slice, or is not inside self, this returns None.

Example

Called on slices

use core_extensions::SliceExt;

let list = [0, 1, 2, 3, 4, 5];
 
let other = [0, 1, 2, 3];

assert_eq!(list.get_offset_of_slice(&list[..0]), None);
assert_eq!(list.get_offset_of_slice(&list[1..]), Some(1));
assert_eq!(list.get_offset_of_slice(&list[3..]), Some(3));
assert_eq!(list.get_offset_of_slice(&list[5..]), Some(5));
assert_eq!(list.get_offset_of_slice(&list[6..]), None);

assert_eq!(list.get_offset_of_slice(&other), None);

Called on strs

use core_extensions::SliceExt;

let string = "foo bar baz";
 
let another = String::from(string);
 
let foo = &string[..3];
let bar = &string[4..7];
let baz = &string[8..11];
 
assert_eq!(string.get_offset_of_slice(&string[..0]), None);
assert_eq!(string.get_offset_of_slice(string), Some(0));
assert_eq!(string.get_offset_of_slice(foo), Some(0));
assert_eq!(string.get_offset_of_slice(bar), Some(4));
assert_eq!(string.get_offset_of_slice(baz), Some(8));
assert_eq!(string.get_offset_of_slice(&string[11..]), None);

assert_eq!(string.get_offset_of_slice(&another), None);

fn index_of(&self, other: *const Self::Elem) -> usize

Returns the index of other if it’s stored in the slice (if it points within the slice).

If other is not inside self, this returns self.len().

Example

Called on slices

use core_extensions::SliceExt;

let list = vec![0, 1, 2, 3, 4, 5];

let other = [0, 1, 2, 3];

assert_eq!(list.index_of(&list[0]), 0);
assert_eq!(list.index_of(&list[3]), 3);
assert_eq!(list.index_of(&list[5]), 5);
assert_eq!(list.index_of(list.as_ptr().wrapping_offset(6)), 6);
assert_eq!(list.index_of(list.as_ptr().wrapping_offset(7)), 6);
assert_eq!(list.index_of(&0), list.len());

assert_eq!(list.index_of(&other[0]), list.len());
assert_eq!(list.index_of(&other[1]), list.len());

Called on strs

use core_extensions::SliceExt;

let string = String::from("abcdefgh");
let bytes = string.as_bytes();

let other = b"abcdefgh";

assert_eq!(string.index_of(&bytes[0]), 0);
assert_eq!(string.index_of(&bytes[3]), 3);
assert_eq!(string.index_of(&bytes[5]), 5);
assert_eq!(string.index_of(bytes.as_ptr().wrapping_offset(6)), 6);
assert_eq!(string.index_of(bytes.as_ptr().wrapping_offset(7)), 7);
assert_eq!(string.index_of(&0), string.len());

assert_eq!(string.index_of(&other[0]), string.len());
assert_eq!(string.index_of(&other[1]), string.len());

fn get_index_of(&self, other: *const Self::Elem) -> Option<usize>

Returns the index of other if it’s stored in the slice (if it points within the slice).

If other is not inside self, this returns None.

Example

Called on slices

use core_extensions::SliceExt;

let list = vec![0, 1, 2, 3, 4, 5];

let other = [0, 1, 2, 3];

assert_eq!(list.get_index_of(&list[0]), Some(0));
assert_eq!(list.get_index_of(&list[3]), Some(3));
assert_eq!(list.get_index_of(&list[5]), Some(5));
assert_eq!(list.get_index_of(list.as_ptr().wrapping_offset(6)), None);
assert_eq!(list.get_index_of(list.as_ptr().wrapping_offset(7)), None);
assert_eq!(list.get_index_of(&0), None);

assert_eq!(list.get_index_of(&other[0]), None);
assert_eq!(list.get_index_of(&other[1]), None);

Called on strs

use core_extensions::SliceExt;

let string = String::from("abcdefgh");
let bytes = string.as_bytes();

let other = b"abcdefgh";

assert_eq!(string.get_index_of(&bytes[0]), Some(0));
assert_eq!(string.get_index_of(&bytes[3]), Some(3));
assert_eq!(string.get_index_of(&bytes[5]), Some(5));
assert_eq!(string.get_index_of(bytes.as_ptr().wrapping_offset(6)), Some(6));
assert_eq!(string.get_index_of(bytes.as_ptr().wrapping_offset(7)), Some(7));
assert_eq!(string.get_index_of(&0), None);

assert_eq!(string.get_index_of(&other[0]), None);
assert_eq!(string.get_index_of(&other[1]), None);

fn slice_lossy<SB>(&self, range: Range<usize>, bias: SB) -> &Self

where SB: Into<SliceBias>,

Used for non-panicking slicing.

If range.end is less than range.start, this returns an empty slice.

bias parameter

The bias parameter, by being converted into a SliceBias, determines how this method handles invalid ranges.

The impl for [T] ignores this parameter, saturating ranges at self.len().

For str, it grows the range in the directions determined by bias parameter.

Examples

[T] slice

use core_extensions::SliceExt;

let arr = [1, 2, 3, 4, 5, 6];
assert_eq!(arr.slice_lossy(0..3, ()), &arr[..3]);
assert_eq!(arr.slice_lossy(3..1000, ()), &arr[3..]);
assert_eq!(arr.slice_lossy(1000..1000, ()), &[]);
assert_eq!(arr.slice_lossy(1000..0, ()), &[]);

str slice

use core_extensions::SliceExt;
use core_extensions::slices::SliceBias;

let word = "niño"; // 'ñ' is 2 bytes long , spanning the range 2..4

assert_eq!(word.slice_lossy(0..3, SliceBias::LEFT ), "ni");
assert_eq!(word.slice_lossy(0..3, SliceBias::RIGHT), "niñ");
assert_eq!(word.slice_lossy(0..3, SliceBias::IN ), "ni");
assert_eq!(word.slice_lossy(0..3, SliceBias::OUT), "niñ");

assert_eq!(word.slice_lossy(3..10000, ()), "ño");
assert_eq!(word.slice_lossy(3..10000, SliceBias::OUT), "ño");

assert_eq!(word.slice_lossy(1000..1000, ()), "");
assert_eq!(word.slice_lossy(1000..1000, SliceBias::OUT), "");
assert_eq!(word.slice_lossy(1000..0, SliceBias::OUT), "");

fn slice_lossy_mut<SB>(&mut self, range: Range<usize>, bias: SB) -> &mut Self

where SB: Into<SliceBias>,

Used for non-panicking mutable slicing.

Identical behavior to slice_lossy with respect to ranges.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl SliceExt for str

type Elem = u8

fn contains_slice(&self, other: &Self) -> bool

fn is_slice(&self, other: &Self) -> bool

fn offset_of_slice(&self, other: &Self) -> usize

fn get_offset_of_slice(&self, other: &Self) -> Option<usize>

fn index_of(&self, other: *const u8) -> usize

fn get_index_of(&self, other: *const u8) -> Option<usize>

fn slice_lossy<SB>(&self, range: Range<usize>, bias: SB) -> &Self

where SB: Into<SliceBias>,

fn slice_lossy_mut<SB>(&mut self, range: Range<usize>, bias: SB) -> &mut Self

where SB: Into<SliceBias>,

impl<T> SliceExt for [T]

type Elem = T

fn contains_slice(&self, other: &Self) -> bool

fn is_slice(&self, other: &Self) -> bool

fn offset_of_slice(&self, other: &Self) -> usize

fn get_offset_of_slice(&self, other: &Self) -> Option<usize>

fn index_of(&self, other: *const T) -> usize

fn get_index_of(&self, other: *const T) -> Option<usize>

fn slice_lossy<SB>(&self, range: Range<usize>, _bias: SB) -> &Self

fn slice_lossy_mut<SB>(&mut self, range: Range<usize>, _bias: SB) -> &mut Self

Implementors