Struct byteseeker::ByteSeeker

pub struct ByteSeeker<'a, RS: 'a + Read + Seek> { /* fields omitted */ }

Seeker that can seek the occurences of a given byte slice within a stream of bytes.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [b'0', b'\n', b'0'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

assert_eq!(seeker.seek(b"0").unwrap(), 0);
assert_eq!(seeker.seek_nth(b"0", 1).unwrap(), 2);

// After resetting, we can seek from the other direction.
seeker.reset();
assert_eq!(seeker.seek_back(b"0").unwrap(), 2);
assert_eq!(seeker.seek_nth_back(b"0", 1).unwrap(), 0);

The ByteSeeker uses a internal buffer to read a chunk of bytes into memory to search the occurences of a given byte slice. You can specify the capacity of the interal buffer by initializing a ByteSeeker using ByteSeeker::with_capacity, if you are seeking within a pretty small or pretty large stream. The default capacity of the internal buffer is default to 1024 currently.

It’s worth noting that seeking a byte slice whose length is greater than the capacity of the calling ByteSeeker is not allowed.

Implementations

impl<'a, RS: 'a + Read + Seek> ByteSeeker<'a, RS>

pub fn new(stream: &'a mut RS) -> Self

Creates a new ByteSeeker that wraps a byte stream that implements Read and Seek.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [1, 2, 3];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

pub fn with_capacity(stream: &'a mut RS, cap: usize) -> Self

Creates a new ByteSeeker that wraps a byte stream that implements Read and Seek, and sets the capacity of its internal buffer to the given capacity.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [1, 2, 3];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::with_capacity(&mut cursor, 3);

pub fn len(&self) -> usize

Returns the length of the underlying byte stream.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = "lorem ipsum".as_bytes();
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

assert_eq!(seeker.len(), 11);

pub fn capacity(&self) -> usize

Returns the capacity of this ByteSeeker.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = "lorem ipsum".as_bytes();
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::with_capacity(&mut cursor, 11);

assert_eq!(seeker.capacity(), 11);

pub fn reset(&mut self)

Resets the state of the ByteSeeker to its original, so you can reuse this initialized ByteSeeker as it was newly created.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [b'0', b'\n', b'0'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

assert_eq!(seeker.seek(b"0").unwrap(), 0);
assert_eq!(seeker.seek(b"0").unwrap(), 2);

// The `reset` here is equivalent to:
// let mut seeker = ByteSeeker::new(&mut cursor);
seeker.reset();
assert_eq!(seeker.seek_back(b"0").unwrap(), 2);
assert_eq!(seeker.seek_back(b"0").unwrap(), 0);

pub fn seek(&mut self, bytes: &[u8]) -> Result<usize>

Searches for the given bytes forwards, and returns the offset (ralative to the start of the underlying byte stream) if the given bytes were found.

If the initialized ByteSeeker haven’t been called before, seek will start from the beginning; Otherwise, it will start from the last found seek position + 1.

The ByteSeeker is stateful, which means you can call seek multiple times until reaching the end of the underlying byte stream.

Errors

If the given bytes were not found, an error variant of ErrorKind::ByteNotFound will be returned. If any other I/O errors were encountered, an error variant of ErrorKind::Io will be returned.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [b'0', b'\n', b'\n', b'\n'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

assert_eq!(seeker.seek(b"0").unwrap(), 0);
assert_eq!(seeker.seek(b"\n\n").unwrap(), 1);
assert_eq!(seeker.seek(b"\n\n").is_err(), true);

pub fn seek_back(&mut self, bytes: &[u8]) -> Result<usize>

Searches for the given bytes backwards, and returns the offset (ralative to the start of the underlying byte stream) if the given bytes were found.

If the initialized ByteSeeker haven’t been called before, seek will start from the end; Otherwise, it will start from the last found seek position - 1.

The ByteSeeker is stateful, which means you can call seek_back multiple times until reaching the end of the underlying byte stream.

Errors

If the given bytes were not found, an error variant of ErrorKind::ByteNotFound will be returned. If any other I/O errors were encountered, an error variant of ErrorKind::Io will be returned.

Examples

use byteseeker::ByteSeeker;
use std::io::Cursor;

let bytes = [b'0', b'\n', b'\n', b'\n'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);

assert_eq!(seeker.seek_back(b"\n\n").unwrap(), 2);
assert_eq!(seeker.seek_back(b"\n\n").is_err(), true);

pub fn seek_nth(&mut self, bytes: &[u8], nth: usize) -> Result<usize>

Seeks the nth occurence of the given bytes forwards, and returns the offset (ralative to the start of the underlying byte stream) if the given bytes were found.

If the initialized ByteSeeker haven’t been called before, seek_nth will start from the beginning; Otherwise, it will start from the last found seek position + 1.

The ByteSeeker is stateful, which means you can call seek_nth multiple times until reaching the end of the underlying byte stream.

Errors

If the given bytes were not found, an error variant of ErrorKind::ByteNotFound will be returned. If any other I/O errors were encountered, an error variant of ErrorKind::Io will be returned.

Examples

use std::io::Cursor;
use byteseeker::ByteSeeker;

let mut bytes = [b'\n', b'\n', b'\n', b'\n', b'\n'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);
assert_eq!(seeker.seek_nth(b"\n\n", 2).unwrap(), 2);
assert_eq!(seeker.seek_nth(b"\n\n", 2).is_err(), true);

pub fn seek_nth_back(&mut self, bytes: &[u8], nth: usize) -> Result<usize>

Seeks the nth occurence of the given bytes backwards, and returns the offset (ralative to the start of the underlying byte stream) if the given bytes were found.

If the initialized ByteSeeker haven’t been called before, seek_nth_back will start from the end; Otherwise, it will start from the last found seek position - 1.

The ByteSeeker is stateful, which means you can call seek_nth_back multiple times until reaching the end of the underlying byte stream.

Errors

If the given bytes were not found, an error variant of ErrorKind::ByteNotFound will be returned. If any other I/O errors were encountered, an error variant of ErrorKind::Io will be returned.

Examples

use std::io::Cursor;
use byteseeker::ByteSeeker;

let mut bytes = [b'\n', b'\n', b'\n', b'\n', b'\n'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);
assert_eq!(seeker.seek_nth_back(b"\n\n", 2).unwrap(), 1);
assert_eq!(seeker.seek_nth_back(b"\n\n", 2).is_err(), true);

pub fn get_mut(&mut self) -> &mut RS

Gets a mutable reference to the underlying reader.

It is inadvisable to directly read from the underlying reader.

Examples

use byteseeker::ByteSeeker;
use std::io::{Cursor, Read};

let bytes = [b'0', b'\n', b'\n', b'\n'];
let mut cursor = Cursor::new(bytes);
let mut seeker = ByteSeeker::new(&mut cursor);
assert_eq!(seeker.seek(b"\n").unwrap(), 1);

let mut reader = seeker.get_mut();
let mut buf = Vec::new();
let _ = reader.read_to_end(&mut buf);
assert_eq!(&buf, &[b'\n', b'\n']);

Trait Implementations

impl<'a, RS: Debug + 'a + Read + Seek> Debug for ByteSeeker<'a, RS>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.