Struct Stream

pub struct Stream<'a> { /* private fields */ }

A stream of bytes and characters.

Implementations

impl<'a> Stream<'a>

pub fn new(src: &'a str) -> Self

Create a new stream from a string source.

pub fn offset(&self) -> usize

Returns the current position of the stream.

Example

use uwl::Stream;

let mut stream = Stream::new("an 🍆");

assert_eq!(stream.offset(), 0);
stream.next();
assert_eq!(stream.offset(), 1);
stream.next();
assert_eq!(stream.offset(), 2);
stream.next();
assert_eq!(stream.offset(), 3);
stream.next_char();
assert_eq!(stream.offset(), 7);

pub fn source(&self) -> &'a str

Returns the source the stream is operating on.

Example

use uwl::Stream;

let stream = Stream::new("Once upon a time... life");

assert_eq!(stream.source(), "Once upon a time... life");

pub fn len(&self) -> usize

The provided source’s length. Returns the amount of bytes.

Example

use uwl::Stream;

let mut stream = Stream::new("abc🍆");
assert_eq!(stream.len(), 7);
stream.next();
// Regardless of any modification method present on the stream,
// `len` always returns a constant.
assert_eq!(stream.len(), 7);

pub fn is_empty(&self) -> bool

Returns a boolean indicating whether there are no more bytes to parse.

Example

use uwl::Stream;

let mut stream = Stream::new("a");

assert!(!stream.is_empty());
stream.next();
assert!(stream.is_empty());
assert_eq!(stream.current(), None);

pub fn rest(&self) -> &'a str

Returns the remainder (after the offset).

Example

use uwl::Stream;

let mut stream = Stream::new("foo bar");

assert_eq!(stream.take_until(|s| s == b' '), "foo");
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.rest(), "bar");

pub fn peek(&self, amount: usize) -> Option<u8>

Look ahead by the amount of bytes.

Example

use uwl::Stream;

let mut stream = Stream::new("hello");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.peek(1), Some(b'e'));
assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.peek(2), Some(b'l'));
assert_eq!(stream.current(), Some(b'h'));

pub fn peek_char(&self, amount: usize) -> Option<char>

Look ahead by the amount of characters.

Example

use uwl::Stream;

let mut stream = Stream::new("🍆👅🍆");

assert_eq!(stream.current_char(), Some('🍆'));
assert_eq!(stream.peek_char(0), Some('🍆'));
assert_eq!(stream.current_char(), Some('🍆'));
assert_eq!(stream.peek_char(1), Some('👅'));
assert_eq!(stream.current_char(), Some('🍆'));
assert_eq!(stream.peek_char(2), Some('🍆'));

pub fn current(&self) -> Option<u8>

Fetch the current byte.

Example

use uwl::Stream;

let stream = Stream::new("hello");

assert_eq!(stream.current(), Some(b'h'));

pub fn current_char(&self) -> Option<char>

Fetch the current character.

Example

use uwl::Stream;

let stream = Stream::new("😃 😂");

assert_eq!(stream.current_char(), Some('😃'));

pub fn next(&mut self) -> Option<u8>

Advance to the next byte. Returns the current byte prior to advancement.

Example

use uwl::Stream;

let mut stream = Stream::new("hello");

assert_eq!(stream.current(), Some(b'h'));

assert_eq!(stream.next(), Some(b'h'));
assert_eq!(stream.current(), Some(b'e'));

pub fn next_char(&mut self) -> Option<char>

Advance to the next character. Returns the current character prior to advancement.

Example

use uwl::Stream;

let mut stream = Stream::new("😃 😂");

assert_eq!(stream.next_char(), Some('😃'));
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.current_char(), Some('😂'));

pub fn peek_while(&self, f: impl FnMut(u8) -> bool) -> &'a str

Look ahead based on a predicate while it returns true. Returns a string before the lookahead and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello _wo_r_l_4d");

assert_eq!(stream.peek_while(|b| b.is_ascii_alphabetic()), "hello");
assert_eq!(stream.rest(), "hello _wo_r_l_4d");
stream.take_while(|b| b.is_ascii_alphabetic());
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.peek_while(|b| b == b'_' || b.is_ascii_alphanumeric()), "_wo_r_l_4d");
assert_eq!(stream.rest(), "_wo_r_l_4d");

pub fn peek_while_char(&self, f: impl FnMut(char) -> bool) -> &'a str

Look ahead based on a predicate while it returns true. Returns a string before the lookahead and after.

Example

use uwl::Stream;

let mut stream = Stream::new("🍆🍆🍆🍆🍆 _wo_r_l_4d");

assert_eq!(stream.peek_while_char(|c| c == '🍆'), "🍆🍆🍆🍆🍆");
assert_eq!(stream.rest(), "🍆🍆🍆🍆🍆 _wo_r_l_4d");
stream.take_while_char(|c| c == '🍆');
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.peek_while(|b| b == b'_' || b.is_ascii_alphanumeric()), "_wo_r_l_4d");
assert_eq!(stream.rest(), "_wo_r_l_4d");

pub fn peek_until(&self, f: impl FnMut(u8) -> bool) -> &'a str

