Struct StyledStr 

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

Borrowed ANSI-styled string.

A StyledStr instance consists of two parts:

• Original text (a &str).
• A sequence of styled spans covering the text.

StyledStr represents the borrowed string variant in contrast to StyledString, which is owned. A StyledStr can be parsed from rich syntax in compile time via the styled! macro, or borrowed from a string using StyledString::as_str().

Examples

See crate-level docs for the examples of usage.

Implementations

impl<'a> StyledStr<'a>

pub const fn is_empty(&self) -> bool

Checks whether this string is empty.

pub const fn is_plain(&self) -> bool

Checks whether this string is plain (doesn’t include non-default styled spans).

Examples

assert!(StyledStr::default().is_plain());
assert!(styled!("Hello").is_plain());
assert!(!styled!("[[green]]Hello").is_plain());

pub const fn text(&self) -> &'a str

Returns the unstyled text.

pub fn diff(self, other: Self) -> Result<(), Diff<'a>>

Diffs this against the other styled string.

Errors

Returns an error if the styled strings differ either in text, or in applied styles.

pub fn get(&self, range: impl RangeBounds<usize>) -> Option<Self>

Returns a slice of this string. This works similarly to str::get() and returns None under the same conditions.

Examples

let styled = styled!("[[green]]Hello, [[it]]world[[/]]!");
let slice = styled.get(3..=8).unwrap();
assert_eq!(slice, styled!("[[green]]lo, [[it]]wo"));

let slice = styled.get(10..).unwrap();
assert_eq!(slice, styled!("[[it]]ld[[/]]!"));

pub const fn split_at(self, mid: usize) -> (Self, Self)

Splits this string into two at the specified position.

Panics

Panics in the same situations as str::split_at().

Examples

let styled = styled!("[[green]]Hello, [[it]]world[[/]]!");
let (start, end) = styled.split_at(5);
assert_eq!(start, styled!("[[green]]Hello"));
assert_eq!(end, styled!("[[green]], [[it]]world[[/]]!"));

