Copies a string to or from a memory address, optionally converting to or from a given code page.
StrPut String , Encoding := None StrPut String, Address , Length , Encoding := None StrGet(Address , Length , Encoding := None )
Any string. Numbers are also acceptable.
The address at which the string will be written to/read from.
The maximum number of characters to read/write, including the null-terminator if required.
StrGet: By default, StrGet only copies up to the first binary zero. If Length is negative, its absolute value indicates the exact number of characters to convert, including any binary zeros that the string might contain - in other words, the result is always a string of exactly that length.
StrPut: See Return Value below for more details.
The source encoding for StrGet or target encoding for StrPut; for example, "UTF-8", "UTF-16" or "CP936". If Address and Length are not specified, numeric identifiers must be prefixed with "CP". Specify an empty string or "CP0" to use the system default ANSI code page.
For either function, invalid parameters cause an empty string to be returned.
StrPut returns the number of characters written, the required buffer size in characters if no Address was given, or 0 if an error occurred. If Length is less than the length of the converted string, the function fails and returns 0. If Length is exactly the length of the converted string, the string is not null-terminated; otherwise the returned count includes the null-terminator.
StrGet returns the requested string after performing any necessary conversion.
Note that the String parameter of StrPut and return value of StrGet are always in the native encoding of the current executable, whereas Encoding specifies the encoding of the string written to or read from the given Address. If no Encoding is specified, the string is simply measured or copied without any conversion taking place.
If conversion between code pages is necessary, the required buffer size may differ from the size of the source String.
Script Compatibility, FileEncoding, VarSetCapacity
Either Length or Encoding may be specified directly after Address, but in those cases Encoding must be non-numeric:
strA := StrGet(addressA, "cp0") ; OK strA := StrGet(addressA, length, 0) ; OK strA := StrGet(addressA, 0) ; Error
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. If you frequently use variables with StrPut, consider 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)
}