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 |
---|---|
Converts part of a multibyte string into the wide-character string. |
|
Converts a multibyte string into the specified case and copies the result into the destination array. |
|
Appends a multibyte string to the destination string. |
|
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. |
|
Copies a multibyte string into the destination array. It returns the number of bytes copied. |
|
Returns the number of bytes in a multibyte string. |
|
Appends at most n bytes from a multibyte string to the destination string. |
|
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. Each string is in the specified length. |
|
Copies a specified number of bytes of a multibyte string into the destination array. |
|
Returns the number of display positions occupied by the multibyte string within the range of n bytes. |
|
Converts a |
|
Converts part of a wide-character string to the multibyte string. |
|
Determines the number of bytes required for a wide-character in multibyte encoding. |
|
Converts a wide character string into the specified case and copies the result into the destination array. |
|
Appends a wide-character string to the destination string. |
|
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. |
|
Compares two wide-character strings by binary, linguistic, or case-insensitive comparison methods. |
|
Copies a wide-character string into a destination array. It returns the number of characters copied. |
|
Returns the number of characters in a wide-character string. |
|
Appends at most n characters from a wide-character string to the destination string. |
|
Compares two wide-character strings by binary, linguistic, or case-insensitive methods. Each string is a specified length. |
|
Copies at most n characters of a wide-character string into the destination array. |
|
Searches for the last occurrence of a character in a wide-character string. |
|
Converts a specified wide character into the corresponding lowercase character. |
|
Converts a |
|
Converts a specified wide character into the corresponding uppercase character. |
Converts part of a multibyte string into the wide-character string.
sword OCIMultiByteInSizeToWideChar ( dvoid *hndl, OCIWchar *dst, size_t dstsz, CONST OraText *src, size_t srcsz, size_t *rsize );
OCI environment or user session handle to determine the character set of the string.
Pointer to a destination buffer for wchar
. It can be NULL
pointer when dstsz
is zero.
Destination buffer size in number of characters. If it is zero, then this function returns the number of characters needed for the conversion.
Source string to be converted.
Length of source string in bytes.
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.
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.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
..
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
.
size_t OCIMultiByteStrCaseConversion ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr, ub4 flag );
OCI environment or user session handle.
Pointer to destination array. The result string is NULL
-terminated.
Pointer to source string.
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.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of bytes for result string, not including the NULL
terminator.
Appends a copy of the multibyte string pointed to by srcstr
to the end of the string pointed to by dststr
.
size_t OCIMultiByteStrcat ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr );
OCI environment or user session handle to determine the character set.
Pointer to the destination multibyte string for appending. The output buffer is NULL
-terminated.
Pointer to the source string to append.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of bytes in the result string, not including the NULL
terminator.
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods.
int OCIMultiByteStrcmp ( dvoid *hndl, CONST OraText *str1, CONST OraText *str2, int flag );
OCI environment or user session handle.
Pointer to a NULL
-terminated string.
Pointer to a NULL
-terminated string.
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.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
0, if str1 = str2
Positive, if str1 > str2
Negative, if str1 < str2
Copies the multibyte string pointed to by srcstr
into the array pointed to by dststr
.
size_t OCIMultiByteStrcpy ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr );
Pointer to the OCI environment or user session handle.
Pointer to the destination buffer.The output buffer is NULL
-terminated.
Pointer to the source multibyte string.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of bytes copied, not including the NULL
terminator.
Returns the number of bytes in the multibyte string pointed to by str
, not including the NULL
terminator.
size_t OCIMultiByteStrlen ( dvoid *hndl, CONST OraText *str );
Pointer to the OCI environment or user session handle.
Pointer to the source multibyte string.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of bytes, not including the NULL
terminator.
Appends a specified number of bytes from a multibyte string to a destination string.
size_t OCIMultiByteStrncat ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr, size_t n );
Pointer to OCI environment or user session handle.
Pointer to the destination multibyte string for appending.
Pointer to the source multibyte string to append.
The number of bytes from srcstr
to append.
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.
The number of bytes in the result string, not including the NULL
terminator
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. A length is specified for each string.
int OCIMultiByteStrncmp ( dvoid *hndl, CONST OraText *str1, size_t len1, OraText *str2, size_t len2, int flag );
OCI environment or user session handle.
Pointer to the first string.
The length of the first string to compare.
Pointer to the second string.
The length of the second string to compare.
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.
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.
0, if str1
= str2
Positive, if str1
> str2
Negative, if str1
< str2
Copies a multibyte string into an array.
size_t OCIMultiByteStrncpy ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr, size_t n );
Pointer to OCI environment or user session handle.
Pointer to the destination buffer.
Pointer to the source multibyte string.
The number of bytes from srcstr
to copy.
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.
The number of bytes in the resulting string, not including the NULL terminator.
Returns the number of display positions occupied by the multibyte string within the range of n
bytes.
size_t OCIMultiByteStrnDisplayLength ( dvoid *hndl, CONST OraText *str1, size_t n );
OCI environment or user session handle.
Pointer to a multibyte string.
The number of bytes to examine.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of display positions.
Converts an entire NULL
-terminated string into the wide-character string.
sword OCIMultiByteToWideChar ( dvoid *hndl, OCIWchar *dst, CONST OraText *src, size_t *rsize );
OCI environment or user session handle to determine the character set of string
Destination buffer for wchar
.
Source string to be converted.
Number of characters converted including NULL
terminator. If it is a NULL
pointer, then nothing is returned.
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.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
.
Converts part of a wide-character string to multibyte format.
sword OCIWideCharInSizeToMultiByte ( dvoid *hndl, OraText *dst, size_t dstsz, CONST OCIWchar *src, size_t srcsz, size_t *rsize );
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.
Destination buffer size in bytes. If it is zero,then the function returns the size in bytes need for converted string.
Source wchar
string to be converted.
Length of source string in characters.
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.
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.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
.
Determines the number of bytes required for a wide character in multibyte encoding.
size_t OCIWideCharMultiByteLength ( dvoid *hndl, OCIWchar wc );
OCI environment or user session handle to determine the character set.
wchar
character.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of bytes required for the wide character.
Converts a wide-character string into a specified case and copies the result into the destination array.
size_t OCIMultiByteStrCaseConversion ( dvoid *hndl, OraText *dststr, CONST OraText *srcstr, ub4 flag );
OCI environment or user session handle.
Pointer to destination array.
Pointer to source string.
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.
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.
The number of bytes for result string, not including the NULL
terminator.
Appends the wide-character string pointed to by wsrcstr
to the wide-character string pointed to by wdststr
.
size_t OCIWideCharStrcat ( dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr );
OCI environment or user session handle to determine the character set.
Pointer to the destination wchar
string. The output buffer is NULL
-terminated.
Pointer to the source wide-character string to append.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of characters in the result string, not including the NULL
terminator.
Searches for the first occurrence of a specified character in a wide-character string.
OCIWchar *OCIWideCharStrchr ( dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc );
OCI environment or user session handle to determine the character set.
Pointer to the wchar
string to search.
wchar
to search for.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
A wchar
pointer if successful, otherwise a NULL
pointer.
Compares two wide-character strings by binary (based on wchar
encoding value), linguistic, or case-insensitive comparison methods.
int OCIWideCharStrcmp ( dvoid *hndl, CONST OCIWchar *wstr1, CONST OCIWchar *wstr2, int flag );
OCI environment or user session handle to determine the character set.
Pointer to a NULL
-terminated wchar
string.
Pointer to a NULL
-terminated wchar
string.
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.
The UNICODE_BINARY sort method cannot be used with OCIWideCharStrcmp()
to perform a linguistic comparison of supplied wide character arguments.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
0, if wstr1 = wstr2
Positive, if wstr1 > wstr2
Negative, if wstr1 < wstr2
Copies a wide-character string into an array.
size_t OCIWideCharStrcpy ( dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr );
OCI environment or user session handle to determine the character set.
Pointer to the destination wchar
buffer.The result string is NULL
-terminated.
Pointer to the source wchar
string.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
The number of characters copied not including the NULL
terminator.
Returns the number of characters in a wide-character string.
size_t OCIWideCharStrlen ( dvoid *hndl, CONST OCIWchar *wstr );
OCI environment or user session handle to determine the character set.
Pointer to the source wchar
string.
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.
The number of characters not including the NULL
terminator.
Appends at most n
characters from a wide-character string to the destination.
size_t OCIWideCharStrncat ( dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr, size_t n );
OCI environment or user session handle to determine the character set.
Pointer to the destination wchar
string.
Pointer to the source wchar
string.
Number of characters from wsrcstr
to append.
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.
The number of characters in the result string, not including the NULL
terminator.
Compares two wide-character strings by binary, linguistic, or case-sensitive methods. Each string has a specified length.
int OCIWideCharStrncmp ( dvoid *hndl, CONST OCIWchar *wstr1, size_t len1, CONST OCIWchar *wstr2, size_t len2, int flag );
OCI environment or user session handle to determine the character set.
Pointer to the first wchar
string.
The length from the first string for comparison.
Pointer to the second wchar
string.
The length from the second string for comparison.
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.
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.
The UNICODE_BINARY sort method cannot be used with OCIWideCharStrncmp()
to perform a linguistic comparison of supplied wide character arguments.
0, if wstr1 = wstr2
Positive, if wstr1 > wstr2
Negative, if wstr1 < wstr2
Copies at most a n
characters from a wide-character string into a destination.
size_t OCIWideCharStrncpy ( dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr, size_t n );
OCI environment or user session handle to determine the character set.
Pointer to the destination wchar
buffer.
Pointer to the source wchar
string.
Number of characters from wsrcstr
to copy.
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.
The number of characters copied not including the NULL
terminator.
Searches for the last occurrence of a character in a wide-character string.
OCIWchar *OCIWideCharStrrchr ( dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc );
OCI environment or user session handle to determine the character set.
Pointer to the wchar
string to search in.
wchar
to search for.
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.
wchar
pointer if successful, otherwise a NULL
pointer.
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.
OCIWchar OCIWideCharToLower ( dvoid *hndl, OCIWchar wc );
OCI environment or user session handle to determine the character set.
wchar
for lowercase conversion.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
A wchar
.
Converts an entire NULL
-terminated wide-character string into a multibyte string.
sword OCIWideCharToMultiByte ( dvoid *hndl, OraText *dst, CONST OCIWchar *src, size_t *rsize );
OCI environment or user session handle to determine the character set of string.
Destination buffer for multibyte string. The output buffer is NULL
-terminated.
Source wchar
string to be converted.
Length of source string in characters.
Number of bytes written into destination buffer. If it is a NULL
pointer, then nothing is returned.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
.
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.
OCIWchar OCIWideCharToUpper ( dvoid *hndl, OCIWchar wc );
OCI environment or user session handle to determine the character set.
wchar
for uppercase conversion.
If OCI_UTF16ID
is specified for SQL CHAR
data in the OCIEnvNlsCreate()
function, then this function produces an error.
A wchar
.