OCI String Manipulation Functions

Two types of data structures are supported for string manipulation:

• multibyte strings
• wide-character strings

Multibyte strings are encoded in native Oracle character sets. Functions that operate on multibyte strings take the string as a whole unit with the length of the string calculated in bytes. wide-character (wchar) string functions provide more flexibility in string manipulation. They support character-based and string-based operations with the length the string calculated in characters.

The wide-character datatype is Oracle-specific and should not be confused with the wchar_t datatype defined by the ANSI/ISO C standard. The Oracle wide-character datatype is always 4 bytes in all operating systems, while the size of wchar_t depends on the implementation and the operating system. The Oracle wide-character datatype normalizes multibyte characters so that they have a fixed width for easy processing. This guarantees no data loss for round trip conversion between the Oracle wide-character set and the native character set.

String manipulation can be classified into the following categories:

• Conversion of strings between multibyte and wide character
• Character classifications
• Case conversion
• Calculations of display length
• General string manipulation, such as comparison, concatenation, and searching

Table 21-5 summarizes the OCI string manipulation functions.

Table 21-5 OCI String Manipulation Functions  

Function/Page	Purpose
OCIMultiByteInSizeToWideChar()	Converts part of a multibyte string into the wide-character string.
OCIMultiByteStrCaseConversion()	Converts a multibyte string into the specified case and copies the result into the destination array.
OCIMultiByteStrCat()	Appends a multibyte string to the destination string.
OCIMultiByteStrcmp()	Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods.
OCIMultiByteStrcpy()	Copies a multibyte string into the destination array. It returns the number of bytes copied.
OCIMultiByteStrlen()	Returns the number of bytes in a multibyte string.
OCIMultiByteStrncat()	Appends at most n bytes from a multibyte string to the destination string.
OCIMultiByteStrncmp()	Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. Each string is in the specified length.
OCIMultiByteStrncpy()	Copies a specified number of bytes of a multibyte string into the destination array.
OCIMultiByteStrnDisplayLength()	Returns the number of display positions occupied by the multibyte string within the range of n bytes.
OCIMultiByteToWideChar()	Converts a NULL-terminated multibyte string into wide-character format.
OCIWideCharInSizeToMultiByte()	Converts part of a wide-character string to the multibyte string.
OCIWideCharMultiByteLength()	Determines the number of bytes required for a wide-character in multibyte encoding.
OCIWideCharStrCaseConversion()	Converts a wide character string into the specified case and copies the result into the destination array.
OCIWideCharStrcat()	Appends a wide-character string to the destination string.
OCIWideCharStrchr()	Searches for the first occurrence of a wide character in a string. It returns a point to the wide character if the search is successful.
OCIWideCharStrcmp()	Compares two wide-character strings by binary, linguistic, or case-insensitive comparison methods.
OCIWideCharStrcpy()	Copies a wide-character string into a destination array. It returns the number of characters copied.
OCIWideCharStrlen()	Returns the number of characters in a wide-character string.
OCIWideCharStrncat()	Appends at most n characters from a wide-character string to the destination string.
OCIWideCharStrncmp()	Compares two wide-character strings by binary, linguistic, or case-insensitive methods. Each string is a specified length.
OCIWideCharStrncpy()	Copies at most n characters of a wide-character string into the destination array.
OCIWideCharStrrchr()	Searches for the last occurrence of a character in a wide-character string.
OCIWideCharToLower()	Converts a specified wide character into the corresponding lowercase character.
OCIWideCharToMultiByte()	Converts a NULL-terminated wide-character string into a multibyte string.
OCIWideCharToUpper()	Converts a specified wide character into the corresponding uppercase character.

OCIMultiByteInSizeToWideChar()

Purpose

Converts part of a multibyte string into the wide-character string.

Syntax

sword OCIMultiByteInSizeToWideChar ( dvoid         *hndl,
                                     OCIWchar      *dst,
                                     size_t        dstsz,
                                     CONST OraText *src,
                                     size_t        srcsz,
                                     size_t        *rsize );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set of the string.

dst (OUT)

Pointer to a destination buffer for wchar. It can be NULL pointer when dstsz is zero.

dstsz (IN)

Destination buffer size in number of characters. If it is zero, then this function returns the number of characters needed for the conversion.

src (IN)

Source string to be converted.

srcsz (IN)

Length of source string in bytes.

rsize (OUT)

Number of characters written into destination buffer, or number of characters for converted string if dstsz is zero. If it is a NULL pointer, then nothing is returned.

