# 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

## 示例

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

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

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

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

dftg