anstream

https://docs.rs/anstream/latest/anstream/
Admin
anstream is an auto-adapting Rust library for standard output and standard error streams that...
Tokens:6,609
Snippets:95
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Using the panic macro

Source: https://docs.rs/anstream/latest/anstream/macro.panic.html

Examples showing basic usage, simple string messages, and formatted messages.

```rust
use anstream::panic;
panic!();
panic!("this is a terrible mistake!");
panic!("this is a {} {message}", "fancy", message = "message");
```

--------------------------------

### Basic println Usage

Source: https://docs.rs/anstream/latest/anstream/macro.println.html

Examples of printing newlines, static strings, and formatted arguments using the println! macro.

```rust
use anstream::println;

println!(); // prints just a newline
println!("hello there!");
println!("format {} arguments", "some");
let local_variable = "some";
println!("format {local_variable} arguments");
```

--------------------------------

### Get ANSI-compatible stdout

Source: https://docs.rs/anstream/latest/anstream/fn.stdout.html

Returns an Stdout handle. Requires the 'auto' feature flag.

```rust
pub fn stdout() -> Stdout
```

--------------------------------

### Get ANSI-compatible stderr

Source: https://docs.rs/anstream/latest/anstream/fn.stderr.html

Returns an ANSI escape code compatible stderr. Requires the 'auto' feature flag.

```rust
pub fn stderr() -> Stderr
```

--------------------------------

### Print styled text with anstream

Source: https://docs.rs/anstream/latest/anstream/index.html

Demonstrates using anstream's println macro alongside owo-colors to apply foreground and background colors to output.

```rust
use anstream::println;
use owo_colors::OwoColorize as _;

// Foreground colors
println!("My number is {:#x}!", 10.green());
// Background colors
println!("My number is not {}!", 4.on_red());
```

--------------------------------

### StripBytes::new

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StripBytes.html

Creates a new instance of StripBytes in its initial state.

```APIDOC
## pub fn new() -> Self

### Description
Initializes a new StripBytes instance.

### Returns
- **Self** - A new instance of StripBytes.
```

--------------------------------

### AutoStream::new

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Creates a new AutoStream with explicit runtime control over styling behavior.

```APIDOC
## pub fn new(raw: S, choice: ColorChoice) -> Self

### Description
Creates a new AutoStream instance that wraps a raw stream with a specified ColorChoice.

### Parameters
- **raw** (S) - The underlying stream implementing RawStream.
- **choice** (ColorChoice) - The styling behavior to apply.
```

--------------------------------

### Using the print Macro

Source: https://docs.rs/anstream/latest/anstream/macro.print.html

Basic usage of the print macro, including flushing the output stream.

```rust
use std::io::Write as _;
use anstream::print;
use anstream::stdout;

print!("this ");
print!("will ");
print!("be ");
print!("on ");
print!("the ");
print!("same ");
print!("line ");

stdout().flush().unwrap();

print!("this string has a newline, why not choose println! instead?\n");

stdout().flush().unwrap();
```

--------------------------------

### Define custom color choice logic

Source: https://docs.rs/anstream/latest/anstream/type.Stderr.html

Demonstrates how to manually determine color output behavior for a stream, similar to AutoStream::choice but without specific environment variable overrides.

```rust
// Like `AutoStream::choice` but without `NO_COLOR`, `CLICOLOR_FORCE`, `CI`
fn choice(raw: &dyn anstream::stream::RawStream) -> anstream::ColorChoice {
    let choice = anstream::ColorChoice::global();
    if choice == anstream::ColorChoice::Auto {
        if raw.is_terminal() && anstyle_query::term_supports_color() {
            anstream::ColorChoice::Always
        } else {
            anstream::ColorChoice::Never
        }
    } else {
        choice
    }
}

let stream = std::io::stdout();
let choice = choice(&stream);
let auto = anstream::AutoStream::new(stream, choice);
```

--------------------------------

### println Macro Definition

Source: https://docs.rs/anstream/latest/anstream/macro.println.html

The signature of the println! macro.

