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>
impl<'a> StyledStr<'a>
Sourcepub const fn is_plain(&self) -> bool
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());Sourcepub fn diff(self, other: Self) -> Result<(), Diff<'a>>
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.
Sourcepub fn get(&self, range: impl RangeBounds<usize>) -> Option<Self>
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[[/]]!"));Sourcepub const fn split_at(self, mid: usize) -> (Self, Self)
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[[/]]!"));Sourcepub fn starts_with(&self, needle: StyledStr<'_>) -> bool
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")));Sourcepub fn ends_with(&self, needle: StyledStr<'_>) -> bool
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")));Sourcepub fn contains(&self, needle: StyledStr<'_>) -> bool
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")));Sourcepub fn find(&self, needle: StyledStr<'_>) -> Option<usize>
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);Sourcepub fn spans(
&self,
) -> impl ExactSizeIterator<Item = SpanStr<'a>> + DoubleEndedIterator + 'a
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())
);Sourcepub const fn span(&self, span_idx: usize) -> Option<SpanStr<'a>>
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)");Sourcepub const fn span_at(&self, text_pos: usize) -> Option<SpanStr<'a>>
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);Sourcepub fn lines(self) -> Lines<'a> ⓘ
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"),
]);Sourcepub fn ansi(&self) -> impl Display + '_
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);Sourcepub fn pop(&mut self) -> Option<(char, Style)>
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"));Sourcepub fn to_owned(self) -> StyledString
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
impl AddAssign<StyledStr<'_>> for StyledString
Source§fn add_assign(&mut self, rhs: StyledStr<'_>)
fn add_assign(&mut self, rhs: StyledStr<'_>)
+= operation. Read moreSource§impl AddAssign<StyledStr<'_>> for StyledStringBuilder
impl AddAssign<StyledStr<'_>> for StyledStringBuilder
Source§fn add_assign(&mut self, rhs: StyledStr<'_>)
fn add_assign(&mut self, rhs: StyledStr<'_>)
+= operation. Read moreSource§impl<'a> Extend<StyledStr<'a>> for StyledString
impl<'a> Extend<StyledStr<'a>> for StyledString
Source§fn extend<I: IntoIterator<Item = StyledStr<'a>>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = StyledStr<'a>>>(&mut self, iter: I)
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one)