Comments

This routine converts part of a multibyte string into the wide-character string. It converts as many complete characters as it can until it reaches the output buffer size limit or input buffer size limit or it reaches a NULL terminator in a source string. The output buffer is NULL-terminated if space permits. If dstsz is zero, then this function returns only the number of characters not including the ending NULL terminator needed for a converted string. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR..

Related Functions

OCIMultiByteToWideChar()

OCIMultiByteStrCaseConversion()

Purpose

Converts the multibyte string pointed to by srcstr into uppercase or lowercase as specified by the flag and copies the result into the array pointed to by dststr.

Syntax

size_t OCIMultiByteStrCaseConversion ( dvoid          *hndl, 
                                       OraText        *dststr, 
                                       CONST OraText  *srcstr, 
                                       ub4            flag );

Parameters

hndl (IN/OUT)

OCI environment or user session handle.

dststr (OUT)

Pointer to destination array. The result string is NULL-terminated.

srcstr (IN)

Pointer to source string.

flag (IN)

Specify the case to which to convert:

• OCI_NLS_UPPERCASE: Convert to uppercase
• OCI_NLS_LOWERCASE: Convert to lowercase

This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale is used for case conversion.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes for result string, not including the NULL terminator.

OCIMultiByteStrCat()

Purpose

Appends a copy of the multibyte string pointed to by srcstr to the end of the string pointed to by dststr.

Syntax

size_t OCIMultiByteStrCat ( dvoid           *hndl, 
                            OraText         *dststr, 
                            CONST OraText   *srcstr );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

dststr (IN/OUT)

Pointer to the destination multibyte string for appending. The output buffer is NULL-terminated.

srcstr (IN)

Pointer to the source string to append.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes in the result string, not including the NULL terminator.

Related Functions

OCIMultiByteStrncat()

OCIMultiByteStrcmp()

Purpose

Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods.

Syntax

int OCIMultiByteStrcmp ( dvoid           *hndl, 
                         CONST OraText   *str1, 
                         CONST OraText   *str2, 
                         int             flag );

Parameters

hndl (IN/OUT)

OCI environment or user session handle.

str1 (IN)

Pointer to a NULL-terminated string.

str2 (IN)

Pointer to a NULL-terminated string.

flag (IN)

It is used to decide the comparison method. It can take one of the following values:

• OCI_NLS_BINARY: Binary comparison This is the default value.
• OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale

This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison. For example, use OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings linguistically without regard to case.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

• 0, if str1 = str2
• Positive, if str1 > str2
• Negative, if str1 < str2

Related Functions

OCIMultiByteStrncmp()

OCIMultiByteStrcpy()

Purpose

Copies the multibyte string pointed to by srcstr into the array pointed to by dststr.

Syntax

size_t OCIMultiByteStrcpy ( dvoid           *hndl, 
                            OraText         *dststr, 
                            CONST OraText   *srcstr );

Parameters

hndl (IN/OUT)

Pointer to the OCI environment or user session handle.

dststr (OUT)

Pointer to the destination buffer.The output buffer is NULL-terminated.

srcstr (IN)

Pointer to the source multibyte string.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes copied, not including the NULL terminator.

Related Functions

OCIMultiByteStrncpy()

OCIMultiByteStrlen()

Purpose

Returns the number of bytes in the multibyte string pointed to by str, not including the NULL terminator.

Syntax

size_t OCIMultiByteStrlen ( dvoid          *hndl, 
                            CONST OraText  *str );

Parameters

hndl (IN/OUT)

Pointer to the OCI environment or user session handle.

str (IN)

Pointer to the source multibyte string.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes, not including the NULL terminator.

Related Functions

OCIWideCharStrlen()

OCIMultiByteStrncat()

Purpose

Appends a specified number of bytes from a multibyte string to a destination string.

Syntax

size_t OCIMultiByteStrncat ( dvoid           *hndl, 
                             OraText         *dststr, 
                             CONST OraText   *srcstr, 
                             size_t          n );

Parameters

hndl (IN/OUT)

Pointer to OCI environment or user session handle.

dststr (IN/OUT)

Pointer to the destination multibyte string for appending.

srcstr (IN)

Pointer to the source multibyte string to append.

n (IN)

The number of bytes from srcstr to append.

Comments

This function is similar to OCIMultiByteStrcat(). At most n bytes from srcstr are appended to dststr. Note that the NULL terminator in srcstr stops appending and the function appends as many character as possible within n bytes. dststr is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes in the result string, not including the NULL terminator

