Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

ustring.h File Reference

#include "unicode/utypes.h"

Go to the source code of this file.

Defines

#define U_STRING_DECL(var, cs, length)    static const wchar_t var[(length)+1]={ L ## cs }
 Unicode String literals in C. More...

#define U_STRING_INIT(var, cs, length)

Functions

U_CAPI int32_t U_EXPORT2 u_strlen (const UChar *s)
 Determine the length of an array of UChar. More...

U_CAPI UChar* U_EXPORT2 u_strcat (UChar *dst, const UChar *src)
 Concatenate two ustrings. More...

U_CAPI UChar* U_EXPORT2 u_strncat (UChar *dst, const UChar *src, int32_t n)
 Concatenate two ustrings. More...

U_CAPI UChar* U_EXPORT2 u_strchr (const UChar *s, UChar c)
 Find the first occurrence of a specified character in a ustring. More...

U_CAPI UChar* U_EXPORT2 u_strstr (const UChar *s, const UChar *substring)
 Find the first occurrence of a substring in a string. More...

U_CAPI UChar* U_EXPORT2 u_strchr32 (const UChar *s, UChar32 c)
 Find the first occurence of a specified code point in a string. More...

U_CAPI int32_t U_EXPORT2 u_strcmp (const UChar *s1, const UChar *s2)
 Compare two ustrings for bitwise equality. More...

U_CAPI int32_t U_EXPORT2 u_strncmp (const UChar *ucs1, const UChar *ucs2, int32_t n)
 Compare two ustrings for bitwise equality. More...

U_CAPI UChar* U_EXPORT2 u_strcpy (UChar *dst, const UChar *src)
 Copy a ustring. More...

U_CAPI UChar* U_EXPORT2 u_strncpy (UChar *dst, const UChar *src, int32_t n)
 Copy a ustring. More...

U_CAPI UChar* U_EXPORT2 u_uastrcpy (UChar *ucs1, const char *s2 )
 Copy a byte string encoded in the default codepage to a ustring. More...

U_CAPI UChar* U_EXPORT2 u_uastrncpy (UChar *ucs1, const char *s2, int32_t n)
 Copy a byte string encoded in the default codepage to a ustring. More...

U_CAPI char* U_EXPORT2 u_austrcpy (char *s1, const UChar *us2 )
 Copy ustring to a byte string encoded in the default codepage. More...

U_CAPI int32_t U_EXPORT2 u_unescape (const char *src, UChar *dest, int32_t destCapacity)
 Unescape a string of characters and write the resulting Unicode characters to the destination buffer. More...

U_CDECL_END U_CAPI UChar32
U_EXPORT2 
u_unescapeAt (UNESCAPE_CHAR_AT charAt, int32_t *offset, int32_t length, void *context)
 Unescape a single sequence. More...

U_CAPI int32_t U_EXPORT2 u_strToUpper (const UChar *src, int32_t srcLength, UChar *dest, int32_t destCapacity, const char *locale, UErrorCode *pErrorCode)
 Uppercase the characters in a string. More...

U_CAPI int32_t U_EXPORT2 u_strToLower (const UChar *src, int32_t srcLength, UChar *dest, int32_t destCapacity, const char *locale, UErrorCode *pErrorCode)
 Lowercase the characters in a string. More...


Variables

U_CDECL_BEGIN typedef UChar (* UNESCAPE_CHAR_AT )(int32_t offset, void *context)
 Callback function for u_unescapeAt() that returns a character of the source text given an offset and a context pointer. More...


Define Documentation

#define U_STRING_DECL( var, cs, length )   static const wchar_t var[(length)+1]={ L ## cs }
 

Unicode String literals in C.

We need one macro to declare a variable for the string and to statically preinitialize it if possible, and a second macro to dynamically intialize such a string variable if necessary.

The macros are defined for maximum performance. They work only for strings that contain "invariant characters", i.e., only latin letters, digits, and some punctuation. See utypes.h for details.

A pair of macros for a single string must be used with the same parameters. The string parameter must be a C string literal. The length of the string, not including the terminating NUL, must be specified as a constant. The U_STRING_DECL macro should be invoked exactly once for one such string variable before it is used.

Usage:

     U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
     U_STRING_DECL(ustringVar2, "jumps 5%", 8);
     static UBool didInit=FALSE;
   
     int32_t function() {
         if(!didInit) {
             U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
             U_STRING_INIT(ustringVar2, "jumps 5%", 8);
             didInit=TRUE;
         }
         return u_strcmp(ustringVar1, ustringVar2);
     }
 

Definition at line 229 of file ustring.h.

#define U_STRING_INIT( var, cs, length )
 