```rust
macro_rules! println {
    () => { ... };
    ($($arg:tt)*) => { ... };
}
```

--------------------------------

### println!

Source: https://docs.rs/anstream/latest/anstream/macro.println.html

Prints to stdout with a newline. This macro uses the same syntax as format! and is available when the 'auto' feature is enabled.

```APIDOC
## println!

### Description
Prints to `stdout`, with a newline. On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone. This macro uses the same syntax as `format!`.

### Signature
`macro_rules! println { () => { ... }; ($($arg:tt)*) => { ... }; }`

### Notes
- **Feature Flag**: Available on crate feature `auto` only.
- **Performance**: The macro locks standard output on each call. For hot loops, consider locking stdout manually with `AutoStream::lock`.
- **Usage**: Use for primary program output; use `eprintln!` for error or progress messages.

### Panics
Panics if writing to `stdout` fails for any reason except a broken pipe. Writing to non-blocking stdout can cause an error, leading to a panic.

### Example
```rust
use anstream::println;

println!(); // prints just a newline
println!("hello there!");
println!("format {} arguments", "some");
let local_variable = "some";
println!("format {local_variable} arguments");
```
```

--------------------------------

### StripStream::new

Source: https://docs.rs/anstream/latest/anstream/struct.StripStream.html

Creates a new StripStream instance that wraps the provided writer.

```APIDOC
## pub fn new<S>(raw: S) -> StripStream<S>

### Description
Creates a new `StripStream` that wraps the given `raw` writer. Only printable data will be passed to the inner writer.

### Parameters
- **raw** (S) - The writer to wrap (must implement `std::io::Write`).
```

--------------------------------

### Using the eprint Macro

Source: https://docs.rs/anstream/latest/anstream/macro.eprint.html

Basic usage of the eprint macro to output error messages to stderr.

```rust
use anstream::eprint;

eprint!("Error: Could not complete task");
```

--------------------------------

### eprint!

Source: https://docs.rs/anstream/latest/anstream/macro.eprint.html

Prints to stderr. Equivalent to the print! macro, except that output goes to stderr instead of stdout. Use only for error and progress messages.

```APIDOC
## eprint!

### Description
Prints to `stderr`. Equivalent to the `print!` macro, except that output goes to `stderr` instead of `stdout`.

### Usage
`eprint!($($arg:tt)*)`

### Notes
- Available on crate feature `auto` only.
- Not all `eprint!` calls will be captured in tests like `std::eprint!`.
- Panics if writing to `stderr` fails for any reason except broken pipe.

### Example
```rust
use anstream::eprint;

eprint!("Error: Could not complete task");
```
```

--------------------------------

### eprintln!

Source: https://docs.rs/anstream/latest/anstream/macro.eprintln.html

Prints to stderr with a newline. This macro is equivalent to println! but outputs to stderr instead of stdout. It is intended for error and progress messages.

```APIDOC
## eprintln!

### Description
Prints to `stderr`, with a newline. Equivalent to the `println!` macro, except that output goes to `stderr` instead of `stdout`.

### Usage
`eprintln!()`
`eprintln!($($arg:tt)*)`

### Requirements
- Available on crate feature `auto` only.

### Notes
- Use `eprintln!` only for error and progress messages.
- Not all `eprintln!` calls will be captured in tests like `std::eprintln!` unless the `test` feature is enabled or in test binaries.

### Panics
Panics if writing to `stderr` fails for any reason except broken pipe. Writing to non-blocking stdout can cause an error, which will lead this macro to panic.

### Example
```rust
use anstream::eprintln;

eprintln!("Error: Could not complete task");
```
```

--------------------------------

### println! macro

Source: https://docs.rs/anstream/latest/anstream/index.html

Prints to stdout, automatically adapting ANSI escape codes to the terminal's capabilities.

```APIDOC
## println!

### Description
Prints to stdout, with a newline, while automatically handling ANSI escape code adaptation.

### Usage
```rust
use anstream::println;
println!("Hello, world!");
```
```

--------------------------------

### print!

Source: https://docs.rs/anstream/latest/anstream/macro.print.html