Related Functions

OCIMultiByteStrCat()

OCIMultiByteStrncmp()

Purpose

Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. A length is specified for each string.

Syntax

int OCIMultiByteStrncmp ( dvoid          *hndl,
                          CONST OraText  *str1,
                          size_t         len1,
                          OraText        *str2,
                          size_t         len2,
                          int            flag );

Parameters

hndl (IN/OUT)

OCI environment or user session handle.

str1 (IN)

Pointer to the first string.

len1 (IN)

The length of the first string to compare.

str2 (IN)

Pointer to the second string.

len2 (IN)

The length of the second string to compare.

flag( IN)

It is used to decide the comparison method. It can take one of the following values:

• OCI_NLS_BINARY: Binary comparison. This is the default value.
• OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale

This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison. For example, use OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings linguistically without regard to case.

Comments

This function is similar to OCIMultiByteStrcmp(), except that at most len1 bytes from str1 and len2 bytes from str2 are compared. The NULL terminator is used in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

• 0, if str1 = str2
• Positive, if str1 > str2
• Negative, if str1 < str2

Related Functions

OCIMultiByteStrcpy()

OCIMultiByteStrncpy()

Purpose

Copies a multibyte string into an array.

Syntax

size_t OCIMultiByteStrncpy ( dvoid           *hndl, 
                             OraText         *dststr, 
                             CONST OraText   *srcstr, 
                             size_t           n );

Parameters

hndl (IN/OUT)

Pointer to OCI environment or user session handle.

srcstr (OUT)

Pointer to the destination buffer.

dststr (IN)

Pointer to the source multibyte string.

n (IN)

The number of bytes from srcstr to copy.

Comments

This function is similar to OCIMultiByteStrcpy(). At most n bytes are copied from the array pointed to by srcstr to the array pointed to by dststr. Note that the NULL terminator in srcstr stops copying and the function copies as many characters as possible within n bytes. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes in the resulting string, not including the NULL terminator.

Related Functions

OCIMultiByteStrcpy()

OCIMultiByteStrnDisplayLength()

Purpose

Returns the number of display positions occupied by the multibyte string within the range of n bytes.

Syntax

size_t OCIMultiByteStrnDisplayLength ( dvoid           *hndl, 
                                       CONST OraText   *str1, 
                                       size_t          n );

Parameters

hndl (IN/OUT)

OCI environment or user session handle.

str (IN)

Pointer to a multibyte string.

n (IN)

The number of bytes to examine.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of display positions.

OCIMultiByteToWideChar()

Purpose

Converts an entire NULL-terminated string into the wide-character string.

Syntax

sword OCIMultiByteToWideChar ( dvoid           *hndl, 
                               OCIWchar        *dst, 
                               CONST OraText   *src, 
                               size_t          *rsize );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set of string

dst (OUT)

Destination buffer for wchar.

src (IN)

Source string to be converted.

rsize (OUT)

Number of characters converted including NULL terminator. If it is a NULL pointer, then nothing is returned.

Comments

The wchar output buffer are NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Related Functions

OCIWideCharToMultiByte()

OCIWideCharInSizeToMultiByte()

Purpose

Converts part of a wide-character string to multibyte format.

Syntax

sword OCIWideCharInSizeToMultiByte ( dvoid            *hndl, 
                                     OraText          *dst, 
                                     size_t           dstsz, 
                                     CONST OCIWchar   *src, 
                                     size_t           srcsz, 
                                     size_t           *rsize );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set of string.dst (OUT)

Destination buffer for multibyte. It can be a NULL pointer if dstsz is zero.

dstsz (IN)

Destination buffer size in bytes. If it is zero,then the function returns the size in bytes need for converted string.

src (IN)

Source wchar string to be converted.

srcsz (IN)

Length of source string in characters.

rsize (OUT)

Number of bytes written into destination buffer, or number of bytes need to store the converted string if dstsz is zero. If it is a NULL pointer, then nothing is returned.

Comments

Converts part of a wide-character string into the multibyte format. It converts as many complete characters as it can until it reaches the output buffer size or the input buffer size or until it reaches a NULL terminator in the source string. The output buffer is NULL-terminated if space permits. If dstsz is zero, then the function returns the size in bytes not including the NULL terminator needed to store the converted string. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR,

OCIWideCharMultiByteLength()

Purpose

Determines the number of bytes required for a wide character in multibyte encoding.

Syntax

size_t OCIWideCharMultiByteLength ( dvoid     *hndl, 
                                    OCIWchar  wc );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wc (IN)

