Copies a string to a memory address, optionally converting it to a given code page.
StrPut(String , Encoding := None) StrPut(String, Target , Length , Encoding := None)
Any string. If a number is given, it is automatically converted to a string.
String is assumed to be in the native encoding.
The memory address to which the string will be written.
Note: If conversion between code pages is necessary, the required buffer size may differ from the size of the source string. For such cases, call StrPut with two parameters to calculate the required size.
The maximum number of characters to write, including the null-terminator if required.
If Length is zero or less than the projected length after conversion (or the length of the source string if conversion is not required), zero characters are written.
Length must not be omitted unless the buffer size is known to be sufficient, such as if the buffer was allocated based on a previous call to StrPut with the same Source and Encoding.
Note: When Encoding is specified, Length should be the size of the buffer (in characters), not the length of String or a substring, as conversion may increase its length.
Note: Length and StrPut's return value are measured in characters, whereas buffer sizes are usually measured in bytes.
The target encoding; for example, "UTF-8", "UTF-16" or "CP936". For numeric identifiers, the prefix "CP" can be omitted only if Length is specified. Specify an empty string or "CP0" to use the system default ANSI code page.
This function returns the number of characters written. If no Target was given, it returns the required buffer size in characters. If Length is exactly the length of the converted string, the string is not null-terminated; otherwise the returned size includes the null-terminator.
An empty string is returned if invalid parameters are detected, or if the conversion cannot be performed. If the final number of characters would exceed Length, the return value is zero.
Note that the String parameter is always assumed to use the native encoding of the current executable, whereas Encoding specifies the encoding of the string written to the given Target. If no Encoding is specified, the string is simply measured or copied without any conversion taking place.
String Encoding, StrGet(), Script Compatibility, FileEncoding, DllCall(), VarSetCapacity()
Either Length or Encoding may be specified directly after Target, but in those cases Encoding must be non-numeric.
StrPut(str, address, "cp0") ; Code page 0, unspecified buffer size StrPut(str, address, n, 0) ; Maximum n chars, code page 0 StrPut(str, address, 0) ; Unsupported (maximum 0 chars)
StrPut may be called once to calculate the required buffer size for a string in a particular encoding, then again to encode and write the string into the buffer. The process can be simplified by adding this function to your library.
StrPutVar(string, ByRef var, encoding)
{
; Ensure capacity.
VarSetCapacity( var, StrPut(string, encoding)
; StrPut returns char count, but VarSetCapacity needs bytes.
* ((encoding="utf-16"||encoding="cp1200") ? 2 : 1) )
; Copy or convert the string.
return StrPut(string, &var, encoding)
}