format

std.format

fun write_bytes

pub fun write_bytes(w: *writer.Writer, buf: *u8, len: usize) Result[usize, str];

将原始字节写入写入器

w:目标写入器 buf:源缓冲区 len:要写入的字节数 返回值:已写入的字节数,或错误消息

fun write_str

pub fun write_str(w: *writer.Writer, s: str) Result[usize, str];

将以空字符结尾的字符串写入写入器

w:目标写入器 s:要写入的字符串(若为 nil 则视为空字符串) 返回值:已写入的字节数,或错误消息

fun write_byte

pub fun write_byte(w: *writer.Writer, b: u8) Result[usize, str];

将单个字节写入写入器

w:目标写入器 b:要写入的字节 返回值:成功时为 1,或错误消息

fun write_newline

pub fun write_newline(w: *writer.Writer) Result[usize, str];

向写入器写入一个换行符

w:目标写入器 返回值:成功时为 1,或错误消息

fun write_u64

pub fun write_u64(w: *writer.Writer, n: u64) Result[usize, str];

以十进制形式写入无符号整数

w:目标写入器 n:要格式化的值 返回值:已写入的字节数,或错误消息

fun write_i64

pub fun write_i64(w: *writer.Writer, n: i64) Result[usize, str];

以十进制形式写入有符号整数

w:目标写入器 n:要格式化的值 返回值:已写入的字节数,或错误消息

fun write_hex_u64

pub fun write_hex_u64(w: *writer.Writer, n: u64, upper: bool) Result[usize, str];

以十六进制形式写入 64 位值

w:目标写入器 n:要格式化的值 upper:若为 true 则使用大写(A-F),若为 false 则使用小写(a-f) 返回值:已写入的字节数,或错误消息

fun write_ptr

pub fun write_ptr(w: *writer.Writer, p: ptr) Result[usize, str];

将指针写入为 0x 后跟十六进制数字的形式

w:目标写入器 p:要格式化的指针 返回值:已写入的字节数,或错误消息

fun write_f64

pub fun write_f64(w: *writer.Writer, n: f64) Result[usize, str];

以最短可往返的十进制形式写入 64 位浮点数

w:目标写入器 n:要格式化的值 返回值:已写入的字节数,或错误消息

val ERR_BAD_FORMAT

pub val ERR_BAD_FORMAT: str = "bad format"

val ERR_FEW_HOLES

pub val ERR_FEW_HOLES:  str = "more arguments than format holes"

val ERR_MANY_HOLES

pub val ERR_MANY_HOLES: str = "more format holes than arguments"

fun vformat

pub fun vformat(w: *writer.Writer, fmt: str, va: ...) Result[usize, str];

将编译期可变参数包格式化到写入器中(v1.7 打包机制)

孔(holes)是类型导向的 {},按顺序与参数匹配:有符号/无符号整型 -> 十进制,str -> 文本,ptr -> 0xHEXf64 -> 最短可往返十进制。规格说明:{:x}/{:X} 十六进制,{:c} 低字节字符,{:N}/{:0N} 最小宽度(右对齐),{:<N} 左对齐。{{}} 是字面量大括号转义。参数序列在编译期展开并针对每次调用进行单态化(monomorphized);格式扫描留在运行时执行。

w:目标写入器 fmt:格式化字符串 va:编译期可变参数包 返回值:总写入字节数,或错误消息

fun format

pub fun format(w: *writer.Writer, fmt: str, va: ...) Result[usize, str];

将编译期可变参数包格式化到写入器中

这是一个轻量包装器,将整个参数包转发给 vformat

w:目标写入器 fmt:格式化字符串 va:编译期可变参数包 返回值:总写入字节数,或错误消息

fun sprint

pub fun sprint(a: *A.Allocator, fmt: str, va: ...) Result[str, str];

将编译期可变参数包格式化为一个新分配的字符串

这是 format/vformat 的内存分配对应版本:使用相同的类型导向分派和规格词汇渲染相同的 {} 孔,但返回由 a 拥有的新 str,而不是写入到 Writer 中。结果是一个精确大小、以空字符结尾的分配(str_len + 1 字节),与 std.types.string 的分配构造函数相匹配。执行两次格式化:首先通过 vformat 的测量遍来确定缓冲区大小,然后填充遍渲染到其中,因此不需要增长或修剪。格式错误会在任何分配发生之前报告。

a:结果的分配器 fmt:格式化字符串 va:编译期可变参数包 返回值:格式化后的字符串,或者在分配器为 nil、分配失败或格式畸形时返回错误