Struct uwl::StringStream

pub struct StringStream<'a> {
    pub src: &'a str,
    /* private fields */
}

A stream of chars. Handles both ASCII and Unicode.

Note

This stream returns chars as &strs. In instances like take_while, the &str refers to actual multi-char substrings (e.g “foo”).

Fields

src: &'a str

The source this stream operates on.

Implementations

impl<'a> StringStream<'a>

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

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

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

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

Advance to the next char

Example

use uwl::StringStream;

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

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

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

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

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

Lookahead by x chars. Returns the char it landed on. This does not actually modify, it just needs to temporarily advance.

Example

use uwl::StringStream;

let mut stream = StringStream::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(&mut self, ahead: usize) -> &'a str

Lookahead by x chars. Returns a substring up to the end it landed on. This does not actually modify, it just needs to temporarily advance.

Example

use uwl::StringStream;

let mut stream = StringStream::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_str(&mut self, ahead: usize) -> &'a str

👎Deprecated since 0.1.3: renamed to peek_for

Lookahead by x chars. Returns a substring up to the end it landed on. This does not actually modify, it just needs to temporarily advance.

Deprecated

Use peek_for instead.

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

Consume while true.

Example

use uwl::StringStream;

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

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

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

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

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

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.

Examples

Get anything between html h1 tags

use uwl::StringStream;

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

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

Parse html tags

use uwl::StringStream;

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

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

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

let mut stream = StringStream::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 set(&mut self, pos: usize)

Set the offset. Panics if the offset is in the middle of a unicode character, or exceeds the length of the input.

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

Set the offset without any checks.

Trait Implementations

impl<'a> Clone for StringStream<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for StringStream<'a>

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

Formats the value using the given formatter.