Struct CharsRange

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

Subrange of a StrQueue.

This can be created by StrQueue::chars_range.

The range contains valid UTF-8 sequence with the optional last incomplete character.

Implementations

impl<'a> CharsRange<'a>

Subrange access.

pub fn range<R>(&self, range: R) -> Self

where R: RangeBounds<usize>,

Returns the subrange.

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. Panics if the given index is out of range.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"Hello \xce\xb1");
let range = queue.chars_range(..);
assert_eq!(range.to_string(), "Hello \u{03B1}");

assert_eq!(range.range(3..7).to_string(), "lo \u{FFFD}");

pub fn to_complete(self) -> Self

Returns the range without the last incomplete character.

If you want to modify self instead of getting a modified copy, use CharsRange::trim_last_incomplete_char.

Examples

use str_queue::{PartialHandling, StrQueue};

let queue = StrQueue::from(b"Hello \xce");
let range = queue.chars_range(..);
assert_eq!(range.to_string(), "Hello \u{FFFD}");
assert_eq!(range.to_complete().to_string(), "Hello ");

impl<'a> CharsRange<'a>

Content length and existence.

pub fn len(&self) -> usize

Returns the total length.

Examples

use str_queue::StrQueue;

let queue = StrQueue::from(b"Hello \xce");
let range = queue.chars_range(..);
assert_eq!(range.len(), b"Hello \xce".len());

pub fn is_empty(&self) -> bool

Returns true if the range is empty.

Examples

use str_queue::StrQueue;

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

assert!(queue.chars_range(0..0).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.chars_range(..).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.chars_range(..).len_incomplete(), 1);

pub fn is_empty_complete(&self) -> bool

Returns true if the chars range contains no complete string.

Examples

use str_queue::StrQueue;

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

queue.push_bytes(b"\xce");
assert!(queue.chars_range(..).is_empty_complete());

queue.push_bytes(b"\xb1");
assert!(!queue.chars_range(..).is_empty_complete());

pub fn is_complete(&self) -> bool

Returns true if the chars range 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.chars_range(..).is_complete());
queue.push_bytes(b"\xb1");
// Now the string is "abc\u{03B1}".
assert!(queue.chars_range(..).is_complete());

impl<'a> CharsRange<'a>

Range and content manipulation.

pub fn clear(&mut self)

Clears the range, removing all elements.

Examples

use str_queue::{PartialHandling, StrQueue};

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

range.clear();
assert!(range.is_empty());
// Only the range is cleared. The underlying queue does not change.
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 queue = StrQueue::from(b"Hello \xce");
let mut range = queue.chars_range(..);
assert_eq!(range.to_string(), "Hello \u{FFFD}");

range.trim_last_incomplete_char();
assert_eq!(range.to_string(), "Hello ");

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

Pops the first character in the range and returns it.

Trailing incomplete character is ignored.

Examples

use str_queue::StrQueue;

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

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

use str_queue::StrQueue;

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

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

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

Pops the first character from the range 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}'));

pub fn pop_line<'r>(&'r mut self) -> Option<CharsRangePoppedLine<'a, 'r>>

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 queue = StrQueue::from("Hello\nworld\r\nGoodbye\rworld\r");
let mut range = queue.chars_range(..);

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

pub fn pop_fragment(&mut self) -> Option<Fragment<'a>>

Pops the first Fragment from the range and return it.

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

Examples

use str_queue::StrQueue;

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

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

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

impl<'a> CharsRange<'a>

Content access.

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

Returns the first character in the range.

Examples

use str_queue::StrQueue;

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

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

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

Returns the subrange of the first line, including the line break.

Returns Some(range) if the range contains a complete line, which won’t be changed if more contents are appended. Returns None if the range contains only an incomplete line, which will be changed if more contents are appended.

Examples

use str_queue::StrQueue;

let mut queue = StrQueue::from(b"Hello \xce");
assert_eq!(
    queue.chars_range(..).first_line().map(|r| r.to_string()),
    None
);

queue.push_bytes(b"\xb1\r");
// The line is still considered incomplete since the line ending can be `\r\n`.
assert_eq!(
    queue.chars_range(..).first_line().map(|r| r.to_string()),
    None
);

queue.push_bytes(b"\nhello");
assert_eq!(
    queue.chars_range(..).first_line().map(|r| r.to_string()),
    Some("Hello \u{03B1}\r\n".to_owned())
);

use str_queue::{PartialHandling, StrQueue};