Prints to stdout without a trailing newline. Equivalent to the standard println! macro but without the newline character.

```APIDOC
## print!

### Description
Prints to `stdout`. Equivalent to the `println!` macro except that a newline is not printed at the end of the message.

### Usage
`print!($($arg:tt)*)`

### Notes
- Requires `auto` feature.
- `stdout` is frequently line-buffered; use `std::io::Write::flush()` to ensure immediate emission.
- The macro locks `stdout` on each call; for hot loops, consider locking `AutoStream` manually.
- Use `eprint!` for error and progress messages.

### Panics
Panics if writing to `stdout` fails for any reason except broken pipe. Writing to non-blocking `stdout` can cause an error, leading to a panic.

### Example
```rust
use std::io::Write as _;
use anstream::print;
use anstream::stdout;

print!("this ");
print!("will ");
print!("be ");
print!("on ");
print!("the ");
print!("same ");
print!("line ");

stdout().flush().unwrap();
```
```

--------------------------------

### AutoStream::never

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Disables color output.

```APIDOC
## pub fn never(raw: S) -> Self

### Description
Only passes printable data to the inner Write, stripping all color/styling.
```

--------------------------------

### eprintln Macro Definition

Source: https://docs.rs/anstream/latest/anstream/macro.eprintln.html

The macro signature for eprintln as defined in the anstream crate.

```rust
macro_rules! eprintln {
    () => { ... };
    ($($arg:tt)*) => { ... };
}
```

--------------------------------

### AutoStream::always

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Forces color output.

```APIDOC
## pub fn always(raw: S) -> Self

### Description
Forces color output, ignoring the inner Write's capabilities.
```

--------------------------------

### print Macro Definition

Source: https://docs.rs/anstream/latest/anstream/macro.print.html

The signature of the print macro.

```rust
macro_rules! print {
    ($($arg:tt)*) => { ... };
}
```

--------------------------------

### Using eprintln for Error Messages

Source: https://docs.rs/anstream/latest/anstream/macro.eprintln.html

Basic usage of the eprintln macro to print an error message to stderr.

```rust
use anstream::eprintln;

eprintln!("Error: Could not complete task");
```

--------------------------------

### AutoStream::auto

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Creates an AutoStream that automatically adapts to the stream's capabilities (requires 'auto' feature).

```APIDOC
## pub fn auto(raw: S) -> Self

### Description
Automatically detects and adapts to the stream's capabilities for styling.
```

--------------------------------

### Macro definition

Source: https://docs.rs/anstream/latest/anstream/macro.panic.html

The signature of the panic macro as defined in the crate.

```rust
macro_rules! panic {
    () => { ... };
    ($($arg:tt)*) => { ... };
}
```

--------------------------------

### ColorChoice::global()

Source: https://docs.rs/anstream/latest/anstream/enum.ColorChoice.html

Retrieves the current global ColorChoice state.

```APIDOC
## fn global()

### Description
Get the current `ColorChoice` state.

### Returns
- **ColorChoice** - The current global configuration for color output.
```

--------------------------------

### eprint Macro Definition

Source: https://docs.rs/anstream/latest/anstream/macro.eprint.html

The signature of the eprint macro as defined in the anstream crate.

```rust
macro_rules! eprint {
    ($($arg:tt)*) => { ... };
}
```

--------------------------------

### StrippedStr::to_string

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StrippedStr.html

Converts the printable content within the StrippedStr instance into a standard String.

```APIDOC
## pub fn to_string(&self) -> String

### Description
Creates a `String` of the printable content contained within the `StrippedStr` instance.

### Signature
`pub fn to_string(&self) -> String`
```

--------------------------------

### stdout() function

Source: https://docs.rs/anstream/latest/anstream/index.html

Creates an ANSI escape code compatible stdout stream.

```APIDOC
## stdout()

### Description
Creates an adaptive wrapper around the global standard output stream of the current process.

### Return Value
Returns an instance of `Stdout` which implements `std::io::Write`.
```

--------------------------------

### fn stdout