Look ahead based on a predicate until it returns true. Returns a string before the lookahead and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello!");

assert_eq!(stream.peek_until(|b| b == b'!'), "hello");
assert_eq!(stream.rest(), "hello!");

pub fn peek_until_char(&self, f: impl FnMut(char) -> bool) -> &'a str

Look ahead based on a predicate until it returns true. Returns a string before the lookahead and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello🍆");

assert_eq!(stream.peek_until_char(|c| c == '🍆'), "hello");
assert_eq!(stream.rest(), "hello🍆");

pub fn take_while(&mut self, f: impl FnMut(u8) -> bool) -> &'a str

Consume bytes based on a predicate while it returns true. Returns a string before the consumption and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.take_while(|s| s.is_ascii_alphabetic()), "hello");
assert_eq!(stream.current(), None);

pub fn take_while_char(&mut self, f: impl FnMut(char) -> bool) -> &'a str

Consume bytes based on a predicate while it returns true. Returns a string before the consumption and after.

Example

use uwl::Stream;

let mut stream = Stream::new("🍆🍆🍆");

assert_eq!(stream.current_char(), Some('🍆'));
assert_eq!(stream.take_while_char(|c| c == '🍆'), "🍆🍆🍆");
assert_eq!(stream.current_char(), None);

pub fn take_until(&mut self, f: impl FnMut(u8) -> bool) -> &'a str

Consume bytes based on a predicate until it returns true. Returns a string before the consumption and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello!");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.take_until(|b| b == b'!'), "hello");
assert_eq!(stream.current(), Some(b'!'));

pub fn take_until_char(&mut self, f: impl FnMut(char) -> bool) -> &'a str

Consume bytes based on a predicate until it returns true. Returns a string before the consumption and after.

Example

use uwl::Stream;

let mut stream = Stream::new("hello🍆");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.take_until_char(|c| c == '🍆'), "hello");
assert_eq!(stream.current_char(), Some('🍆'));

pub fn peek_for(&self, amount: usize) -> &'a str

Look ahead by the amount of bytes. Returns a string before the lookahead and after.

Note

If the amount exceeds the amount of available bytes, this will return the rest of the source.

Example

use uwl::Stream;

let mut stream = Stream::new("hello world");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.peek_for(5), "hello");

for _ in 0..5 {
    stream.next();
}

assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.peek_for(5), "world");
assert_eq!(stream.next(), Some(b'w'));
assert_eq!(stream.next(), Some(b'o'));
assert_eq!(stream.peek_for(10), "rld");
assert_eq!(stream.next(), Some(b'r'));
assert_eq!(stream.next(), Some(b'l'));
assert_eq!(stream.next(), Some(b'd'));

pub fn peek_for_char(&self, amount: usize) -> &'a str

Look ahead by the amount of characters. Returns a string before the lookahead and after.

Note

If the amount exceeds the amount of available characters, this will return the rest of the source.

Example

use uwl::Stream;

let mut stream = Stream::new("hello 🍆🍆 🍆🍆🍆🍆");

assert_eq!(stream.current(), Some(b'h'));
assert_eq!(stream.peek_for_char(5), "hello");

for _ in 0..5 {
    stream.next();
}

assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.peek_for_char(2), "🍆🍆");
assert_eq!(stream.peek_for_char(10), "🍆🍆 🍆🍆🍆🍆");

pub fn advance(&mut self, amount: usize) -> &'a str

Advance onward by the amount of bytes. Returns a string before the advancement and after.

Note

If the amount exceeds the amount of available bytes, this will return the rest of the source.

Example

use uwl::Stream;

let mut stream = Stream::new("hello world");

assert_eq!(stream.advance(5), "hello");
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.advance(2), "wo");
assert_eq!(stream.advance(5), "rld");
assert!(stream.is_empty());

pub fn advance_char(&mut self, amount: usize) -> &'a str

Advance onward by the amount of bytes. Returns a string before the advancement and after.

Note

If the amount exceeds the amount of available bytes, this will return the rest of the source.

Example

use uwl::Stream;

let mut stream = Stream::new("hello 🍆🍆 🍆🍆🍆");

assert_eq!(stream.advance_char(5), "hello");
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.advance_char(2), "🍆🍆");
assert_eq!(stream.next(), Some(b' '));
assert_eq!(stream.advance_char(6), "🍆🍆🍆");
assert!(stream.is_empty());

pub fn eat(&mut self, m: &str) -> bool

Advance if the leading string matches to the expected input. Returns true on succession, false on failure.

Example

use uwl::Stream;

let mut stream = Stream::new("hello world");

assert!(stream.eat("hello"));
assert!(!stream.eat("not a space"));
assert!(stream.eat(" "));
assert_eq!(stream.rest(), "world");

pub fn set(&mut self, pos: usize)

Set the offset to the pos.

pub fn increment(&mut self, amount: usize)

Increments the offset by the amount

Trait Implementations

impl<'a> Clone for Stream<'a>

fn clone(&self) -> Stream<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Stream<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Stream<'a>

fn default() -> Stream<'a>

Returns the “default value” for a type.

impl<'a> Copy for Stream<'a>