pub fn starts_with(&self, needle: StyledStr<'_>) -> bool

Checks whether this string starts with a needle, matching both its text and styling.

Examples

let styled = styled!("[[green]]Hello, [[* bold]]world");
assert!(styled.starts_with(styled!("[[green]]Hello")));
// Styling is taken into account
assert!(!styled.starts_with(styled!("Hello")));

pub fn ends_with(&self, needle: StyledStr<'_>) -> bool

Checks whether this string ends with a needle, matching both its text and styling.

Examples

let styled = styled!("[[green]]Hello, [[* bold]]world");
assert!(styled.ends_with(styled!("[[green bold]]ld")));
// Styling is taken into account
assert!(!styled.ends_with(styled!("world")));

pub fn contains(&self, needle: StyledStr<'_>) -> bool

Checks whether needle is contained in this string, matching both by text and styling.

Examples

let styled = styled!("[[green]]Hello, [[* bold]]world");
assert!(styled.contains(styled!("[[green]]lo, [[* bold]]w")));
assert!(!styled.contains(styled!("lo")));

pub fn find(&self, needle: StyledStr<'_>) -> Option<usize>

Finds the first byte position of needle in this string from the string start, matching both by text and styling.

Examples

let styled = styled!("[[green]]Hello, [[* bold]]world");
assert_eq!(
    styled.find(styled!("[[green]]lo, [[* bold]]w")),
    Some(3)
);
assert_eq!(styled.find(styled!("lo")), None);

pub fn spans( &self, ) -> impl ExactSizeIterator<Item = SpanStr<'a>> + DoubleEndedIterator + 'a

Iterates over spans contained in this string.

Examples

let styled = styled!("[[green]]Hello, [[* bold]]world");
let mut spans = styled.spans();
assert_eq!(spans.len(), 2);

assert_eq!(
    spans.next().unwrap(),
    SpanStr::new("Hello, ", AnsiColor::Green.on_default())
);
assert_eq!(
    spans.next().unwrap(),
    SpanStr::new("world", AnsiColor::Green.on_default().bold())
);

pub const fn span(&self, span_idx: usize) -> Option<SpanStr<'a>>

Returns a span by the span index.

Use Self::span_at() if you need to locate the span covering the specified position in the text.

Examples

let styled = styled!("[[bold blue!]]INFO[[/]] [[dim it]](2 min ago)[[/]] Important");
let span = styled.span(0).unwrap();
assert_eq!(span.text, "INFO");
assert_eq!(span.style.get_fg_color(), Some(AnsiColor::BrightBlue.into()));

let span = styled.span(2).unwrap();
assert_eq!(span.text, "(2 min ago)");

pub const fn span_at(&self, text_pos: usize) -> Option<SpanStr<'a>>

Looks up a span covering the specified position in the unstyled text.

Use Self::span() if you need to locate the span by its index.

Examples

let styled = styled!("[[bold blue!]]INFO[[/]] [[dim it]](2 min ago)[[/]] Important");
let span = styled.span_at(7).unwrap();
assert_eq!(span.text, "(2 min ago)");
assert_eq!(span.style.get_effects(), Effects::ITALIC | Effects::DIMMED);

pub fn lines(self) -> Lines<'a>

Splits this text by lines.

Examples

let styled = styled!("[[bold green!]]Hello,\n  :[[* -color]]world\n");
let lines: Vec<_> = styled.lines().collect();
assert_eq!(lines, [
    styled!("[[bold green!]]Hello,"),
    styled!("[[bold green!]]  :[[bold]]world"),
]);

pub fn ansi(&self) -> impl Display + '_

Returns a string with embedded ANSI escapes.

Examples

let styled = styled!("[[bold blue!]]INFO[[/]] [[dim it]](2 min ago)[[/]] Important");
let ansi_str = styled.ansi().to_string();
assert!(ansi_str.contains('\u{1b}'));

// The ANSI string can be parsed back via `from_ansi()`.
let restored = StyledString::from_ansi(&ansi_str)?;
assert_eq!(restored, styled);

pub fn pop(&mut self) -> Option<(char, Style)>

Pops a single char from the end of the string.

Examples

let mut styled = styled!("[[bold green!]]Hello[[it]]!❤");
let (ch, style) = styled.pop().unwrap();
assert_eq!(ch, '❤');
assert_eq!(style, Style::new().italic());
assert_eq!(styled, styled!("[[bold green!]]Hello[[it]]!"));

styled.pop().unwrap();
assert_eq!(styled, styled!("[[bold green!]]Hello"));

pub fn to_owned(self) -> StyledString

Converts this string to the owned variant.

Note that this shadows ToOwned::to_owned(), but this shouldn’t be an issue since StyledStr implements Copy.

Trait Implementations

impl AddAssign<StyledStr<'_>> for StyledStringBuilder

fn add_assign(&mut self, rhs: StyledStr<'_>)

Performs the += operation.

impl AddAssign<StyledStr<'_>> for StyledString

fn add_assign(&mut self, rhs: StyledStr<'_>)

Performs the += operation.

impl<'a> Clone for StyledStr<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for StyledStr<'a>

impl Debug for StyledStr<'_>

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

Formats the value using the given formatter.

impl<'a> Default for StyledStr<'a>

fn default() -> StyledStr<'a>

Returns the “default value” for a type.

impl Display for StyledStr<'_>

Outputs a string with rich syntax.

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

Formats the value using the given formatter.

impl<'a> Extend<StyledStr<'a>> for StyledString

fn extend<I: IntoIterator<Item = StyledStr<'a>>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, T> From<StyledStr<'a>> for StyledString<T>

where T: From<&'a str> + Deref<Target = str>,

fn from(str: StyledStr<'a>) -> Self

Converts to this type from the input type.

impl<'a> FromIterator<StyledStr<'a>> for StyledString

fn from_iter<I: IntoIterator<Item = StyledStr<'a>>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> PartialEq for StyledStr<'a>

fn eq(&self, other: &StyledStr<'a>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T> PartialEq<StyledStr<'_>> for StyledString<T>

where T: Deref<Target = str>,

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

Equality operator ==.

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

Inequality operator !=.

impl<T> PartialEq<StyledString<T>> for StyledStr<'_>

where T: Deref<Target = str>,

fn eq(&self, other: &StyledString<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<'a> StructuralPartialEq for StyledStr<'a>