Definition at line 230 of file ustring.h.


Function Documentation

U_CAPI char *U_EXPORT2 u_austrcpy ( char * s1,
const UChar * us2 )
 

Copy ustring to a byte string encoded in the default codepage.

Adds a null terminator. performs a UChar to host byte conversion

Parameters:
dst   The destination string.
src   The source string.
Returns:
A pointer to dst.
Stable:

U_CAPI int32_t U_EXPORT2 u_strToLower ( const UChar * src,
int32_t srcLength,
UChar * dest,
int32_t destCapacity,
const char * locale,
UErrorCode * pErrorCode )
 

Lowercase the characters in a string.

Casing is locale-dependent and context-sensitive. The result may be longer or shorter than the original.

Parameters:
src   The original string
srcLength   The length of the original string. If -1, then src must be zero-terminated.
dest   A buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacity   The size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
locale   The locale to consider, or NULL for none.
pErrorCode   Must be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns:
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Unimplemented

U_CAPI int32_t U_EXPORT2 u_strToUpper ( const UChar * src,
int32_t srcLength,
UChar * dest,
int32_t destCapacity,
const char * locale,
UErrorCode * pErrorCode )
 

Uppercase the characters in a string.

Casing is locale-dependent and context-sensitive. The result may be longer or shorter than the original.

Parameters:
src   The original string
srcLength   The length of the original string. If -1, then src must be zero-terminated.
dest   A buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacity   The size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
locale   The locale to consider, or NULL for none.
pErrorCode   Must be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns:
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Unimplemented

U_CAPI UChar *U_EXPORT2 u_strcat ( UChar * dst,
const UChar * src )
 

Concatenate two ustrings.

Appends a copy of src, including the null terminator, to dst. The initial copied character from src overwrites the null terminator in dst.

Parameters:
dst   The destination string.
src   The source string.
Returns:
A pointer to dst.
Stable:

U_CAPI UChar *U_EXPORT2 u_strchr ( const UChar * s,
UChar c )
 

Find the first occurrence of a specified character in a ustring.

Parameters:
s   The string to search.
c   The character to find.
Returns:
A pointer to the first occurrence of c in s, or a null pointer if s does not contain c.
Stable:

U_CAPI UChar *U_EXPORT2 u_strchr32 ( const UChar * s,
UChar32 c )
 

Find the first occurence of a specified code point in a string.

Parameters:
s   The string to search.
c   The code point (0..0x10ffff) to find.
Returns:
A pointer to the first occurrence of c in s, or a null pointer if there is no such character. If c is represented with several UChars, then the returned pointer will point to the first of them.
Draft:

U_CAPI int32_t U_EXPORT2 u_strcmp ( const UChar * s1,
const UChar * s2 )
 

Compare two ustrings for bitwise equality.

Parameters:
s1   A string to compare.
s2   A string to compare.
Returns:
0 if s1 and s2 are bitwise equal; a negative value if s1 is bitwise less than s2,/TT>; a positive value if s1 is bitwise greater than s2,/TT>.
Stable:

U_CAPI UChar *U_EXPORT2 u_strcpy ( UChar * dst,
const UChar * src )
 

Copy a ustring.

Adds a null terminator.

Parameters:
dst   The destination string.
src   The source string.
Returns:
A pointer to dst.
Stable:

U_CAPI int32_t U_EXPORT2 u_strlen ( const UChar * s )
 

Determine the length of an array of UChar.

Parameters:
s   The array of UChars, NULL (U+0000) terminated.
Returns:
The number of UChars in chars, minus the terminator.
Stable:

U_CAPI UChar *U_EXPORT2 u_strncat ( UChar * dst,
const UChar * src,
int32_t n )
 

Concatenate two ustrings.

Appends at most n characters from src to dst. Adds a null terminator.

Parameters:
dst   The destination string.
src   The source string.
n   The maximum number of characters to compare.
Returns:
A pointer to dst.
Stable:

U_CAPI int32_t U_EXPORT2 u_strncmp ( const UChar * ucs1,
const UChar * ucs2,
int32_t n )
 

Compare two ustrings for bitwise equality.

Compares at most n characters.

Parameters:
s1   A string to compare.
s2   A string to compare.
n   The maximum number of characters to compare.
Returns:
0 if s1 and s2 are bitwise equal; a negative value if s1 is bitwise less than s2,/TT>; a positive value if s1 is bitwise greater than s2,/TT>.
Stable:

U_CAPI UChar *U_EXPORT2 u_strncpy ( UChar * dst,
const UChar * src,
int32_t n )
 

Copy a ustring.

