Struct StrQueue

pub struct StrQueue { /* private fields */ }

Queue for a string.

This queue can contain incomplete UTF-8 byte sequences at the tail. However, if it became sure that the sequence is invalid as UTF-8 sequence, the invalid bytes would be replaced by U+FFFD REPLACEMENT CHARACTER.

Implementations

impl StrQueue

StrQueue creation.

pub fn new() -> Self

Creates an empty StrQueue.

Examples

use str_queue::StrQueue;

let deque = StrQueue::new();

pub fn with_capacity(capacity: usize) -> Self

Creates an empty StrQueue with at least the given capacity.

Examples

use str_queue::StrQueue;

let deque = StrQueue::with_capacity(42);

assert!(deque.capacity() >= 42);

impl StrQueue

Capacity.

pub fn capacity(&self) -> usize

Returns the number of bytes the StrQueue can hold without reallocating.

Examples

use str_queue::StrQueue;

let deque = StrQueue::with_capacity(42);

assert!(deque.capacity() >= 42);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more bytes.

pub fn reserve_exact(&mut self, additional: usize)

Reserves capacity for exact additional more bytes.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the StrQueue as much as possible.

impl StrQueue

Subrange access.

pub fn bytes_range<R>(&self, range: R) -> BytesRange<'_>

where R: RangeBounds<usize>,

Returns the subrange accessor for the queue.

pub fn chars_range<R>(&self, range: R) -> CharsRange<'_>

where R: RangeBounds<usize>,

Returns the subrange accessor for the queue.

The returned range can contain an incomplete character at the end. If you want to exclude a possible trailing incomplete character in the range, use CharsRange::to_complete or CharsRange::trim_last_incomplete_char.

Panics

Panics if the start bound of the range does not lie on UTF-8 sequence boundary.

impl StrQueue

Content length and existence.

pub fn len(&self) -> usize

Returns the string length in bytes, including incomplete bytes.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"hello\xce");
assert_eq!(queue.len(), 6);

pub fn is_empty(&self) -> bool

Returns true if the queue is completely empty (i.e. has no bytes).

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::new();
assert!(queue.is_empty());

queue.push_str("hello");
assert!(!queue.is_empty());

pub fn len_complete(&self) -> usize

Returns the string length in bytes, excluding incomplete bytes.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"hello\xce");
assert_eq!(queue.len_complete(), 5);

pub fn len_incomplete(&self) -> usize

Returns the length of incomplete bytes.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"hello\xce");
assert_eq!(queue.len_incomplete(), 1);

pub fn is_empty_complete(&self) -> bool

Returns true if the StrQueue contains no complete string.

This returns the same value as self.first().is_none().

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::new();
assert!(queue.is_empty_complete());

queue.push_bytes(b"\xce");
assert!(queue.is_empty_complete());
assert_eq!(queue.first_char(), None);

queue.push_bytes(b"\xb1");
assert!(!queue.is_empty_complete());
assert_eq!(queue.first_char(), Some('\u{03B1}'));

pub fn is_complete(&self) -> bool

Returns true if the content is a complete string, i.e. has no trailing incomplete character.

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::from(b"abc\xce");
assert!(!queue.is_complete());
queue.push_bytes(b"\xb1");
// Now the string is "abc\u{03B1}".
assert!(queue.is_complete());

impl StrQueue

Buffer and content manipulation.

pub fn clear(&mut self)

Clears the StrQueue, removing all bytes.

Examples

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from(b"Hello \xce");
assert!(!queue.is_empty());

queue.clear();
assert!(queue.is_empty());

pub fn trim_last_incomplete_char(&mut self) -> usize

Trims the last incomplete character, and returns the length of the trimmed bytes.

If the string is complete (i.e. no incomplete character follows), does nothing and returns 0.

If you want to get a modified copy instead of modifying self itself, use CharsRange::to_complete.

Examples

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from(b"Hello \xce");
assert_eq!(
    queue.display(PartialHandling::Emit).to_string(),
    "Hello \u{FFFD}"
);

