StrPut() [AHK_L 46+]

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)

매개변수

String

문자열, If a number is given, it is automatically converted to a string.

String is assumed to be in the native encoding.

Target

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.

Length

쓸 문자의 최대 개수, 필요하면 널-종료 문자 포함.

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.

Encoding

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. 빈 문자열이나 "CP0"을 지정하면 시스템 기본 ANSI 코드 페이지를 사용합니다.

반환 값

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. Encoding을 지정하지 않으면, 그 문자열은 그냥 아무 변환도 일어나지 않고 그대로 복사되거나 측정됩니다.

String Encoding, StrGet(), Script Compatibility, FileEncoding, DllCall(), VarSetCapacity()

예제

Length나 Encoding을 Target 다음에 직접적으로 지정할 수 있습니다. 그러나 그런 경우 Encoding은 절대로 숫치형이 되면 안됩니다.

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은 특정한 인코딩으로 문자열에 대하여 필요한 버퍼 크기를 계산하기 위하여 한 번 호출이 가능합니다. 다음, 그 문자열을 인코드해서 버퍼 안으로 써 넣을 수 있습니다. The process can be simplified by adding this function to your library.

StrPutVar(string, ByRef var, encoding)
{
    ; 가용능력을 확인합니다.
    VarSetCapacity( var, StrPut(string, encoding)
        ; StrPut은 문자 개수를 돌려주지만, VarSetCapacity는 바이트를 필요로 합니다.
        * ((encoding="utf-16"||encoding="cp1200") ? 2 : 1) )
    ; 그 문자열을 복사하거나 변환합니다.
    return StrPut(string, &var, encoding)
}