let queue = StrQueue::from(b"Hello\n");
assert_eq!(
    queue.chars_range(..).first_line().map(|r| r.to_string()),
    Some("Hello\n".to_owned())
);

impl<'a> CharsRange<'a>

Iterators.

pub fn chars(&self) -> Chars<'_>

Returns an iterator of chars.

Incomplete characters are emitted as U+FFFD REPLACEMENT CHARACTER. If you want to ignore them, use CharsRange::to_complete or CharsRange::trim_last_incomplete_char before creating the iterator.

Examples

use str_queue::{PartialHandling, StrQueue};

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

// The trailing incomplete character is replaced with U+FFFD.
assert_eq!(
    range.chars().collect::<String>(),
    "alpha->\u{FFFD}"
);

pub fn fragments(&self) -> 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, StrQueue};

// `\xce\xb1` is `\u{03B1}`.
let queue = StrQueue::from(b"hello \xce\xb1");
let range = queue.chars_range(3..7);

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

impl<'a> CharsRange<'a>

Conversion.

pub fn to_bytes_range(&self) -> BytesRange<'a>

Returns the bytes range.

Trait Implementations

impl<'a> Clone for CharsRange<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for CharsRange<'a>

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

Formats the value using the given formatter.

impl Display for CharsRange<'_>

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

Formats the value using the given formatter.

impl<'a> From<CharsRange<'a>> for BytesRange<'a>

