Struct uwl::Stream

pub struct Stream<'a, T: Advancer> { /* fields omitted */ }

A stream of "chars". Handles ASCII and/or Unicode depending on the Advancer

Note

This stream's idea of a "char" is a string slice (&str). In some of the methods, this slice may only be wide as any ASCII (and/or Unicode) character can be. Others, such as take_while, may return more than one "char".

Methods

impl<'a, T: Advancer> Stream<'a, T>

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

Create a new stream from a source.

pub fn current(&self) -> Option<&'a str>

Fetch the current char.

Example

use uwl::AsciiStream;

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

assert_eq!(stream.current(), Some("h"));

pub fn next(&mut self) -> Option<&'a str>

Advance to the next char

Example

use uwl::AsciiStream;

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

assert_eq!(stream.current(), Some("h"));

stream.next();
assert_eq!(stream.current(), Some("e"));

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

Advance by x chars.

Example

use uwl::AsciiStream;

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

assert_eq!(stream.advance(5), Some("hello"));
stream.next();
assert_eq!(stream.advance(5), Some("world"));
assert!(stream.at_end());

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::AsciiStream;

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

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

pub fn peek(&self, ahead: usize) -> Option<&'a str>

Lookahead by x chars. Returns the char it landed on.

Example

use uwl::AsciiStream;

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

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

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

Lookahead by x chars. Returns a substring up to the end it landed on.

Example

use uwl::AsciiStream;

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

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

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

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

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

Lookahead for as long as f returns true. Returns a substring up to the end it landed on.

Example

use uwl::{AsciiStream, StrExt};

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

assert_eq!(stream.peek_while(|s| s.is_alphabetic()), "hello");
assert_eq!(stream.rest(), "hello _wo_r_l_4d");
stream.take_while(|s| s.is_alphabetic());
stream.next();
assert_eq!(stream.peek_while(|s| s.is_diglet()), "_wo_r_l_4d");
assert_eq!(stream.rest(), "_wo_r_l_4d");

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

Lookahead for as long as f does not return true. Returns a substring up to the end it landed on.

Example

use uwl::AsciiStream;

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

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

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

Consume while true.

Example

use uwl::AsciiStream;

// Import a few utility methods (for `is_alphabetic`)
use uwl::StrExt;

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

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

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

Consume until true.

Example

use uwl::AsciiStream;

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

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

pub fn parse<'b>(&mut self, fmt: &'b str) -> Result<&'a str, &'b str>

Slice a portion from the stream by using rules defined by the formatting string

• {} => the portion to return
• (x) => optional text x that may be present, ignored
• letters/numbers => text to expect

To espace { or (, use them twice. For example, ((/{{. This is not necessary for } or ).

Whitespace between { and } is skipped.

If parsing does not succeed, this won't advance. On Err, the expected string, or "parse failed", are returned.

Examples

Get anything between html h1 tags

use uwl::AsciiStream;

let mut stream = AsciiStream::new("<h1>hello world!</h1>");

assert_eq!(stream.parse("<h1>{}</h1>"), Ok("hello world!"));

Parse html tags

use uwl::AsciiStream;

let mut stream = AsciiStream::new("<h2></h2>");

// the opening tag - <h2>
assert_eq!(stream.parse("<(/){}>"), Ok("h2"));
// the closing tag - </h2>
assert_eq!(stream.parse("<(/){}>"), Ok("h2"));

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

Returns the remainder (after the offset).

Example

use uwl::AsciiStream;

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

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

pub fn at_end(&self) -> bool

Determines the end of the input.

Example

use uwl::AsciiStream;

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

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

pub fn offset(&self) -> usize

The "offset"; the start of the current char.

Example

use uwl::UnicodeStream;

let mut stream = UnicodeStream::new("a 🍆");

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(), 6);

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

Returns the source the stream is operating on.

Example

use uwl::AsciiStream;

let stream = AsciiStream::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::UnicodeStream;

let mut stream = UnicodeStream::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

Is the provided source empty?

Example

use uwl::AsciiStream;

let stream = AsciiStream::new("");

assert!(stream.is_empty());
assert_eq!(stream.source(), "");

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

Set the offset.

Panics if the offset is in the middle of a unicode character.

pub unsafe fn set_unchecked(&mut self, pos: usize)

Set the offset without any checks.

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

Increment the offset by bytes.

Panics if the offset appears to be in the middle of a unicode character.

pub unsafe fn increment_unchecked(&mut self, bytes: usize)

Increment the offset by bytes without any checks.

Trait Implementations

impl<'_, T: Advancer> Debug for Stream<'_, T>

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

Formats the value using the given formatter.

impl<'_, T: Advancer> Clone for Stream<'_, T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'_, T: Advancer> Default for Stream<'_, T>

fn default() -> Self

Returns the "default value" for a type.