queue.trim_last_incomplete_char();
assert_eq!(queue.display(PartialHandling::Emit).to_string(), "Hello ");

pub fn push_str(&mut self, s: &str)

Pushes the given string to the queue.

Examples

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from("hello");
queue.push_str(" world");

assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "hello world"
);

pub fn push_char(&mut self, c: char)

Pushes the given character to the queue.

Examples

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from("hello");
queue.push_char('!');

assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "hello!"
);

pub fn push_bytes(&mut self, bytes: &[u8])

Pushes the given bytes to the queue.

Invalid UTF-8 sequences not at the last would be replaced with U+FFFD REPLACEMENT CHARACTER. The last incomplete sequences would be kept, since it might become valid when more bytes are appended later.

Examples

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from(b"alpha \xce");
assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "alpha \u{FFFD}"
);

queue.push_bytes(b"\xb1");
assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "alpha \u{03B1}"
);

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

Pops the first character in the buffer and returns it.

Trailing incomplete character is ignored.

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::from("hello");

assert_eq!(queue.pop_char(), Some('h'));
assert_eq!(queue.pop_char(), Some('e'));
assert_eq!(queue.pop_char(), Some('l'));
assert_eq!(queue.pop_char(), Some('l'));
assert_eq!(queue.pop_char(), Some('o'));
assert_eq!(queue.pop_char(), None);
assert!(queue.is_empty());

use str_queue::StrQueue;

let mut queue = StrQueue::from(b"a\xf0");

assert_eq!(queue.pop_char(), Some('a'));
assert_eq!(queue.pop_char(), None);
assert!(!queue.is_empty());

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

Pops the first character from the queue and returns it.

The trailing incomplete character is replaced with U+FFFD REPLACEMENT CHARACTER, if available.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"abc\xce");
let mut range = queue.chars_range(..);

assert_eq!(range.pop_char_replaced(), Some('a'));
assert_eq!(range.pop_char_replaced(), Some('b'));
assert_eq!(range.pop_char_replaced(), Some('c'));
assert_eq!(range.pop_char_replaced(), Some('\u{FFFD}'));
assert_eq!(range.pop_char_replaced(), None);

pub fn pop_line(&mut self) -> Option<PoppedLine<'_>>

Pops the first line in the queue and returns it.

Incomplete lines are ignored.

Note that it is unspecified whether the line will be removed from the queue, if the PoppedLine value is not dropped while the borrow it holds expires (e.g. due to core::mem::forget).

Examples

use str_queue::StrQueue;

// Note that the last "world\r" is not considered as a complete line
// since the line can be finally "world\r" or "world\r\n".
let mut queue = StrQueue::from("Hello\nworld\r\nGoodbye\rworld\r");

assert_eq!(queue.pop_line().map(|v| v.to_string()).as_deref(), Some("Hello\n"));
assert_eq!(queue.pop_line().map(|v| v.to_string()).as_deref(), Some("world\r\n"));
assert_eq!(queue.pop_line().map(|v| v.to_string()).as_deref(), Some("Goodbye\r"));
assert_eq!(queue.pop_line().map(|v| v.to_string()).as_deref(), None);
assert_eq!(queue.chars_range(..), "world\r");

pub fn pop_fragment(&mut self) -> Option<PoppedFragment<'_>>

Pops the first Fragment from the queue and return it.

In other words, takes as much content as possible from the queue.

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::from(b"Hello \xce");
let mut buf = String::new();

while let Some(frag) = queue.pop_fragment() {
    buf.push_str(&frag.to_string());
}

assert_eq!(buf, "Hello \u{FFFD}");
assert!(queue.is_empty());

impl StrQueue

Content access.

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

Returns the first character in the buffer.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from("hello");

assert_eq!(queue.first_char(), Some('h'));

pub fn first_line(&self) -> Option<CharsRange<'_>>

Returns the first complete line in the buffer.

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::from("hello");
// No complete line.
assert_eq!(queue.first_line(), None);

queue.push_bytes(b"\r");
// Still no complete line: "hello\r" is considered incomplete since
// it cannot be decided whether the line is "hello\r" or "hello\r\n".
assert_eq!(queue.first_line(), None);