fn from(v: CharsRange<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<CharsRange<'a>> for Fragments<'a>

fn from(range: CharsRange<'a>) -> Self

Converts to this type from the input type.

impl<'a> Hash for CharsRange<'a>

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.

impl Ord for CharsRange<'_>

fn cmp(&self, rhs: &Self) -> Ordering

This comparson is arawe of the existence of the last incomplete characters, but does not aware of its value. If you care about the value of the incomplete characters, you should use bytes comparison.

If the range has the incomplete character, it is treated as a character which is smaller than any other characters. In other words, the comparison result can be thought as (lhs.complete(), !lhs.is_complete()).cmp(&(rhs.complete(), !rhs.is_complete())).

Examples

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue_ce = StrQueue::from(b"Hello\xce");
let range_ce = queue_ce.chars_range(..);
let queue_f0 = StrQueue::from(b"Hello\xf0");
let range_f0 = queue_f0.chars_range(..);

// Bytes for incomplete characters are considered the same.
assert_eq!(range_ce, range_f0);
assert_eq!(range_ce.cmp(&range_f0), Ordering::Equal);
// To distinguish incomplete characters, use bytes range.
assert_ne!(range_ce.to_bytes_range(), range_f0.to_bytes_range());
assert_eq!(
    range_ce.to_bytes_range().cmp(&range_f0.to_bytes_range()),
    Ordering::Less
);

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue_ce = StrQueue::from(b"Hello\xce");
let range_ce = queue_ce.chars_range(..);

let queue_none = StrQueue::from(b"Hello");
let range_none = queue_none.chars_range(..);
assert_ne!(range_ce, range_none);
assert_eq!(range_ce.partial_cmp(&range_none), Some(Ordering::Greater));

let queue_00 = StrQueue::from(b"Hello\x00");
let range_00 = queue_00.chars_range(..);
assert_ne!(range_ce, range_00);
// `\xce` is incomplete, so it is considered smaller than `\x00`.
// Note that `\x00` is a valid ASCII character.
assert_eq!(range_ce.partial_cmp(&range_00), Some(Ordering::Less));

let queue_ufffd = StrQueue::from("Hello\u{FFFD}");
let range_ufffd = queue_ufffd.chars_range(..);
assert_ne!(range_ce, range_ufffd);
// The incomplete character (which consists of `\xce`) is converted to
// `\u{FFFD}` when displayed, but it is not considered to be the same
// as a valid Unicode character `\u{FFFD}`.
assert_eq!(range_ce.partial_cmp(&range_ufffd), Some(Ordering::Less));

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&str> for CharsRange<'_>

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<CharsRange<'_>> for &str

fn eq(&self, other: &CharsRange<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<CharsRange<'_>> for str

fn eq(&self, other: &CharsRange<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for CharsRange<'_>

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for CharsRange<'_>

fn eq(&self, other: &Self) -> bool

Compares the two chars ranges and returns true if they are equal.

This comparson is arawe of the existence of the last incomplete characters, but does not aware of its value. If you care about the value of the incomplete characters, you should use bytes comparison.

Examples

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue1 = StrQueue::from(b"Hello\xce");
let range1 = queue1.chars_range(..);
let queue2 = StrQueue::from(b"Hello\xf0");
let range2 = queue2.chars_range(..);

assert_eq!(range1, range2);
assert_ne!(range1.to_bytes_range(), range2.to_bytes_range());

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&str> for CharsRange<'_>

fn partial_cmp(&self, rhs: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<CharsRange<'_>> for &str

fn partial_cmp(&self, rhs: &CharsRange<'_>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<CharsRange<'_>> for str

fn partial_cmp(&self, rhs: &CharsRange<'_>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<str> for CharsRange<'_>

fn partial_cmp(&self, rhs: &str) -> Option<Ordering>

Compares the chars range and a string slice.

If the range has the incomplete character, it is treated as a character which is smaller than any other characters. In other words, the comparison result can be thought as (range.complete(), !range.is_complete()).cmp(&(rhs, false)). The complete part differ from the rhs string slice, that result is returned regardless of the incomplete character.

Examples

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue_00 = StrQueue::from(b"Hello\x00");
let range_00 = queue_00.chars_range(..);
let queue_ce = StrQueue::from(b"Hello\xce");
let range_ce = queue_ce.chars_range(..);

assert_eq!(range_00, "Hello\u{0}");
assert_eq!(range_00.partial_cmp("Hello\u{0}"), Some(Ordering::Equal));

assert_eq!(range_ce.partial_cmp("Hello"), Some(Ordering::Greater));
// `\xce` is incomplete, so it is considered smaller than `\x00`.
// Note that `\x00` is a valid ASCII character.
assert_eq!(range_ce.partial_cmp("Hello\u{0}"), Some(Ordering::Less));
// The incomplete character (which consists of `\xce`) is converted to
// `\u{FFFD}` when displayed, but it is not considered to be the same
// as a valid Unicode character `\u{FFFD}`.
assert_eq!(range_ce.partial_cmp("Hello\u{FFFD}"), Some(Ordering::Less));

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for CharsRange<'_>

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

Compares the two chars ranges.

This comparson is arawe of the existence of the last incomplete characters, but does not aware of its value. If you care about the value of the incomplete characters, you should use bytes comparison.

If the range has the incomplete character, it is treated as a character which is smaller than any other characters. In other words, the comparison result can be thought as (lhs.complete(), !lhs.is_complete()).cmp(&(rhs.complete(), !rhs.is_complete())).

Examples

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue_ce = StrQueue::from(b"Hello\xce");
let range_ce = queue_ce.chars_range(..);
let queue_f0 = StrQueue::from(b"Hello\xf0");
let range_f0 = queue_f0.chars_range(..);

// Bytes for incomplete characters are considered the same.
assert_eq!(range_ce, range_f0);
assert_eq!(range_ce.cmp(&range_f0), Ordering::Equal);
// To distinguish incomplete characters, use bytes range.
assert_ne!(range_ce.to_bytes_range(), range_f0.to_bytes_range());
assert_eq!(
    range_ce.to_bytes_range().cmp(&range_f0.to_bytes_range()),
    Ordering::Less
);

use str_queue::{PartialHandling, StrQueue};
use core::cmp::Ordering;

let queue_ce = StrQueue::from(b"Hello\xce");
let range_ce = queue_ce.chars_range(..);

let queue_none = StrQueue::from(b"Hello");
let range_none = queue_none.chars_range(..);
assert_ne!(range_ce, range_none);
assert_eq!(range_ce.partial_cmp(&range_none), Some(Ordering::Greater));

let queue_00 = StrQueue::from(b"Hello\x00");
let range_00 = queue_00.chars_range(..);
assert_ne!(range_ce, range_00);
// `\xce` is incomplete, so it is considered smaller than `\x00`.
// Note that `\x00` is a valid ASCII character.
assert_eq!(range_ce.partial_cmp(&range_00), Some(Ordering::Less));

let queue_ufffd = StrQueue::from("Hello\u{FFFD}");
let range_ufffd = queue_ufffd.chars_range(..);
assert_ne!(range_ce, range_ufffd);
// The incomplete character (which consists of `\xce`) is converted to
// `\u{FFFD}` when displayed, but it is not considered to be the same
// as a valid Unicode character `\u{FFFD}`.
assert_eq!(range_ce.partial_cmp(&range_ufffd), Some(Ordering::Less));

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> Copy for CharsRange<'a>

impl<'a> Eq for CharsRange<'a>