Microsoft DirectX 8.0

String Functions

Declaration: Wxutil.h

AMGetWideStringAllocates and creates a wide string version of an existing nonwide string.
atoiConverts a string to an integer.
FreeBSTRFrees the task-allocated BSTR string.
IntToWstrConverts an integer to a wide string.
lstrcmpiWCompares two wide strings, ignoring case.
lstrcmpWCompares two wide strings.
lstrcpynWCopies one wide string to another, with a maximum length.
lstrcpyWCopies one wide string to another.
lstrlenWRetrieves the length of a wide string in wide characters.
WriteBSTRCreates a task-allocated BSTR string by allocating task-allocated memory and copying a wide string to it.
WstrToIntConverts a wide string to an integer.

AMGetWideString

String Functions

Allocates and creates a Unicode™ version of an existing non-Unicode string.

Syntax

STDAPI AMGetWideString(
    LPCWSTR pszString,
    LPWSTR *ppszReturn
    );

Parameters

pszString
Pointer to a non-Unicode source string.
ppszReturn
Address of a pointer to a Unicode™ string that will contain pszString.

Return Value

Returns S_OK if successful, E_POINTER if ppszReturn is NULL, or E_OUTOFMEMORY if not enough memory is available.

atoi

String Functions

Converts a given string to an integer.

Syntax

int WINAPI atoi(
    const TCHAR *sz
    );

Parameters

sz
Pointer to a source character string.

Return Value

Returns the string's integer value.

Remarks

This version of atoi supports only decimal digits, and does not allow leading white space or signs. It supports both Unicode™ and ANSI strings. Other versions can vary.

FreeBSTR

String Functions

Frees a task-allocated BSTR string from memory.

Syntax

STDAPI FreeBSTR(
    BSTR *pstr
    );

Parameters

pstr
Pointer to the BSTR to free.

Return Value

Returns S_OK if successful, or S_FALSE if pstr is null.

Remarks

Memory is allocated for passing between objects across interfaces by calling CoTaskMemAlloc. It is freed by calling CoTaskMemFree. You can allocate, pass, and free memory safely between objects created in different programming languages by using a central memory allocator.

IntToWstr

String Functions

Converts a given integer value to a wide string representation.

Syntax

void IntToWstr(
    int i,
    LPWSTR wstrDest
    );

Parameters

i
Integer value to be converted.
wstrDest
Pointer to the wide-character string that will contain the converted string.

Return Value

No return value.

lstrcmpiW

String Functions

Compares two wide-character strings. The comparison is not case sensitive.

Syntax

int lstrcmpiW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

Parameters

lpszString1
Pointer to the first null-terminated wide string to be compared.
lpszString2
Pointer to the second null-terminated wide string to be compared.

Return Value

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

Remarks

The lstrcmpiW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpiW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

lstrcmpW

String Functions

Compares two wide-character strings. The comparison is case sensitive.

Syntax

int lstrcmpW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

Parameters

lpszString1
Pointer to the first null-terminated wide string to be compared.
lpszString2
Pointer to the second null-terminated wide string to be compared.

Return Value

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

Remarks

The lstrcmpW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

lstrcpyW

String Functions

Copies a wide string to a buffer.

Syntax

LPWSTR lstrcpyW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2
    );

Parameters

lpszString1
Pointer to a buffer to receive the contents of the string pointed to by the lpszString2 parameter. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
Pointer to the null-terminated wide string to be copied.

Return Value

Returns a pointer to the buffer.

lstrcpynW

String Functions

Copies a wide string to a buffer, up to a specified number of wide characters.

Syntax

LPWSTR lstrcpynW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2,
    int iMaxLength
    );

Parameters

lpszString1
Pointer to a buffer to receive the contents of the string that the lpszString2 parameter points to. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
Pointer to the null-terminated wide string to be copied.
iMaxLength
Maximum number of wide characters to copy, including a terminating null character.

Return Value

Returns a pointer to the buffer.

Remarks

If iMaxLength is nonzero, lstrcpynW always inserts a terminating null wide character in the destination string, which could result in the source string being truncated.

lstrlenW

String Functions

Retrieves the length of the specified wide string.

Syntax

int lstrlenW(
    LPCWSTR lpszString
    );

Parameters

lpszString
Pointer to a null-terminated wide string.

Return Value

If the function succeeds, the return value specifies the length of the string, in wide characters.

WriteBSTR

String Functions

Allocates and fills a task-allocated BSTR string.

Syntax

STDAPI WriteBSTR(
    BSTR *pstrDest,
    LPCWSTR szSrc
    );

Parameters

pstrDest
Pointer to where the allocated BSTR will be stored.
szSrc
Pointer to a wide (Unicode™) string that will be copied to the newly allocated BSTR string.

Return Value

Returns an HRESULT value.

Remarks

Memory is allocated for passing between objects across interfaces by calling CoTaskMemAlloc. It is freed by calling CoTaskMemFree. By using a central memory allocator, memory can be allocated, passed, and freed safely between objects created in different programming languages.

WstrToInt

String Functions

Converts a given wide string value to an integer.

Syntax

int WstrToInt(
    LPCWSTR wstrSrc
    );

Parameters

wstrSrc
Pointer to the source wide-character string.

Return Value

Returns the string's integer value.