Source: https://docs.rs/anstream/latest/anstream/fn.stdout.html

Creates an ANSI escape code compatible stdout. This function is available when the 'auto' crate feature is enabled.

```APIDOC
## fn stdout()

### Description
Creates an ANSI escape code compatible stdout. Note that users should call `AutoStream::lock` in loops to avoid the performance hit of acquiring/releasing from the implicit locking in each `std::io::Write` call.

### Signature
`pub fn stdout() -> Stdout`

### Requirements
Available on crate feature `auto` only.
```

--------------------------------

### Locking stdout for Performance

Source: https://docs.rs/anstream/latest/anstream/macro.print.html

Locking stdout manually to avoid performance bottlenecks when calling print in a loop.

```rust
use std::io::Write as _;

let mut lock = anstream::stdout().lock();
write!(lock, "hello world").unwrap();
```

--------------------------------

### StripBytesIter Definition

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StripBytesIter.html

The definition of the StripBytesIter struct.

```rust
pub struct StripBytesIter<'s> { /* private fields */ }
```

--------------------------------

### PartialEq::ne

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StrippedStr.html

Tests for inequality between two values, used by the != operator.

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

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

--------------------------------

### PartialEq::eq

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StrippedStr.html

Tests for equality between two StrippedStr values, used by the == operator.

```APIDOC
## fn eq(&self, other: &StrippedStr<'s>) -> bool

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

--------------------------------

### fn is_terminal(&self) -> bool

Source: https://docs.rs/anstream/latest/anstream/stream/trait.IsTerminal.html

Checks if the underlying descriptor or handle refers to a terminal/tty. Returns true if it is a terminal, false otherwise.

```APIDOC
## fn is_terminal(&self) -> bool

### Description
Returns `true` if the descriptor or handle refers to a terminal/tty. This method is available for various types including `File`, `Stderr`, `Stdout`, and their respective locks.

### Signature
`fn is_terminal(&self) -> bool`

### Returns
- **bool** - Returns `true` if the handle is a terminal, `false` otherwise.
```

--------------------------------

### pub fn strip_str(data: &str) -> StrippedStr<'_>

Source: https://docs.rs/anstream/latest/anstream/adapter/fn.strip_str.html

Strips ANSI escape sequences from a &str, returning the printable content. This is useful for writing output to destinations that do not support ANSI escape sequences, such as log files.

```APIDOC
## Function: strip_str

### Description
Strips ANSI escape sequences from a `&str`, returning the printable content. This can be used to take output from a program that includes escape sequences and write it somewhere that does not easily support them, such as a log file.

### Signature
`pub fn strip_str(data: &str) -> StrippedStr<'_>`

### Parameters
- **data** (&str) - The input string containing potential ANSI escape sequences.

### Returns
- **StrippedStr** - A wrapper containing the printable content of the input string.

### Example
```rust
use std::io::Write as _;

let styled_text = "\x1b[32mfoo\x1b[m bar";
let plain_str = anstream::adapter::strip_str(&styled_text).to_string();
assert_eq!(plain_str, "foo bar");
```
```

--------------------------------

### fn stderr

Source: https://docs.rs/anstream/latest/anstream/fn.stderr.html

Creates an ANSI escape code compatible stderr stream. Note that users should call AutoStream::lock in loops to avoid performance overhead.

```APIDOC
## fn stderr

### Description
Creates an ANSI escape code compatible stderr stream. This function is available only when the `auto` crate feature is enabled.

### Signature
`pub fn stderr() -> Stderr`

### Usage Note
Call `AutoStream::lock` in loops to avoid the performance hit of acquiring/releasing from the implicit locking in each `std::io::Write` call.
```

--------------------------------

### panic!

Source: https://docs.rs/anstream/latest/anstream/macro.panic.html

The panic! macro terminates the current thread and provides a message payload. It is used to assert conditions and handle unrecoverable errors.

```APIDOC
## panic!

### Description
Panics the current thread. This allows a program to terminate immediately and provide feedback to the caller of the program. This macro is the perfect way to assert conditions in example code and in tests.