Copies at most n characters. The result will be null terminated if the length of src is less than n.

Parameters:
dst   The destination string.
src   The source string.
n   The maximum number of characters to copy.
Returns:
A pointer to dst.
Stable:

U_CAPI UChar *U_EXPORT2 u_strstr ( const UChar * s,
const UChar * substring )
 

Find the first occurrence of a substring in a string.

Parameters:
s   The string to search.
Returns:
A pointer to the first occurrence of substring in s, or a null pointer if substring is not in s.

U_CAPI UChar *U_EXPORT2 u_uastrcpy ( UChar * ucs1,
const char * s2 )
 

Copy a byte string encoded in the default codepage to a ustring.

Adds a null terminator. performs a host byte to UChar conversion

Parameters:
dst   The destination string.
src   The source string.
Returns:
A pointer to dst.
Stable:

U_CAPI UChar *U_EXPORT2 u_uastrncpy ( UChar * ucs1,
const char * s2,
int32_t n )
 

Copy a byte string encoded in the default codepage to a ustring.

Copies at most n characters. The result will be null terminated if the length of src is less than n. performs a host byte to UChar conversion

Parameters:
dst   The destination string.
src   The source string.
n   The maximum number of characters to copy.
Returns:
A pointer to dst.
Stable:

U_CAPI int32_t U_EXPORT2 u_unescape ( const char * src,
UChar * dest,
int32_t destCapacity )
 

Unescape a string of characters and write the resulting Unicode characters to the destination buffer.

The following escape sequences are recognized:

\uhhhh 4 hex digits; h in [0-9A-Fa-f] \Uhhhhhhhh 8 hex digits \xhh 1-2 hex digits \ooo 1-3 octal digits; o in [0-7]

as well as the standard ANSI C escapes:

=> U+0007, => U+0008, \t => U+0009,
=> U+000A, \v => U+000B, \f => U+000C, \r => U+000D, \" => U+0022, \' => U+0027, \? => U+003F, \ => U+005C

Anything else following a backslash is generically escaped. For example, "[a\-z]" returns "[a-z]".

If an escape sequence is ill-formed, this method returns an empty string. An example of an ill-formed sequence is "\u" followed by fewer than 4 hex digits.

The above characters are recognized in the compiler's codepage, that is, they are coded as 'u', '\', etc. Characters that are not parts of escape sequences are converted using u_charsToUChars().

This function is similar to UnicodeString::unescape() but not identical to it. The latter takes a source UnicodeString, so it does escape recognition but no conversion.

Parameters:
src   a zero-terminated string of invariant characters
dest   pointer to buffer to receive converted and unescaped text and, if there is room, a zero terminator. May be NULL for preflighting, in which case no UChars will be written, but the return value will still be valid. On error, an empty string is stored here (if possible).
destCapacity   the number of UChars that may be written at dest. Ignored if dest == NULL.
Returns:
the capacity required to fully convert all of the source text, including the zero terminator, or 0 on error.
See also:
u_unescapeAt , UnicodeString::unescape() , UnicodeString::unescapeAt()

U_CDECL_END U_CAPI UChar32 U_EXPORT2 u_unescapeAt ( UNESCAPE_CHAR_AT charAt,
int32_t * offset,
int32_t length,
void * context )
 

Unescape a single sequence.

The character at offset-1 is assumed (without checking) to be a backslash. This method takes a callback pointer to a function that returns the UChar at a given offset. By varying this callback, ICU functions are able to unescape char* strings, UnicodeString objects, and UFILE pointers.

If offset is out of range, or if the escape sequence is ill-formed, (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape() for a list of recognized sequences.

Parameters:
charAt   callback function that returns a UChar of the source text given an offset and a context pointer.
offset   pointer to the offset that will be passed to charAt. The offset value will be updated upon return to point after the last parsed character of the escape sequence. On error the offset is unchanged.
length   the number of characters in the source text. The last character of the source text is considered to be at offset length-1.
context   an opaque pointer passed directly into charAt.
Returns:
the character represented by the escape sequence at offset, or (UChar32)0xFFFFFFFF on error.
See also:
u_unescape() , UnicodeString::unescape() , UnicodeString::unescapeAt()


Variable Documentation

U_CDECL_BEGIN typedef UChar(* UNESCAPE_CHAR_AT)(int32_t offset,void *context)
 

Callback function for u_unescapeAt() that returns a character of the source text given an offset and a context pointer.

The context pointer will be whatever is passed into u_unescapeAt().

See also:
u_unescapeAt

Definition at line 295 of file ustring.h.


Generated at Fri Dec 15 12:12:57 2000 for ICU 1.7 by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000