StrPut

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

StrPut String , Encoding := None 
StrPut String, Target , Length , Encoding := None

参数

String

类型: 字符串

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

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

Target

类型: 对象或整数

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

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

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

Length

类型: 整数

要写入的最大字符数, 需要时包含空终止符.

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

当 Target 是一个普通的内存地址时, 不能省略 Length, 除非已知缓冲的大小足够大, 例如, 如果缓冲是基于先前调用的 StrPut 而分配的, 具有相同的 Source 和 Encoding.

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

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

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

Encoding

类型: 字符串或整数

目标编码; 例如, "UTF-8", "UTF-16" 或 "CP936". 对于数字标识符, 只有在指定 Length 时, 才可以省略前缀 "CP". 指定空字符串或 "CP0" 则使用系统默认 ANSI 代码.

返回值

类型: 整数

如果省略了 Target, 函数返回以字节数表示的所需的缓冲大小, 包含了空终止符.

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

错误处理

如果检测到无效参数, 则抛出 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
}