StyledStr

Struct StyledStr 

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

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§

Source§

impl<'a> StyledStr<'a>

Source

pub const fn is_empty(&self) -> bool

Checks whether this string is empty.

Source

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());
Source

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

Returns the unstyled text.

Source

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.

Source

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[[/]]!"));
Source

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[[/]]!"));
Source

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")));
Source

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")));
Source

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")));
Source

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);
Source

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())
);
Source

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)");
Source

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);
Source

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"),
]);
Source

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);
Source

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"));
Source

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§

Source§

impl AddAssign<StyledStr<'_>> for StyledString

Source§

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

Performs the += operation. Read more
Source§

impl AddAssign<StyledStr<'_>> for StyledStringBuilder

Source§

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

Performs the += operation. Read more
Source§

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

Source§

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

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for StyledStr<'_>

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

fn default() -> StyledStr<'a>

Returns the “default value” for a type. Read more
Source§

impl Display for StyledStr<'_>

Outputs a string with rich syntax.

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

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

Extends a collection with the contents of an iterator. Read more
Source§

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)
Extends a collection with exactly one element.
Source§

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. Read more
Source§

impl<'a, T> From<StyledStr<'a>> for StyledString<T>
where T: From<&'a str> + Deref<Target = str>,

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Creates a value from an iterator. Read more
Source§

impl<T> PartialEq<StyledStr<'_>> for StyledString<T>
where T: Deref<Target = str>,

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl<T> PartialEq<StyledString<T>> for StyledStr<'_>
where T: Deref<Target = str>,

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

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

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

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

Source§

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

Auto Trait Implementations§

§

impl<'a> Freeze for StyledStr<'a>

§

impl<'a> RefUnwindSafe for StyledStr<'a>

§

impl<'a> Send for StyledStr<'a>

§

impl<'a> Sync for StyledStr<'a>

§

impl<'a> Unpin for StyledStr<'a>

§

impl<'a> UnwindSafe for StyledStr<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.