Struct term_string::TermString

pub struct TermString { /* fields omitted */ }

A string type with term styling info attached to it.

Internally, TermString contains multiple strings, each one of them has a TermStyle attached to it.

Methods

impl TermString

Basic methods for constructing and modifying TermStrings,

pub fn new<S>(style: TermStyle, text: S) -> Self where     S: Borrow<str>,

Create a TermString variable from a TermStyle and a string value.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");
ts.println();

pub fn len(&self) -> usize

Return the length of the un-styled string contained in TermString.

Examples

let bold = TermStyle::bold();
let underline = TermStyle::underline(true);
let mut ts = TermString::new(bold, "some bold text ");
ts += TermString::new(underline, "and some underlined text.");
assert_eq!(ts.len(), 40);

pub fn is_empty(&self) -> bool

Return true if the un-styled string contained in TermString is empty.

Examples

let bold = TermStyle::bold();
let mut ts = TermString::new(bold, "");
assert!(ts.is_empty());
ts += "this is bold."

pub fn as_string(&self) -> String

Return the un-styled string contained in TermString.

Examples

let bold = TermStyle::bold();
let underline = TermStyle::underline(true);
let mut ts = TermString::new(bold, "some bold text ");
ts += TermString::new(underline, "and some underlined text.");
let s = "some bold text and some underlined text.";
assert_eq!(ts.as_string(), s);

pub fn append_str<S>(&mut self, text: S) where     S: Borrow<str>,

Append a string value to a TermString, inheriting the previous style.

Examples

let bold = TermStyle::bold();
let mut ts = TermString::new(bold, "some bold text ");
ts.append_str("and other bold text");
ts.println();

Note that the line:

ts.append_str("and other bold text");

is equivalent to:

ts += "and other bold text";

pub fn append_term_str<IS>(&mut self, other: IS) where     IS: Into<Self>,

Append a TermString to a TermString.

Examples

let bold = TermStyle::bold();
let underline = TermStyle::underline(true);
let mut ts = TermString::new(bold, "some bold text ");
let ts2 = TermString::new(underline, "and some underlined text.");
ts.append_term_str(ts2);
ts.println();

Note that the line:

ts.append_term_str(ts2);

is equivalent to:

ts += ts2;

Also note that the method's argument type is Into<Self>, and From<S> for TermString where S: Borrow<str> is implemented.

So, this works:

let bold = TermStyle::bold();
let mut ts = TermString::new(bold, "some bold text ");
ts.append_term_str("and some un-styled text.");
ts.println();

Note that the method argument in the example above is converted into a TermString with a Default style first before appending. Contrast this with the behavior of append_str(), where the appended value inherits the previous style.

So, the line:

ts.append_term_str("and some un-styled text.");

is equivalent to:

ts += TermString::from("and some un-styled text.");

which in turn is equivalent to:

ts += TermString::new(TermStyle::default(), "and some un-styled text.");

pub fn append<IS>(&mut self, other: IS) where     IS: Into<Self>,

This is effectively an alias to append_term_str()

pub fn with_appended_str<S>(self, text: S) -> Self where     S: Borrow<str>,

The chaining equivalent of append_str().

pub fn with_appended_term_str<IS>(self, other: IS) -> Self where     IS: Into<Self>,

The chaining equivalent of append_term_str().

pub fn with_appended<IS>(self, other: IS) -> Self where     IS: Into<Self>,

The chaining equivalent of append().

impl TermString

Method for modifying the style of all internal elements of a TermString.

A corresponding method from TermStyle is used on each internal element of the TermString.

Remember that TermStyle is a Copy type.

pub fn set_style<IT>(&mut self, style: IT) where     IT: Into<TermStyle>,

Set the styles of all internal elements of the TermString to this style.

Examples

use term_string::{TermString, TermStyle, color};

let fg_bg = TermStyle::bg(color::RED) + TermStyle::fg(color::WHITE);
let underline = TermStyle::underline(true);

let mut ts = TermString::new(fg_bg, "fg bg");
ts += TermString::new(underline, " underline");

ts.set_style(TermStyle::bold());

// This will print "fg bg underline" in bold and without
// foreground or background colors or underline.
ts.println();

pub fn with_set_style<IT>(self, style: IT) -> Self where     IT: Into<TermStyle>,

The chaining equivalent of set_style().

pub fn reset_style(&mut self)

Reset the styles of all internal elements of the TermString.

Examples

use term_string::{TermString, TermStyle, color};

let fg_bg = TermStyle::bg(color::RED) + TermStyle::fg(color::WHITE);
let underline = TermStyle::underline(true);

let mut ts = TermString::new(fg_bg, "fg bg");
ts += TermString::new(underline, " underline");

ts.reset_style();

// This will print "fg bg underline" without any styling
ts.println();

pub fn with_reset_style(self) -> Self

