W3cubDocs

/Rust

Macro std::write

macro_rules! write {
    ($dst:expr, $($arg:tt)*) => { ... };
}

Writes formatted data into a buffer.

This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be formatted according to the specified format string and the result will be passed to the writer. The writer may be any value with a write_fmt method; generally this comes from an implementation of either the std::fmt::Write or the std::io::Write trait. The macro returns whatever the write_fmt method returns; commonly a std::fmt::Result, or an io::Result.

See std::fmt for more information on the format string syntax.

Examples

use std::io::Write;

fn main() -> std::io::Result<()> {
    let mut w = Vec::new();
    write!(&mut w, "test")?;
    write!(&mut w, "formatted {}", "arguments")?;

    assert_eq!(w, b"testformatted arguments");
    Ok(())
}

A module can import both std::fmt::Write and std::io::Write and call write! on objects implementing either, as objects do not typically implement both. However, the module must import the traits qualified so their names do not conflict:

use std::fmt::Write as FmtWrite;
use std::io::Write as IoWrite;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut s = String::new();
    let mut v = Vec::new();

    write!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt
    write!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt
    assert_eq!(v, b"s = \"abc 123\"");
    Ok(())
}

Note: This macro can be used in no_std setups as well. In a no_std setup you are responsible for the implementation details of the components.

use core::fmt::Write;

struct Example;

impl Write for Example {
    fn write_str(&mut self, _s: &str) -> core::fmt::Result {
         unimplemented!();
    }
}

let mut m = Example{};
write!(&mut m, "Hello World").expect("Not written");

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/macro.write.html