queue.push_bytes(b"\n");
assert_eq!(
    queue.first_line().map(|line| line.to_string()).as_deref(),
    Some("hello\r\n")
);

impl StrQueue

Iterators.

pub fn into_chars(self, partial_handling: PartialHandling) -> IntoChars

Turns the queue into an iterator of the characters.

Examples

use str_queue::{PartialHandling, StrQueue};

let queue = StrQueue::from("alpha \u{03B1} beta \u{03B2}");

assert_eq!(
    queue.into_chars(PartialHandling::Emit).collect::<String>(),
    "alpha \u{03B1} beta \u{03B2}"
);

Trailing possibly invalid bytes (i.e. incomplete characters) can be replaced with U+FFFD REPLACEMENT CHARACTER, or be simply ignored.

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from(b"alpha->\xce");

// The trailing incomplete character is ignored.
assert_eq!(
    queue.clone().into_chars(PartialHandling::Ignore).collect::<String>(),
    "alpha->"
);
// The trailing incomplete character is replaced with U+FFFD.
assert_eq!(
    queue.into_chars(PartialHandling::Emit).collect::<String>(),
    "alpha->\u{FFFD}"
);

pub fn chars(&self, partial_handling: PartialHandling) -> Chars<'_>

Turns the queue into an iterator of the characters.

Examples

use str_queue::{PartialHandling, StrQueue};

let queue = StrQueue::from("alpha \u{03B1} beta \u{03B2}");

assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "alpha \u{03B1} beta \u{03B2}"
);

Trailing possibly invalid bytes (i.e. incomplete characters) can be replaced with U+FFFD REPLACEMENT CHARACTER, or be simply ignored.

use str_queue::{PartialHandling, StrQueue};

let mut queue = StrQueue::from(b"alpha->\xce");
// The trailing incomplete character is ignored.
assert_eq!(
    queue.chars(PartialHandling::Ignore).collect::<String>(),
    "alpha->"
);
// The trailing incomplete character is replaced with U+FFFD.
assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "alpha->\u{FFFD}"
);

queue.push_bytes(b"\xb1");
assert_eq!(
    queue.chars(PartialHandling::Emit).collect::<String>(),
    "alpha->\u{03B1}"
);

pub fn range_chars<R>( &self, range: R, partial_handling: PartialHandling, ) -> Chars<'_>

where R: RangeBounds<usize>,

Returns the chars iterator for the range.

Panics

Panics if the start index of the range does not lie on UTF-8 sequence boundary.

Examples

use str_queue::{Fragment, PartialHandling, StrQueue};

let queue = StrQueue::from("alpha\u{03B1}");

assert_eq!(
    queue.range_chars(3..6, PartialHandling::Emit).collect::<String>(),
    "ha\u{FFFD}"
);
assert_eq!(
    queue.range_chars(3..6, PartialHandling::Ignore).collect::<String>(),
    "ha"
);

pub fn fragments(&self, partial_handling: PartialHandling) -> Fragments<'_>

Returns an iterator of content fragments.

Examples

The code below are redundant since they are intended to show how to use Fragment. To simply create a string from the queue, use StrQueue::display method.

use str_queue::{Fragment, PartialHandling, StrQueue};

// Note that `\xce` can appear as a first byte of valid UTF-8 sequence.
let queue = StrQueue::from(b"hello \xce");

let mut buf = String::new();
for frag in queue.fragments(PartialHandling::Emit) {
    match frag {
        Fragment::Str(s) => buf.push_str(s),
        Fragment::Char(c) => buf.push(c),
        Fragment::Incomplete => buf.push_str("<<incomplete>>"),
    }
}
assert_eq!(buf, "hello <<incomplete>>");

When PartialHandling::Ignore is passed, Fragment::Incomplete won’t be emitted even if the queue contains trailing incomplete character.

use str_queue::{Fragment, PartialHandling, StrQueue};

// Note that `\xce` can appear as a first byte of valid UTF-8 sequence.
let queue = StrQueue::from(b"hello \xce");

