StrPut

复制字符串到内存地址或缓冲, 可选地将字符串转换到给定的代码页.

BytesWritten := StrPut(String, Target , Length, Encoding)
BytesWritten := StrPut(String, Target , Encoding)
ReqBufSize   := StrPut(String , Encoding)

参数

String

类型: 字符串

任何字符串. 如果给定一个数字, 它将自动转换为字符串.

String 被假定为使用原生编码.

Target

类型: 对象或整数

类缓冲对象或内存地址, 字符串将写入其中.

可以使用任何实现 Ptr 和 Size 属性的对象, 但此函数针对原生的缓冲对象进行了优化. 传递具有这些属性的对象可确保函数不会将内存写入无效位置; 这样做可能会导致崩溃或其他不可预测的行为.

注意: 如果需要在代码页之间进行转换, 则所需的缓冲大小可能与源字符串的大小不同. 对于这种情况, 调用带有两个参数的 StrPut 来计算所需的大小.

Length

类型: 整数

如果未设置或省略(或使用 3 参数模式时), 并且如果 Target 不是一个普通内存地址, 则默认为缓冲的大小, 这意味着假定缓冲大小足够(例如, 如果缓冲是基于先前使用相同的 String和Encoding 调用 StrPut 分配的), 则可以不设置或省略. 否则, 请指定要写入的最大字符数, 需要时包含空终止符.

如果 Length 为 0 或小于转换后的计划长度(或不需要转换时, 源字符串的长度), 则抛出异常.

如果 Target 是一个对象, 指定一个超过 Target.Size 计算出的缓冲大小的 Length 被认为是一个错误, 即使转换后的字符串大小在缓冲内.

注意: 当指定 Encoding 时, Length 应该是缓冲的大小(以字符为单位), 而不是 String 或子字符串的长度, 因为转换可能会增加其长度.

注意: Length 是以字符数来计算的, 而缓冲大小通常以字节度量, StrPut 的返回值也是如此. 若要以字节为单位来指定缓冲大小, 请在 Target 参数中使用类缓冲对象.

Encoding

类型: 字符串或整数

如果未设置或省略, 那么将简单地复制或测量字符串, 而不进行任何转换. 否则, 请指定目标编码; 例如, "UTF-8", "UTF-16" 或 "CP936". 对于数字标识符, 只有在 4 参数模式中, 才可以省略前缀 "CP". 指定空字符串或 "CP0" 则使用系统默认 ANSI 代码.

返回值

类型: 整数

在 4 或 3 参数模式下, 函数返回写入的的字节数. 只有当有足够的空间时, 才会写入空终止符并包含在返回值中; 也就是说, 当 Length 或 Target.Size(乘以一个字符的大小) 正好等于转换后的字符串的长度时, 则会省略空终止符.

在 2 参数模式下, 函数返回以字节数表示的所需的缓冲大小, 其中包含了空终止符.

错误处理

如果检测到无效参数, 则抛出 ValueError, 例如转换后的字符串会超过 Length 或 Target.Size 所允许的长度.

如果转换无法执行, 则抛出 OSError.

备注

注意, String 参数总是假定使用当前可执行文件的原生编码, 而 Encoding 指定写入给定 Target 的字符串的编码. 如果没有指定 Encoding, 则只复制或测量字符串, 而不进行任何转换.

相关

字符编码, StrGet, 二进制兼容性, FileEncoding, DllCall, 缓冲对象, VarSetStrCapacity

示例

StrPut(str, address, "cp0")  ; 代码页 0, 未指定缓冲大小
StrPut(str, address, n, 0)   ; 最大 n 字符, 代码页 0
StrPut(str, address, 0)      ; 不支持(最大长度为 0 的字符)

; 返回包含字符串的缓冲对象.
StrBuf(str, encoding)
{
    ; 计算所需的大小并分配缓冲.
    buf := Buffer(StrPut(str, encoding))
    ; 复制或转换字符串.
    StrPut(str, buf, encoding)
    return buf
}