![]() | ![]() | ![]() | GNU Libidn API Reference Manual | ![]() |
---|
#define STRINGPREP_VERSION #define STRINGPREP_MAX_MAP_CHARS int stringprep (char *in, size_t maxlen, int flags, Stringprep_profile *profile); const char* stringprep_check_version (const char *req_version); int stringprep_unichar_to_utf8 (unsigned long c, char *outbuf); unsigned long stringprep_utf8_to_unichar (const char *p); unsigned long* stringprep_utf8_to_ucs4 (const char *str, ssize_t len, size_t *items_written); char* stringprep_ucs4_to_utf8 (unsigned long *str, ssize_t len, size_t *items_read, size_t *items_written); char* stringprep_utf8_nfkc_normalize (const char *str, ssize_t len); unsigned long* stringprep_ucs4_nfkc_normalize (unsigned long *str, ssize_t len); const char* stringprep_locale_charset (void); char* stringprep_convert (const char *str, const char *to_codeset, const char *from_codeset); char* stringprep_locale_to_utf8 (const char *str); char* stringprep_utf8_to_locale (const char *str);
#define STRINGPREP_VERSION "0.1.9"
String defined via CPP denoting the header file version number. Used together with stringprep_check_version() to verify header file and run-time library consistency.
int stringprep (char *in, size_t maxlen, int flags, Stringprep_profile *profile);
Prepare the input UTF-8 string according to the stringprep profile. Normally application programmers use stringprep profile macros such as stringprep_nameprep(), stringprep_kerberos5() etc instead of calling this function directly.
Since the stringprep operation can expand the string, maxlen indicate how large the buffer holding the string is. The flags are one of Stringprep_profile_flags, or 0. The profile indicates processing details, see the profile header files, such as stringprep_generic.h and stringprep_nameprep.h for two examples. Your application can define new profiles, possibly re-using the generic stringprep tables that always will be part of the library. Note that you must convert strings entered in the systems locale into UTF-8 before using this function.
in : | input/ouput array with string to prepare. |
maxlen : | maximum length of input/output array. |
flags : | optional stringprep profile flags. |
profile : | pointer to stringprep profile to use. |
Returns : | Returns 0 iff successful, or an error code. |
const char* stringprep_check_version (const char *req_version);
Check that the the version of the library is at minimum the requested one and return the version string; return NULL if the condition is not satisfied. If a NULL is passed to this function, no check is done, but the version string is simply returned.
See STRINGPREP_VERSION for a suitable req_version string.
req_version : | Required version number, or NULL. |
Returns : | Version string of run-time library, or NULL if the run-time library does not meet the required version number. |
int stringprep_unichar_to_utf8 (unsigned long c, char *outbuf);
Converts a single character to UTF-8.
Param1 : | |
outbuf : | output buffer, must have at least 6 bytes of space. If NULL, the length will be computed and returned and nothing will be written to outbuf. |
Returns : | number of bytes written |
unsigned long stringprep_utf8_to_unichar (const char *p);
Converts a sequence of bytes encoded as UTF-8 to a Unicode character. If p does not point to a valid UTF-8 encoded character, results are undefined.
p : | a pointer to Unicode character encoded as UTF-8 |
Returns : | the resulting character |
unsigned long* stringprep_utf8_to_ucs4 (const char *str, ssize_t len, size_t *items_written);
Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4, assuming valid UTF-8 input. This function does no error checking on the input.
str : | a UTF-8 encoded string |
len : | the maximum length of str to use. If len < 0, then the string is nul-terminated. |
items_written : | location to store the number of characters in the result, or NULL. |
Returns : | a pointer to a newly allocated UCS-4 string. This value must be freed with free(). |
char* stringprep_ucs4_to_utf8 (unsigned long *str, ssize_t len, size_t *items_read, size_t *items_written);
Convert a string from a 32-bit fixed width representation as UCS-4. to UTF-8. The result will be terminated with a 0 byte.
str : | a UCS-4 encoded string |
len : | the maximum length of str to use. If len < 0, then the string is terminated with a 0 character. |
items_read : | location to store number of characters read read, or NULL. |
items_written : | location to store number of bytes written or NULL. The value here stored does not include the trailing 0 byte. |
Returns : | a pointer to a newly allocated UTF-8 string. This value must be freed with free(). If an error occurs, NULL will be returned and error set. |
char* stringprep_utf8_nfkc_normalize (const char *str, ssize_t len);
Converts a string into canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. You should generally call g_utf8_normalize() before comparing two Unicode strings.
The normalization mode is NFKC (ALL COMPOSE). It standardizes differences that do not affect the text content, such as the above-mentioned accent representation. It standardizes the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same. It returns a result with composed forms rather than a maximally decomposed form.
str : | a UTF-8 encoded string. |
len : | length of str, in bytes, or -1 if str is nul-terminated. |
Returns : | a newly allocated string, that is the NFKC normalized form of str. |
unsigned long* stringprep_ucs4_nfkc_normalize (unsigned long *str, ssize_t len);
Converts UCS4 string into UTF-8 and runs stringprep_utf8_nfkc_normalize().
str : | a Unicode string. |
len : | length of str array, or -1 if str is nul-terminated. |
Returns : | a newly allocated Unicode string, that is the NFKC normalized form of str. |
const char* stringprep_locale_charset (void);
Returns : | Return the character set used by the system locale. It will never return NULL, but use "ASCII" as a fallback. |
char* stringprep_convert (const char *str, const char *to_codeset, const char *from_codeset);
Convert the string from one character set to another using the system's iconv() function.
str : | input zero-terminated string. |
to_codeset : | name of destination character set. |
from_codeset : | name of origin character set, as used by str. |
Returns : | Returns newly allocated zero-terminated string which is str transcoded into to_codeset. |
char* stringprep_locale_to_utf8 (const char *str);
Convert string encoded in the locale's character set into UTF-8 by using stringprep_convert().
str : | input zero terminated string. |
Returns : | Returns newly allocated zero-terminated string which is str transcoded into UTF-8. |
char* stringprep_utf8_to_locale (const char *str);
Convert string encoded in UTF-8 into the locale's character set by using stringprep_convert().
str : | input zero terminated string. |
Returns : | Returns newly allocated zero-terminated string which is str transcoded into the locale's character set. |
<<< GNU Libidn API Reference Manual | stringprep_generic >>> |