ACP: Add API to write formatted data directly into a `Vec<u8>`

[moulins]

Proposal

Problem statement

Add a way to write formatted data to a Vec<u8> (instead of a String). The "straightforward" solution of implementing fmt::Write for Vec<u8> would risk causing ambiguities with the write! macro, so this proposes a dedicated API.

Motivating examples or use cases

Writing formatted data to a Vec<u8> buffer is currently awkward; you can either:

use core::fmt::{self, Display};

// ...use `io::Write` and map the error back.
// This isn't available in no-std code, and is somewhat confusing.
// It also has worse codegen because the error path constructs a `io::Error` only to immediately drop it.
fn write_with_io(buffer: &mut Vec<u8>, data: &dyn Display) -> fmt::Result {
  use std::io::Write;
  write!(buffer, "the data is: {data}").map_err(|_| std::fmt::Error)
}

// ...use a temporary string. This works in no-std, but incurs an extra allocation.
fn write_with_tmp(buffer: &mut Vec<u8>, data: &dyn Display) -> fmt::Result {
  let tmp = format!("the data is: {data}");
  buffer.extend_from_slice(tmp.as_bytes());
  Ok(())
}

Solution sketch

// in alloc::fmt

pub fn write_to_buf(buf: &mut Vec<u8>, args: Arguments<'_>) -> Result;

#[repr(transparent)]
pub struct FmtBuffer {
  // SAFETY: only appending bytes is allowed, as the source may rely on existing data being valid UTF8
  raw: Vec<u8>,
}

impl FmtBuffer {
  pub fn from_vec(buf: &mut Vec<u8>) -> &mut Self;

  // Could be omitted
  pub fn from_string(buf: &mut String) -> &mut Self;
  
  pub fn reserve(&mut self, len: usize);

  // Needed to make `write!` work without requiring having `fmt::Write` in scope.
  pub fn write_fmt(&mut self, args: Arguments<'_>) -> Result;
}

impl Write for FmtBuffer;

impl Deref for FmtBuffer {
  type Target = [u8];
}

// Note: no DerefMut; this would conflict with `FmtBuffer::from_string`

Alternatives

• Only provide the write_to_buf free function.
• Do not provide FmtBuffer::from_string; this would allow implementing DerefMut<Target=Vec<u8>>.
• Implement FmtBuffer as struct FmtBuffer<'a>(&'a mut Vec<u8>) instead; this skips needing transmutes in the constructors, but adds an extra level of indirection. The (slight) performance cost could probably be mitigated by adding a new SpecWriteFmt impl.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[hanna-kruppe]

Since this is a new wrapper type, not a trait impl that would be prevented by coherence, the bare minimum version of this seems trivial to implement in third party libraries. Are there any examples of libraries doing this?

[moulins]

Are there any examples of libraries doing this?

Not to my knowledge.

[jmillikin]

I've implemented something similar in several no_std libraries, either writing to &mut Vec<u8> or to a pre-allocated &mut [u8] / &mut [MaybeUninit<u8>]. Though the Vec<u8> versions in my own libs use failable allocation, so an extra layer of error handling.

Publically available example: https://github.com/jmillikin/rust-fuse/blob/88740a5ec642ab680b4b188b4c727d598554b206/fuse/os/linux.rs#L715-L736

struct BufWriter<'a> {
	buf: &'a mut [u8],
	count: usize,
}

impl BufWriter<'_> {
	fn write_bytes(&mut self, b: &[u8]) -> fmt::Result {
		let avail = &mut self.buf[self.count..];
		if b.len() > avail.len() {
			return Err(fmt::Error);
		}
		avail[..b.len()].copy_from_slice(b);
		self.count += b.len();
		Ok(())
	}
}

impl fmt::Write for BufWriter<'_> {
	fn write_str(&mut self, s: &str) -> fmt::Result {
		self.write_bytes(s.as_bytes())
	}
}

It feels related to BorrowedBuf and BorrowedCursor.

[the8472]

Related ACP: #133