fmtbuf

将格式化的字符串写入固定缓冲区。当您需要将用户提供的缓冲区写入时，这非常有用，尤其是在编写与C的FFI时，字符串需要以null终止符结尾。

用法

use fmtbuf::WriteBuf;
use std::fmt::Write;

fn main() {
    let mut buf: [u8; 10] = [0; 10];
    let mut writer = WriteBuf::new(&mut buf);
    if let Err(e) = write!(&mut writer, "🚀🚀🚀") {
        println!("write error: {e:?}");
    }
    let written_len = match writer.finish_with("\0") {
        Ok(len) => len, // <- won't be hit since 🚀🚀🚀 is 12 bytes
        Err(len) => {
            println!("writing was truncated");
            len
        }
    };
    let written = &buf[..written_len];
    println!("wrote {written_len} bytes: {written:?}");
    println!("result: {:?}", std::str::from_utf8(written));
}

🚀🚀

主要用例是实现像 strerror_r 这样的API，其中用户提供缓冲区。

use std::{ffi, fmt::Write, io::Error};
use fmtbuf::WriteBuf;

#[no_mangle]
pub unsafe extern "C" fn mylib_strerror(
    err: *mut Error,
    buf: *mut ffi::c_char,
    buf_len: usize
) {
    let mut buf = unsafe {
        // Buffer provided by a users
        std::slice::from_raw_parts_mut(buf as *mut u8, buf_len)
    };
    // Reserve at least 1 byte at the end because we will always
    // write '\0'
    let mut writer = WriteBuf::with_reserve(buf, 1);

    // Use the standard `write!` macro (no error handling for
    // brevity) -- note that an error here might only indicate
    // write truncation, which is handled gracefully be this
    // library's finish___ functions
    let _ = write!(writer, "{}", err.as_ref().unwrap());

    // null-terminate buffer or add "..." if it was truncated
    let _written_len = writer.finish_with_or(b"\0", b"...\0")
        // Err value is also number of bytes written
        .unwrap_or_else(|e| e);
}

特性

!#[no_std]

通过禁用默认功能并重新启用 "std" 功能来启用对 !#[no_std] 的支持。

fmtbuf = { version = "*", default_features = false }

常见问题解答

为什么不能写入 &mut [u8]？

Rust标准库中的 std::io::Write trait为 &mut [u8] 实现，可以用来代替这个库。这种方法的问题是没有UTF-8编码支持（此外，在 #![no_std] 中也不可用）。

use std::io::{Cursor, Write};

fn main() {
    let mut buf: [u8; 10] = [0; 10];
    let mut writer = Cursor::<&mut [u8]>::new(&mut buf);
    if let Err(e) = write!(&mut writer, "rocket: 🚀") {
        println!("write error: {e:?}");
    }
    let written_len = writer.position() as usize;
    let written = &buf[..written_len];
    println!("wrote {written_len} bytes: {written:?}");
    println!("result: {:?}", std::str::from_utf8(written));
}

运行此程序将显示错误

write error: Error { kind: WriteZero, message: "failed to write whole buffer" }
wrote 10 bytes: [114, 111, 99, 107, 101, 116, 58, 32, 240, 159]
result: Err(Utf8Error { valid_up_to: 8, error_len: None })

问题是，""rocket: 🚀""被编码成一个12字节的序列——🚀表情符号在UTF-8中以4字节编码为b"\xf0\x9f\x9a\x80"——但我们的目标缓冲区只有10字节长。对光标的write!操作天真地切断了🚀的编码过程，使得编码后的字符串无效UTF-8，尽管它已经将光标前进了整个10字节。这是预期的，因为std::io::Write来自io，不知道任何关于字符串编码的信息；它在u8级别上操作。