let mut buf = String::new();
for frag in queue.fragments(PartialHandling::Ignore) {
    match frag {
        Fragment::Str(s) => buf.push_str(s),
        Fragment::Char(c) => buf.push(c),
        Fragment::Incomplete => unreachable!("`PartialHandling::Ignore` is specified"),
    }
}
assert_eq!(buf, "hello ");

Note that StrQueue will immediately replace non-incomplete invalid bytes (such as \xff and \xce\xff). Such already-replaced bytes will be printed as U+FFFD even if PartialHandling::Ignore is specified.

use str_queue::{Fragment, PartialHandling, StrQueue};

// Note that valid UTF-8 sequences can start with `\xf0`, but
// never start with `\xf0\xf0`.
// So, the first `\xf0` is immediately replaced with U+FFFD, and the
// second `\xf0` is considered as a prefix of an incomplete character.
let queue = StrQueue::from(b"hello \xf0\xf0");

let mut buf = String::new();
for frag in queue.fragments(PartialHandling::Emit) {
    match frag {
        Fragment::Str(s) => buf.push_str(s),
        Fragment::Char(c) => buf.push(c),
        Fragment::Incomplete => buf.push_str("<<incomplete>>"),
    }
}
assert_eq!(buf, "hello \u{FFFD}<<incomplete>>");

use str_queue::{Fragment, PartialHandling, StrQueue};

// Note that valid UTF-8 sequences can start with `\xf0`, but
// never start with `\xf0\xf0`.
// So, the first `\xf0` is immediately replaced with U+FFFD, and the
// second `\xf0` is considered as a prefix of an incomplete character.
let queue = StrQueue::from(b"hello \xf0\xf0");

let mut buf = String::new();
for frag in queue.fragments(PartialHandling::Ignore) {
    match frag {
        Fragment::Str(s) => buf.push_str(s),
        Fragment::Char(c) => buf.push(c),
        Fragment::Incomplete => unreachable!("`PartialHandling::Ignore` is specified"),
    }
}
// Note that the first `\xf0` is replaced with `U+FFFD`.
assert_eq!(buf, "hello \u{FFFD}");

pub fn range_fragments<R>( &self, range: R, partial_handling: PartialHandling, ) -> Fragments<'_>

where R: RangeBounds<usize>,

Returns the fragments iterator for the range.

Panics

Panics if the start index of the range does not lie on UTF-8 sequence boundary.

Examples

use str_queue::{Fragment, PartialHandling, StrQueue};

let queue = StrQueue::from("alpha\u{03B1}");

assert_eq!(
    queue.range_fragments(3..6, PartialHandling::Emit).to_string(),
    "ha\u{FFFD}"
);
assert_eq!(
    queue.range_fragments(3..6, PartialHandling::Ignore).to_string(),
    "ha"
);

pub fn display(&self, partial_handling: PartialHandling) -> Display<'_>

Returns an object that implements Display for printing the content.

Examples

use str_queue::StrQueue;
use str_queue::PartialHandling::{Emit, Ignore};

let mut queue = StrQueue::from(b"alpha->\xce");
assert_eq!(queue.display(Ignore).to_string(), "alpha->");
assert_eq!(queue.display(Emit).to_string(), "alpha->\u{FFFD}");

queue.push_bytes(b"\xb1");
assert_eq!(queue.display(Ignore).to_string(), "alpha->\u{03B1}");
assert_eq!(queue.display(Emit).to_string(), "alpha->\u{03B1}");

Trait Implementations

impl Clone for StrQueue

fn clone(&self) -> StrQueue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StrQueue

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

Formats the value using the given formatter.

impl Default for StrQueue

fn default() -> StrQueue

Returns the “default value” for a type.

impl From<&[u8]> for StrQueue

fn from(s: &[u8]) -> Self

Converts to this type from the input type.

impl<const N: usize> From<&[u8; N]> for StrQueue

fn from(s: &[u8; N]) -> Self

Converts to this type from the input type.

impl From<&str> for StrQueue

fn from(s: &str) -> Self

Converts to this type from the input type.

impl Hash for StrQueue

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.