wchar character.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes required for the wide character.

OCIWideCharStrCaseConversion()

Purpose

Converts a wide-character string into a specified case and copies the result into the destination array.

Syntax

size_t OCIMultiByteStrCaseConversion ( dvoid             *hndl, 
                                       OraText           *dststr, 
                                       CONST OraText     *srcstr, 
                                       ub4               flag );

Parameters

ndl (IN/OUT)

OCI environment or user session handle.

dststr (OUT)

Pointer to destination array.

srcstr (IN)

Pointer to source string.

flag (IN)

Specify the case to which to convert:

• OCI_NLS_UPPERCASE: Convert to uppercase.
• OCI_NLS_LOWERCASE: Convert to lowercase.

This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale is used for case conversion.

Comments

Converts the wide-character string pointed to by srcstr into uppercase or lowercase as specified by the flag and copies the result into the array pointed to by dststr. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of bytes for result string, not including the NULL terminator.

OCIWideCharStrcat()

Purpose

Appends the wide-character string pointed to by wsrcstr to the wide-character string pointed to by wdststr.

Syntax

size_t OCIWideCharStrcat ( dvoid            *hndl, 
                           OCIWchar         *wdststr, 
                           CONST OCIWchar   *wsrcstr );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wdststr (IN/OUT)

Pointer to the destination wchar string. The output buffer is NULL-terminated.

wsrcstr (IN)

Pointer to the source wide-character string to append.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of characters in the result string, not including the NULL terminator.

Related Functions

OCIWideCharStrncat()

OCIWideCharStrchr()

Purpose

Searches for the first occurrence of a specified character in a wide-character string.

Syntax

OCIWchar *OCIWideCharStrchr ( dvoid            *hndl, 
                              CONST OCIWchar   *wstr, 
                              OCIWchar         wc );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wstr (IN)

Pointer to the wchar string to search.

wc (IN)

wchar to search for.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

A wchar pointer if successful, otherwise a NULL pointer.

Related Functions

OCIWideCharStrrchr()

OCIWideCharStrcmp()

Purpose

Compares two wide-character strings by binary (based on wchar encoding value), linguistic, or case-insensitive comparison methods.

Syntax

int OCIWideCharStrcmp ( dvoid            *hndl, 
                        CONST OCIWchar   *wstr1, 
                        CONST OCIWchar   *wstr2, 
                        int              flag );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wstr1 (IN)

Pointer to a NULL-terminated wchar string.

wstr2 (IN)

Pointer to a NULL-terminated wchar string.

flag (IN)

Used to decide the comparison method. It can take one of the following values:

• OCI_NLS_BINARY: Binary comparison. This is the default value.
• OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale definition.

This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison. For example, use OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings linguistically without regard to case.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

• 0, if wstr1 = wstr2
• Positive, if wstr1 > wstr2
• Negative, if wstr1 < wstr2

Related Functions

OCIWideCharStrncmp()

OCIWideCharStrcpy()

Purpose

Copies a wide-character string into an array.

Syntax

size_t OCIWideCharStrcpy ( dvoid            *hndl, 
                           OCIWchar         *wdststr, 
                           CONST OCIWchar   *wsrcstr );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wdststr (OUT)

Pointer to the destination wchar buffer.The result string is NULL-terminated.

wsrcstr (IN)

Pointer to the source wchar string.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of characters copied not including the NULL terminator.

Related Functions

OCIWideCharStrncpy()

OCIWideCharStrlen()

Purpose

Returns the number of characters in a wide-character string.

Syntax

size_t OCIWideCharStrlen ( dvoid            *hndl, 
                           CONST OCIWchar   *wstr );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wstr (IN)

Pointer to the source wchar string.

Comments

Returns the number of characters in the wchar string pointed to by wstr, not including the NULL terminator. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of characters not including the NULL terminator.

OCIWideCharStrncat()

Purpose

Appends at most n characters from a wide-character string to the destination.

Syntax

size_t OCIWideCharStrncat ( dvoid            *hndl, 
                            OCIWchar         *wdststr, 
                            CONST OCIWchar   *wsrcstr, 
                            size_t           n );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wdststr (IN/OUT)

Pointer to the destination wchar string.

wsrcstr (IN)

Pointer to the source wchar string.

n (IN)

Number of characters from wsrcstr to append.

Comments

This function is similar to OCIWideCharStrcat(). At most n characters from wsrcstr are appended to wdststr. Note that the NULL terminator in wsrcstr stops appending. wdststr is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of characters in the result string, not including the NULL terminator.