### Syntax
- `panic!()`
- `panic!($($arg:tt)*)`

### Parameters
- **$arg** (tt) - Optional - Formatting arguments used to build the panic message, following the `format!` syntax.

### Usage Example
```rust
use anstream::panic;

// Basic panic
panic!();

// Panic with a string message
panic!("this is a terrible mistake!");

// Panic with formatted message
panic!("this is a {} {message}", "fancy", message = "message");
```
```

--------------------------------

### stderr() function

Source: https://docs.rs/anstream/latest/anstream/index.html

Creates an ANSI escape code compatible stderr stream.

```APIDOC
## stderr()

### Description
Creates an adaptive wrapper around the global standard error stream of the current process.

### Return Value
Returns an instance of `Stderr` which implements `std::io::Write`.
```

--------------------------------

### ColorChoice::write_global(self)

Source: https://docs.rs/anstream/latest/anstream/enum.ColorChoice.html

Overrides the detected global ColorChoice state.

```APIDOC
## fn write_global(self)

### Description
Override the detected `ColorChoice` globally.

### Parameters
- **self** (ColorChoice) - The new color choice setting to apply globally.
```

--------------------------------

### AutoStream::always_ansi

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Forces ANSI escape codes to be passed through as-is.

```APIDOC
## pub fn always_ansi(raw: S) -> Self

### Description
Forces ANSI escape codes to be passed through as-is, regardless of the inner Write's capabilities.
```

--------------------------------

### StripBytes::strip_next

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StripBytes.html

Strips the next segment of data from the provided byte slice.

```APIDOC
## pub fn strip_next<'s>(&'s mut self, bytes: &'s [u8]) -> StripBytesIter<'s>

### Description
Processes the provided byte slice to strip the next segment of data.

### Parameters
- **bytes** (&[u8]) - The input byte slice to process.

### Returns
- **StripBytesIter** - An iterator over the stripped segments.
```

--------------------------------

### Define StrippedBytes struct

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StrippedBytes.html

The definition of the StrippedBytes struct.

```rust
pub struct StrippedBytes<'s> { /* private fields */ }
```

--------------------------------

### StripStream::into_inner / as_inner

Source: https://docs.rs/anstream/latest/anstream/struct.StripStream.html

Methods to retrieve the underlying writer from the StripStream.

```APIDOC
## pub fn into_inner(self) -> S
## pub fn as_inner(&self) -> &S

### Description
`into_inner` consumes the `StripStream` and returns the wrapped writer. `as_inner` returns a reference to the wrapped writer.
```

--------------------------------

### anstream::adapter::strip_bytes

Source: https://docs.rs/anstream/latest/anstream/adapter/fn.strip_bytes.html

Strips ANSI escape sequences from a byte slice.

```APIDOC
## Function: anstream::adapter::strip_bytes

### Description
Strips ANSI escape sequences from bytes, returning the printable content. This can be used to take output from a program that includes escape sequences and write it somewhere that does not easily support them, such as a log file.

### Signature
`pub fn strip_bytes(data: &[u8]) -> StrippedBytes<'_>`

### Parameters
- **data** (&[u8]) - The input byte slice containing potential ANSI escape sequences.

### Returns
- **StrippedBytes** - An object representing the printable content, which can be converted to a vector or other formats.

### Example
```rust
use std::io::Write as _;

let styled_text = "\x1b[32mfoo\x1b[m bar";
let plain_str = anstream::adapter::strip_bytes(styled_text.as_bytes()).into_vec();
assert_eq!(plain_str.as_slice(), &b"foo bar"[..]);
```
```

--------------------------------

### StrippedStr struct definition

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StrippedStr.html

The definition of the StrippedStr struct.

```rust
pub struct StrippedStr<'s> { /* private fields */ }
```

--------------------------------

### StripStrIter Definition

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StripStrIter.html

The definition of the StripStrIter struct.

```rust
pub struct StripStrIter<'s> { /* private fields */ }
```

--------------------------------

### AutoStream::lock

Source: https://docs.rs/anstream/latest/anstream/struct.AutoStream.html

Provides exclusive access to the AutoStream for performance or thread safety.

```APIDOC
## pub fn lock(self) -> AutoStream<LockType>

