StrPut() [AHK_L 46+]

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

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

参数

String

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

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

Target

字符串将被写入的内存地址.

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

Length

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

如果 Length 为 0 或小于转换后的计划长度(或不需要转换时, 源字符串的长度), 没有字符被写入.

Length 不能被省略, 除非已知缓冲大小足够, 例如, 如果缓冲是基于先前使用相同的 String 和 Encoding 调用 StrPut 分配的.

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

注意: Length 和 StrPut 的返回值是以字符数来计算的, 而缓冲大小通常以字节度量.

Encoding

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

返回值

在 4 或 3 参数模式下, 函数返回写入的字符数. 在 2 参数模式下, 则返回以字符数表示的必须的缓冲大小. 如果 Length 准确等于转换的字符串的长度, 那么字符串不包含空终止符; 否则返回的大小包含空终止符.

错误处理

如果检测到无效参数或转换无法执行, 则返回空字符串. 如果最终字符数超过 Length, 则返回 0.

备注

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

字符编码, StrGet(), 脚本兼容性, FileEncoding, DllCall(), VarSetCapacity()

示例

Length 或 Encoding 都可以直接在 Target 后面指定, 但在这种情况下 Encoding 必须是非数字的.

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

可以调用一次 StrPut, 来计算特定编码中的字符串所需的缓冲大小, 然后再次对字符串进行编码并将其写入缓冲. 这个过程可以通过在你的库中添加以下函数来简化.

StrPutVar(string, ByRef var, encoding)
{
    ; 确定容量.
    VarSetCapacity( var, StrPut(string, encoding)
        ; StrPut 返回字符数, 但 VarSetCapacity 需要字节数.
        * ((encoding="utf-16"||encoding="cp1200") ? 2 : 1) )
    ; 复制或转换字符串.
    return StrPut(string, &var, encoding)
}