Related Functions

OCIWideCharStrcat()

OCIWideCharStrncmp()

Purpose

Compares two wide-character strings by binary, linguistic, or case-sensitive methods. Each string has a specified length.

Syntax

int OCIWideCharStrncmp ( dvoid               *hndl, 
                         CONST OCIWchar      *wstr1, 
                         size_t              len1, 
                         CONST OCIWchar      *wstr2, 
                         size_t              len2, 
                         int                 flag );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wstr1 (IN)

Pointer to the first wchar string.

len1 (IN)

The length from the first string for comparison.

wstr2 (IN)

Pointer to the second wchar string.

len2 (IN)

The length from the second string for comparison.

flag (IN)

It is used to decide the comparison method. It can take one of the following values:

• OCI_NLS_BINARY: For the binary comparison, this is default value.
• OCI_NLS_LINGUISTIC: For the linguistic comparison specified in the locale.

This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison. For example, use OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings linguistically without regard to case.

Comments

This function is similar to OCIWideCharStrcmp(). It compares two wide-character strings by binary, linguistic, or case-insensitive comparison methods. At most len1 bytes from wstr1 and len2 bytes from wstr2 are compared. The NULL terminator is used in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

• 0, if wstr1 = wstr2
• Positive, if wstr1 > wstr2
• Negative, if wstr1 < wstr2

Related Functions

OCIWideCharStrcmp()

OCIWideCharStrncpy()

Purpose

Copies at most a n characters from a wide-character string into a destination.

Syntax

size_t OCIWideCharStrncpy ( dvoid            *hndl, 
                            OCIWchar         *wdststr, 
                            CONST OCIWchar   *wsrcstr, 
                            size_t           n );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wdststr (OUT)

Pointer to the destination wchar buffer.

wsrcstr (IN)

Pointer to the source wchar string.

n (IN)

Number of characters from wsrcstr to copy.

Comments

This function is similar to OCIWideCharStrcpy(), except that at most n characters are copied from the array pointed to by wsrcstr to the array pointed to by wdststr. Note that the NULL terminator in wdststr stops copying and the result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

The number of characters copied not including the NULL terminator.

Related Functions

OCIWideCharStrcpy()

OCIWideCharStrrchr()

Purpose

Searches for the last occurrence of a character in a wide-character string.

Syntax

OCIWchar *OCIWideCharStrrchr ( dvoid             *hndl, 
                               CONST OCIWchar    *wstr, 
                               OCIWchar          wc );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wstr (IN)

Pointer to the wchar string to search in.

wc (IN)

wchar to search for.

Comments

Searches for the last occurrence of wc in the wchar string pointed to by wstr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

wchar pointer if successful, otherwise a NULL pointer.

Related Functions

OCIWideCharStrchr()

OCIWideCharToLower()

Purpose

Converts the wide-character string specified by wc into the corresponding lowercase character, if it exists, in the specified locale. If no corresponding lowercase character exists, then it returns wc itself.

Syntax

OCIWchar OCIWideCharToLower ( dvoid       *hndl, 
                              OCIWchar    wc );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wc (IN)

wchar for lowercase conversion.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

A wchar.

Related Functions

OCIWideCharToUpper()

OCIWideCharToMultiByte()

Purpose

Converts an entire NULL-terminated wide-character string into a multibyte string.

Syntax

sword OCIWideCharToMultiByte ( dvoid            *hndl, 
                               OraText          *dst, 
                               CONST OCIWchar   *src, 
                               size_t           *rsize );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set of string.

dst (OUT)

Destination buffer for multibyte string. The output buffer is NULL-terminated.

src (IN)

Source wchar string to be converted.

srcsz (IN)

Length of source string in characters.

rsize (OUT)

Number of bytes written into destination buffer. If it is a NULL pointer, then nothing is returned.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Related Functions

OCIMultiByteToWideChar()

OCIWideCharToUpper()

Purpose

Converts the wide-character string specified by wc into the corresponding uppercase character, if it exists, in the specified locale. If no corresponding uppercase character exists, then it returns wc itself.

Syntax

OCIWchar OCIWideCharToUpper ( dvoid     *hndl, 
                              OCIWchar  wc );

Parameters

hndl (IN/OUT)

OCI environment or user session handle to determine the character set.

wc (IN)

wchar for uppercase conversion.

Comments

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

A wchar.

Related Functions

OCIWideCharToLower()