### Description
Returns an exclusive lock on the stream, useful for performance in loops or preventing interleaved output.
```

--------------------------------

### RawStream Trait Definition

Source: https://docs.rs/anstream/latest/anstream/stream/trait.RawStream.html

The trait requires implementations of Write, IsTerminal, and Sealed.

```rust
pub trait RawStream:
    Write
    + IsTerminal
    + Sealed { }
```

--------------------------------

### StripStr Definition

Source: https://docs.rs/anstream/latest/anstream/adapter/struct.StripStr.html

The definition of the StripStr struct.

```rust
pub struct StripStr { /* private fields */ }
```

--------------------------------

### StripStream Struct Definition

Source: https://docs.rs/anstream/latest/anstream/struct.StripStream.html

The core structure definition for StripStream, which wraps a writer S that implements std::io::Write.

```rust
pub struct StripStream<S>
where
    S: Write,
{ /* private fields */ }
```

--------------------------------

### ColorChoice Enum Definition

Source: https://docs.rs/anstream/latest/anstream/enum.ColorChoice.html

The primary enum used to configure color output behavior.

```rust
pub enum ColorChoice {
    Auto,
    AlwaysAnsi,
    Always,
    Never,
}
```

--------------------------------

### StripStream::lock

Source: https://docs.rs/anstream/latest/anstream/struct.StripStream.html

Locks the stream for exclusive access.

```APIDOC
## pub fn lock(self) -> StripStream<StdoutLock<'static>>
## pub fn lock(self) -> StripStream<StderrLock<'static>>

### Description
Provides exclusive access to the `StripStream` for `Stdout` or `Stderr`. This is useful for faster performance when writing in a loop and to prevent other threads from interleaving output.
```

--------------------------------

### IsTerminal Trait Definition

Source: https://docs.rs/anstream/latest/anstream/stream/trait.IsTerminal.html

The core trait definition requiring the implementation of the is_terminal method.

```rust
pub trait IsTerminal: Sealed {
    // Required method
    fn is_terminal(&self) -> bool;
}
```

--------------------------------

### StripStream::is_terminal

Source: https://docs.rs/anstream/latest/anstream/struct.StripStream.html

Checks if the underlying stream is a terminal.

```APIDOC
## pub fn is_terminal(&self) -> bool

### Description
Returns `true` if the descriptor or handle refers to a terminal/tty. This is available when the inner type `S` implements `IsTerminal`.
```

--------------------------------

### AsLockedWrite Trait Definition

Source: https://docs.rs/anstream/latest/anstream/stream/trait.AsLockedWrite.html

The core trait definition requiring an associated Write type and the as_locked_write method.

```rust
pub trait AsLockedWrite: Sealed {
    type Write<'w>: RawStream + 'w
       where Self: 'w;

    // Required method
    fn as_locked_write(&mut self) -> Self::Write<'_>;
}
```

--------------------------------

### Strip ANSI escapes from bytes

Source: https://docs.rs/anstream/latest/anstream/adapter/fn.strip_bytes.html

Use this function to remove ANSI escape sequences from byte data, such as when writing styled output to a log file.

```rust
use std::io::Write as _;

let styled_text = "\x1b[32mfoo\x1b[m bar";
let plain_str = anstream::adapter::strip_bytes(styled_text.as_bytes()).into_vec();
assert_eq!(plain_str.as_slice(), &b"foo bar"[..]);
```

--------------------------------

### Strip ANSI escapes from a string

Source: https://docs.rs/anstream/latest/anstream/adapter/fn.strip_str.html

Use this function to remove ANSI escape sequences from text before writing to destinations that do not support them, such as log files.

```rust
use std::io::Write as _;

let styled_text = "\x1b[32mfoo\x1b[m bar";
let plain_str = anstream::adapter::strip_str(&styled_text).to_string();
assert_eq!(plain_str, "foo bar");
```
Tokens:
Raw