The chaining equivalent of reset_style().

pub fn or_style<IT>(&mut self, style: IT) where     IT: Into<TermStyle>,

Calls TermStyle::or_style() on each internal element of the TermString.

Examples

use term_string::{TermString, TermStyle, color};

let fg_bg = TermStyle::bg(color::RED) + TermStyle::fg(color::WHITE);
let underline = TermStyle::underline(true);

let mut ts = TermString::new(fg_bg, "fg bg");
ts += TermString::new(underline, " underline");

ts.or_style(TermStyle::bg(color::BLUE));

// This will print "fg bg" with red background and white foreground,
// then " underline" with underline and blue background.
ts.println();

pub fn with_ored_style<IT>(self, style: IT) -> Self where     IT: Into<TermStyle>,

The chaining equivalent of or_style().

pub fn add_style<IT>(&mut self, style: IT) where     IT: Into<TermStyle>,

Calls TermStyle::add_style() on each internal element of the TermString.

Examples

use term_string::{TermString, TermStyle, color};

let fg_bg = TermStyle::bg(color::RED) + TermStyle::fg(color::WHITE);
let underline = TermStyle::underline(true);

let mut ts = TermString::new(fg_bg, "fg bg");
ts += TermString::new(underline, " underline");

ts.add_style(TermStyle::bg(color::BLUE));

// This will print "fg bg" with blue background and white foreground,
// then " underline" with underline and blue background.
ts.println();

pub fn with_style<IT>(self, style: IT) -> Self where     IT: Into<TermStyle>,

The chaining equivalent of add_style().

impl TermString

IO write/print methods

Note

TermWrite is bound to Write + Send on Windows, and only Write on other platforms.

pub fn write_plain<W: TermWrite>(&self, out: W)

Write TermString to out without styling.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stdout without
// any formatting, so not really bold.
ts.write_plain(std::io::stdout());

pub fn write_styled<W: TermWrite>(&self, out: W)

Write TermString to out with styling.

Note

• out doesn't have to be an actual tty.
• If on Windows, and getting terminfo fails, the styling info will be set on the current console, regardless of what out is.

Check out print(), println(), eprint(), and eprintln() below, where out is checked before styled output is written to it.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stdout with formatting,
// even if stdout is not a tty
ts.write_styled(std::io::stdout());

pub fn print_plain(&self)

Write TermString to stdout without styling.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to `stdout` without
// any formatting, so not really bold.
ts.print_plain();

pub fn print_styled(&self)

Print TermString to stdout with styling.

Note

stdout doesn't have to be an actual tty.

Check out print() below, where stdout is checked before styled output is printed.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stdout
// as bold text.
ts.print_styled();

pub fn print(&self)

Print TermString to stdout with styling if stdout is a tty, and without if it's not.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stdout as bold
// text if stdout is a tty, and without any formatting if not.
ts.print();

pub fn println_plain(&self)

The same as print_plain(), but with a newline printed at the end.

pub fn println_styled(&self)

The same as print_styled(), but with a newline printed at the end.

pub fn println(&self)

The same as print(), but with a newline printed at the end.

pub fn eprint_plain(&self)

Write TermString to stderr without styling.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to `stderr` without
// any formatting, so not really bold.
ts.eprint_plain();

pub fn eprint_styled(&self)

Print TermString to stderr with styling.

Note

stderr doesn't have to be an actual tty.

Check out eprint() below, where stderr is checked before styled output is printed.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stderr
// as bold text.
ts.eprint_styled();

pub fn eprint(&self)

Print TermString to stderr with styling if stderr is a tty, and without if it's not.

Examples

let bold = TermStyle::bold();
let ts = TermString::new(bold, "some bold text");

// This will write "some bold text" to stderr as bold
// text if stderr is a tty, and without any formatting if not.
ts.eprint();

pub fn eprintln_plain(&self)

The same as eprint_plain(), but with a newline printed at the end.

pub fn eprintln_styled(&self)

The same as eprint_styled(), but with a newline printed at the end.

pub fn eprintln(&self)

The same as eprint(), but with a newline printed at the end.

Trait Implementations

impl Clone for TermString

fn clone(&self) -> TermString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for TermString

fn default() -> TermString

Returns the "default value" for a type.

impl Debug for TermString

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

Formats the value using the given formatter.

impl<S> From<S> for TermString where     S: Borrow<str>,

fn from(s: S) -> Self

Performs the conversion.

impl<S> Add<S> for TermString where     S: Borrow<str>,

type Output = Self

The resulting type after applying the + operator.

fn add(self, text: S) -> Self

Performs the + operation.

impl<S> AddAssign<S> for TermString where     S: Borrow<str>,

fn add_assign(&mut self, text: S)

Performs the += operation.

impl Add for TermString

type Output = Self

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for TermString

fn add_assign(&mut self, other: Self)

Performs the += operation.