Unicode routines

_ustrdup — Duplicates a string with a custom memory allocator.
do_uconvert — Converts a string to another encoding format.
empty_string — Universal string NULL terminator.
get_uformat — Finds out what text encoding format is currently selected.
need_uconvert — Tells if a string requires encoding conversion.
register_uformat — Installs handler functions for a new text encoding format.
set_ucodepage — Sets 8-bit to Unicode conversion tables.
set_uformat — Set the global current text encoding format.
uatof — Converts a string into a double.
uconvert — High level string encoding conversion wrapper.
uconvert_ascii — Converts string from ASCII into the current format.
uconvert_size — Number of bytes needed to store a string after conversion.
uconvert_toascii — Converts strings from the current format into ASCII.
ucwidth — Low level helper function for testing Unicode text data.
ugetat — Finds out the value of a character in a string.
ugetc — Low level helper function for reading Unicode text data.
ugetx — Low level helper function for reading Unicode text data.
ugetxc — Low level helper function for reading Unicode text data.
uinsert — Inserts a character in a string.
uisdigit — Tells if a character is a digit.
uisok — Low level helper function for testing Unicode text data.
uisspace — Tells if a character is whitespace.
uoffset — Finds the offset of a character in a string.
uremove — Removes a character from a string.
usetat — Replaces a character in a string.
usetc — Low level helper function for writing Unicode text data.
usprintf — Writes formatted data into a buffer.
ustrcat — Concatenates a string to another one.
ustrchr — Finds the first occurrence of a character in a string.
ustrcmp — Compares two strings.
ustrcpy — Copies a string into another one.
ustrdup — Duplicates a string.
ustrerror — Returns a string describing errno.
ustricmp — Compares two strings ignoring case.
ustrlen — Tells the number of characters in a string.
ustrlwr — Replaces all letters with lower case.
ustrncat — Concatenates a string to another one, specifying size.
ustrncmp — Compares up to n letters of two strings.
ustrncpy — Copies a string into another one, specifying size.
ustrnicmp — Compares up to n letters of two strings ignoring case.
ustrpbrk — Finds the first character that matches any in a set.
ustrrchr — Finds the last occurrence of a character in a string.
ustrsize — Size of the string in bytes without null terminator.
ustrsizez — Size of the string in bytes including null terminator.
ustrstr — Finds the first occurrence of a string in another one.
ustrtod — Converts a string into a floating point number.
ustrtok — Retrieves tokens from a string.
ustrtok_r — Reentrant function to retrieve tokens from a string.
ustrtol — Converts a string into an integer.
ustrupr — Replaces all letters with upper case.
ustrzcat — Concatenates a string to another one, specifying size.
ustrzcpy — Copies a string into another one, specifying size.
ustrzncat — Concatenates a string to another one, specifying size.
ustrzncpy — Copies a string into another one, specifying size.
uszprintf — Writes formatted data into a buffer, specifying size.
utolower — Converts a letter to lower case.
utoupper — Converts a letter to upper case.
uvsprintf — Writes formatted data into a buffer, using variable arguments.
uvszprintf — Writes formatted data into a buffer, using size and variable arguments.
uwidth — Low level helper function for testing Unicode text data.
uwidth_max — Number of bytes a character can occupy.

Allegro can manipulate and display text using any character values from 0 right up to 2^32-1 (although the current implementation of the grabber can only create fonts using characters up to 2^16-1). You can choose between a number of different text encoding formats, which controls how strings are stored and how Allegro interprets strings that you pass to it. This setting affects all aspects of the system: whenever you see a function that returns a char * type, or that takes a char * as an argument, that text will be in whatever format you have told Allegro to use.

By default, Allegro uses UTF-8 encoded text (U_UTF8). This is a variable-width format, where characters can occupy anywhere from one to four bytes. The nice thing about it is that characters ranging from 0-127 are encoded directly as themselves, so UTF-8 is upwardly compatible with 7-bit ASCII ("Hello, World!" means the same thing regardless of whether you interpret it as ASCII or UTF-8 data). Any character values above 128, such as accented vowels, the UK currency symbol, and Arabic or Chinese characters, will be encoded as a sequence of two or more bytes, each in the range 128-255. This means you will never get what looks like a 7-bit ASCII character as part of the encoding of a different character value, which makes it very easy to manipulate UTF-8 strings.

There are a few editing programs that understand UTF-8 format text files. Alternatively, you can write your strings in plain ASCII or 16-bit Unicode formats, and then use the Allegro textconv program to convert them into UTF-8.

If you prefer to use some other text format, you can set Allegro to work with normal 8-bit ASCII (U_ASCII), or 16-bit Unicode (U_UNICODE) instead, or you can provide some handler functions to make it support whatever other text encoding you like (for example it would be easy to add support for 32 bit UCS-4 characters, or the Chinese GB-code format).

There is some limited support for alternative 8-bit codepages, via the U_ASCII_CP mode. This is very slow, so you shouldn't use it for serious work, but it can be handy as an easy way to convert text between different codepages. By default the U_ASCII_CP mode is set up to reduce text to a clean 7-bit ASCII format, trying to replace any accented vowels with their simpler equivalents (this is used by the allegro_message() function when it needs to print an error report onto a text mode DOS screen). If you want to work with other codepages, you can do this by passing a character mapping table to the set_ucodepage() function.

Note that you can use the Unicode routines before you call install_allegro() or allegro_init(). If you want to work in a text mode other than UTF-8, it is best to set it with set_uformat() just before you call these.

void set_uformat(int type);

Sets the current text encoding format. This will affect all parts of Allegro, wherever you see a function that returns a char *, or takes a char * as a parameter. `type' should be one of these values:

      U_ASCII     - fixed size, 8-bit ASCII characters
      U_ASCII_CP  - alternative 8-bit codepage (see set_ucodepage())
      U_UNICODE   - fixed size, 16-bit Unicode characters
      U_UTF8      - variable size, UTF-8 format Unicode characters

Although you can change the text format on the fly, this is not a good idea. Many strings, for example the names of your hardware drivers and any language translations, are loaded when you call allegro_init(), so if you change the encoding format after this, they will be in the wrong format, and things will not work properly. Generally you should only call set_uformat() once, before allegro_init(), and then leave it on the same setting for the duration of your program.

See also: get_uformat, register_uformat, set_ucodepage, set_uformat, uconvert, ustrsize, ugetc, ugetx, usetc, uwidth, ucwidth, uisok, uoffset, ugetat, usetat, uinsert, uremove, allegro_init.

Examples using this: exunicod.

int get_uformat(void);

Finds out what text encoding format is currently selected. This function is probably useful only if you are writing an Allegro addon dealing with text strings and you use a different codepath for each possible format. Example:

      switch(get_uformat()) {
         case U_ASCII:
            do_something();
            break;
         case U_UTF8:
            do_something_else();
            break;
         ...
      }

Return value: Returns the currently selected text encoding format. See the documentation of set_uformat() for a list of encoding formats.

See also: set_uformat.

void register_uformat(int type, int (*u_getc)(const char *s), int (*u_getx)(char **s), int (*u_setc)(char *s, int c), int (*u_width)(const char *s), int (*u_cwidth)(int c), int (*u_isok)(int c));

Installs a set of custom handler functions for a new text encoding format. The `type' is the ID code for your new format, which should be a 4-character string as produced by the AL_ID() macro, and which can later be passed to functions like set_uformat() and uconvert(). The function parameters are handlers that implement the character access for your new type: see below for details of these.

See also: set_uformat, uconvert, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.

void set_ucodepage(const unsigned short *table, const unsigned short *extras);

When you select the U_ASCII_CP encoding mode, a set of tables are used to convert between 8-bit characters and their Unicode equivalents. You can use this function to specify a custom set of mapping tables, which allows you to support different 8-bit codepages.

The `table' parameter points to an array of 256 shorts, which contain the Unicode value for each character in your codepage. The `extras' parameter, if not NULL, points to a list of mapping pairs, which will be used when reducing Unicode data to your codepage. Each pair consists of a Unicode value, followed by the way it should be represented in your codepage. The list is terminated by a zero Unicode value. This allows you to create a many->one mapping, where many different Unicode characters can be represented by a single codepage value (eg. for reducing accented vowels to 7-bit ASCII).

Allegro will use the `table' parameter when it needs to convert an ASCII string to an Unicode string. But when Allegro converts an Unicode string to ASCII, it will use both parameters. First, it will loop through the `table' parameter looking for an index position pointing at the Unicode value it is trying to convert (ie. the `table' parameter is also used for reverse matching). If that fails, the `extras' list is used. If that fails too, Allegro will put the character `^', giving up the conversion.

Note that Allegro comes with a default `table' and `extras' parameters set internally. The default `table' will convert 8-bit characters to `^'. The default `extras' list reduces Latin-1 and Extended-A characters to 7 bits in a sensible way (eg. an accented vowel will be reduced to the same vowel without the accent).

See also: set_uformat.

int need_uconvert(const char *s, int type, int newtype);

Given a pointer to a string (`s'), a description of the type of the string (`type'), and the type that you would like this string to be converted into (`newtype'), this function tells you whether any conversion is required. No conversion will be needed if `type' and `newtype' are the same, or if one type is ASCII, the other is UTF-8, and the string contains only character values less than 128. As a convenience shortcut, you can pass the value U_CURRENT as either of the type parameters, to represent whatever text encoding format is currently selected. Example:

      if (need_uconvert(text, U_UTF8, U_CURRENT)) {
         /* conversion is required */
      }

Return value: Returns non-zero if any conversion is required or zero otherwise.

See also: set_uformat, get_uformat, do_uconvert, uconvert.

int uconvert_size(const char *s, int type, int newtype);

Finds out how many bytes are required to store the specified string `s' after a conversion from `type' to `newtype', including the mandatory zero terminator of the string. You can use U_CURRENT for either `type' or `newtype' as a shortcut to represent whatever text encoding format is currently selected. Example:

      length = uconvert_size(old_string, U_CURRENT, U_UNICODE);
      new_string = malloc(length);
      ustrcpy(new_string, old_string);

Return value: Returns the number of bytes required to store the string after conversion.

See also: need_uconvert, do_uconvert.

void do_uconvert(const char *s, int type, char *buf, int newtype, int size);

Converts the specified string `s' from `type' to `newtype', storing at most `size' bytes into the output `buf'. The type parameters can use the value U_CURRENT as a shortcut to represent the currently selected encoding format. Example:

      char temp_string[256];
      do_uconvert(input_string, U_CURRENT, temp_string, U_ASCII, 256);

Note that, even for empty strings, your destination string must have at least enough bytes to store the terminating null character of the string, and your parameter size must reflect this. Otherwise, the debug version of Allegro will abort at an assertion, and the release version of Allegro will overrun the destination buffer.

See also: uconvert.

char *uconvert(const char *s, int type, char *buf, int newtype, int size);

Higher level function running on top of do_uconvert(). This function converts the specified string `s' from `type' to `newtype', storing at most `size' bytes into the output `buf' (including the terminating null character), but it checks before doing the conversion, and doesn't bother if the string formats are already the same (either both types are equal, or one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII characters).

As a convenience, if `buf' is NULL it will convert the string into an internal static buffer and the `size' parameter will be ignored. You should be wary of using this feature, though, because that buffer will be overwritten the next time this routine is called, so don't expect the data to persist across any other library calls. The static buffer may hold less than 1024 characters, so you won't be able to convert large chunks of text. Example:

      char *p = uconvert(input_string, U_CURRENT, buffer, U_ASCII, 256);

Return value: Returns a pointer to `buf' (or the static buffer if you used NULL) if a conversion was performed. Otherwise returns a copy of `s'. In any cases, you should use the return value rather than assuming that the string will always be moved to `buf'.

See also: set_uformat, need_uconvert, uconvert, uconvert_ascii, uconvert_toascii, do_uconvert.

char *uconvert_ascii(const char *s, char buf[]);

Helper macro for converting strings from ASCII into the current encoding format. Expands to uconvert(s, U_ASCII, buf, U_CURRENT, sizeof(buf)).

See also: uconvert.

Examples using this: exunicod.

char *uconvert_toascii(const char *s, char buf[]);

Helper macro for converting strings from the current encoding format into ASCII. Expands to uconvert(s, U_CURRENT, buf, U_ASCII, sizeof(buf)).

See also: uconvert.

extern char empty_string[];

You can't just rely on "" to be a valid empty string in any encoding format. This global buffer contains a number of consecutive zeros, so it will be a valid empty string no matter whether the program is running in ASCII, Unicode, or UTF-8 mode.

int ugetc(const char *s);

Low level helper function for reading Unicode text data. Example:

      int first_unicode_letter = ugetc(text_string);

Return value: Returns the character pointed to by `s' in the current encoding format.

See also: ugetx, usetc, uwidth, ucwidth, uisok.

int ugetx(char **s);

int ugetxc(const char **s);

Low level helper function for reading Unicode text data. ugetxc is provided for working with pointer-to-pointer-to-const char data. Example:

      char *p = string;
      int first_letter, second_letter, third_letter;
      first_letter = ugetx(&p);
      second_letter = ugetx(&p);
      third_letter = ugetx(&p);

Return value: Returns the character pointed to by `s' in the current encoding format, and advances the pointer to the next character after the one just returned.

See also: ugetc, usetc, uwidth, ucwidth, uisok.

int usetc(char *s, int c);

Low level helper function for writing Unicode text data. Writes the character `c' to the address pointed to by `s'.

Return value: Returns the number of bytes written, which is equal to the width of the character in the current encoding format.

See also: ugetc, ugetx, uwidth, ucwidth, uisok.

int uwidth(const char *s);

Low level helper function for testing Unicode text data.

Return value: Returns the number of bytes occupied by the first character of the specified string, in the current encoding format.

See also: uwidth_max, ugetc, ugetx, usetc, ucwidth, uisok.

int ucwidth(int c);

Low level helper function for testing Unicode text data.

Return value: Returns the number of bytes that would be occupied by the specified character value, when encoded in the current format.

See also: uwidth_max, ugetc, ugetx, usetc, uwidth, uisok.

int uisok(int c);

Low level helper function for testing Unicode text data. Finds out if the character value `c' can be encoded correctly in the current format, which can be useful if you are converting from Unicode to ASCII or another encoding format where the range of valid characters is limited.

Return value: Returns non-zero if the value can be correctly encoded, zero otherwise.

See also: ugetc, ugetx, usetc, uwidth, ucwidth.

int uoffset(const char *s, int index);

Finds out the offset (in bytes from the start of the string) of the character at the specified `index' in the string `s'. A zero `index' parameter will return the first character of the string. If `index' is negative, it counts backward from the end of the string, so an `index' of `-1' will return an offset to the last character. Example:

      int from_third_letter = uoffset(text_string, 2);

Return value: Returns the offset in bytes to the specified character.

See also: ugetat, usetat, uinsert, uremove.

int ugetat(const char *s, int index);

Finds out the character value at the specified `index' in the string. A zero `index' parameter will return the first character of the string. If `index' is negative, it counts backward from the end of the string, so an `index' of `-1' will return the last character of the string. Example:

      int third_letter = ugetat(text_string, 2);

Return value: Returns the character value at the specified index in the string.

See also: uoffset, usetat, uinsert, uremove.

int usetat(char *s, int index, int c);

Replaces the character at the specified index in the string with value `c', handling any adjustments for variable width data (ie. if `c' encodes to a different width than the previous value at that location). If `index' is negative, it counts backward from the end of the string. Example:

      usetat(text_string, 2, letter_a);

Return value: Returns the number of bytes by which the trailing part of the string was moved. This is of interest only with text encoding formats where characters have a variable length, like UTF-8.

See also: uoffset, ugetat, uinsert, uremove.

int uinsert(char *s, int index, int c);

Inserts the character `c' at the specified `index' in the string, sliding the rest of the data along to make room. If `index' is negative, it counts backward from the end of the string. Example:

      uinsert(text_string, 0, prefix_letter);

Return value: Returns the number of bytes by which the trailing part of the string was moved.

See also: uoffset, ugetat, usetat, uremove.

int uremove(char *s, int index);

Removes the character at the specified `index' within the string, sliding the rest of the data back to fill the gap. If `index' is negative, it counts backward from the end of the string. Example:

      int length_in_bytes = ustrsizez(text_string);
      ...
      length_in_bytes -= uremove(text_string, -1);

Return value: Returns the number of bytes by which the trailing part of the string was moved.

See also: uoffset, ugetat, usetat, uinsert.

int ustrsize(const char *s);

Returns the size of the specified string in bytes, not including the trailing null character.

See also: ustrsizez, empty_string.

Examples using this: exunicod.

int ustrsizez(const char *s);

Returns the size of the specified string in bytes, including the trailing null character.

See also: ustrsize, empty_string.

Examples using this: exunicod.

int uwidth_max(int type);

Low level helper function for working with Unicode text data. Returns the largest number of bytes that one character can occupy in the given encoding format. Pass U_CURRENT to represent the current format. Example:

      char *temp_buffer = malloc(256 * uwidth_max(U_UTF8));

See also: uwidth, ucwidth.

int utolower(int c);

This function returns `c', converting it to lower case if it is upper case.

See also: utoupper, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.

int utoupper(int c);

This function returns `c', converting it to upper case if it is lower case.

See also: utolower, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.

int uisspace(int c);

Returns nonzero if `c' is whitespace, that is, carriage return, newline, form feed, tab, vertical tab, or space. Example:

      for (counter = 0; counter < ustrlen(text_string); counter++) {
         if (uisspace(ugetat(text_string, counter)))
            usetat(text_string, counter, '_');
      }

See also: uisdigit, ugetc, usetc, uwidth, ucwidth, uisok.

int uisdigit(int c);

Returns nonzero if `c' is a digit.

      for (counter = 0; counter < ustrlen(text_string); counter++) {
         if (uisdigit(ugetat(text_string, counter)))
            usetat(text_string, counter, '*');
      }

See also: uisspace, ugetc, usetc, uwidth, ucwidth, uisok.

char *ustrdup(const char *src)

This functions copies the null-terminated string `src' into a newly allocated area of memory, effectively duplicating it. Example:

      void manipulate_string(const char *input_string)
      {
         char *temp_buffer = ustrdup(input_string);
         /* Now we can modify temp_buffer */
         ...

Return value: Returns the newly allocated string. This memory must be freed by the caller. Returns NULL if it cannot allocate space for the duplicated string.

See also: _ustrdup, uconvert, ustrsize, ustrsizez.

Examples using this: exconfig.

char *_ustrdup(const char *src, void* (*malloc_func)(size_t))

Does the same as ustrdup(), but allows the user to specify a custom memory allocator function.

See also: ustrdup, uconvert, ustrsize, ustrsizez.

char *ustrcpy(char *dest, const char *src);

This function copies `src' (including the terminating null character into `dest'. You should try to avoid this function because it is very easy to overflow the destination buffer. Use ustrzcpy instead.

Return value: Returns the value of dest.

See also: uconvert, ustrzcpy, ustrncpy.

Examples using this: exunicod.

char *ustrzcpy(char *dest, int size, const char *src);

This function copies `src' (including the terminating null character) into `dest', whose length in bytes is specified by `size' and which is guaranteed to be null-terminated even if `src' is bigger than `size'.

Return value: Returns the value of `dest'.

See also: uconvert, ustrcpy, ustrzncpy.

Examples using this: ex3buf, exgui.

char *ustrcat(char *dest, const char *src);

This function concatenates `src' to the end of `dest`'. You should try to avoid this function because it is very easy to overflow the destination buffer, use ustrzcat instead.

Return value: Returns the value of `dest'.

See also: uconvert, ustrzcat, ustrncat.

Examples using this: exunicod.

char *ustrzcat(char *dest, int size, const char *src);

This function concatenates `src' to the end of `dest', whose length in bytes is specified by `size' and which is guaranteed to be null-terminated even when `src' is bigger than `size'.

Return value: Returns the value of `dest'.

See also: uconvert, ustrcat, ustrzncat.

Examples using this: exgui.

int ustrlen(const char *s);

This function returns the number of characters in `s'. Note that this doesn't have to equal the string's size in bytes.

See also: uconvert, ustrsize, ustrsizez.

int ustrcmp(const char *s1, const char *s2);

This function compares `s1' and `s2'.

Return value: Returns zero if the strings are equal, a positive number if `s1' comes after `s2' in the ASCII collating sequence, else a negative number.

See also: uconvert, ustrsize, ustrsizez, ustrncmp, ustricmp, ustrnicmp.

char *ustrncpy(char *dest, const char *src, int n);

This function is like ustrcpy() except that no more than `n' characters from `src' are copied into `dest'. If `src' is shorter than `n' characters, null characters are appended to `dest' as padding until `n' characters have been written.

Note that if `src' is longer than `n' characters, `dest' will not be null-terminated.

Return value: The return value is the value of `dest'.

See also: uconvert, ustrcpy, ustrzncpy.

char *ustrzncpy(char *dest, int size, const char *src, int n);

This function is like ustrzcpy() except that no more than `n' characters from `src' are copied into `dest'. If `src' is shorter than `n' characters, null characters are appended to `dest' as padding until `n' characters have been written. In any case, `dest' is guaranteed to be null-terminated.

Note that, even for empty strings, your destination string must have at least enough bytes to store the terminating null character of the string, and your parameter `size' must reflect this. Otherwise, the debug version of Allegro will abort at an assertion, and the release version of Allegro will overrun the destination buffer.

Return value: The return value is the value of `dest'.

See also: uconvert, ustrzcpy, ustrncpy.

Examples using this: exkeys.

char *ustrncat(char *dest, const char *src, int n);

This function is like ustrcat() except that no more than `n' characters from `src' are appended to the end of `dest'. If the terminating null character in `src' is reached before `n' characters have been written, the null character is copied, but no other characters are written. If `n' characters are written before a terminating null is encountered, the function appends its own null character to `dest', so that `n+1' characters are written. You should try to avoid this function because it is very easy to overflow the destination buffer. Use ustrzncat instead.

Return value: The return value is the value of `dest'.

See also: uconvert, ustrcat, ustrzncat.

char *ustrzncat(char *dest, int size, const char *src, int n);

This function is like ustrzcat() except that no more than `n' characters from `src' are appended to the end of `dest'. If the terminating null character in `src' is reached before `n' characters have been written, the null character is copied, but no other characters are written. Note that `dest' is guaranteed to be null-terminated.

Return value: The return value is the value of `dest'.

See also: uconvert, ustrzcat, ustrncat.

int ustrncmp(const char *s1, const char *s2, int n);

This function compares up to `n' characters of `s1' and `s2'. Example:

      if (ustrncmp(prefix, long_string, ustrlen(prefix)) == 0) {
         /* long_string starts with prefix */
      }

Return value: Returns zero if the substrings are equal, a positive number if `s1' comes after `s2' in the ASCII collating sequence, else a negative number.

See also: uconvert, ustrsize, ustrsizez, ustrcmp, ustricmp, ustrnicmp.

int ustricmp(const char *s1, const char *s2);

This function compares `s1' and `s2', ignoring case. Example:

      if (ustricmp(string, user_input) == 0) {
         /* string and user_input are equal (ignoring case) */
      }

Return value: Returns zero if the strings are equal, a positive number if `s1' comes after `s2' in the ASCII collating sequence, else a negative number.

See also: uconvert, ustrsize, ustrsizez, ustrnicmp, ustrcmp, ustrncmp.

Examples using this: exconfig.

int ustrnicmp(const char *s1, const char *s2, int n);

This function compares up to `n' characters of `s1' and `s2', ignoring case. Example:

      if (ustrnicmp(prefix, long_string, ustrlen(prefix)) == 0) {
         /* long_string starts with prefix (ignoring case) */
      }

Return value: Returns zero if the strings are equal, a positive number if `s1' comes after `s2' in the ASCII collating sequence, else a negative number.

See also: uconvert, ustrsize, ustrsizez, ustricmp, ustrcmp, ustrncmp.

char *ustrlwr(char *s);

This function replaces all upper case letters in `s' with lower case letters. Example:

      char buffer[] = "UPPER CASE STRING";
      allegro_message(ustrlwr(buffer));

Return value: The return value is the value of `s'.

See also: uconvert, utolower, ustrupr.

char *ustrupr(char *s);

This function replaces all lower case letters in `s' with upper case letters. Example:

      char buffer[] = "lower case string";
      allegro_message(ustrupr(buffer));

Return value: The return value is the value of `s'.

See also: uconvert, utolower, ustrlwr.

char *ustrchr(const char *s, int c);

Finds the first occurrence of the character `c' in the string `s'. Example:

      char *p = ustrchr("one,two,three,four", ',');

Return value: Returns a pointer to the first occurrence of `c' in `s', or NULL if no match was found. Note that if `c' is NULL, this will return a pointer to the end of the string.

See also: uconvert, ustrrchr, ustrstr, ustrpbrk, ustrtok.

char *ustrrchr(const char *s, int c);

Finds the last occurrence of the character `c' in the string `s'. Example:

      char *p = ustrrchr("one,two,three,four", ',');

Return value: Returns a pointer for the last occurrence of `c' in `s', or NULL if no match was found.

See also: uconvert, ustrchr, ustrstr, ustrpbrk, ustrtok.

char *ustrstr(const char *s1, const char *s2);

This function finds the first occurrence of string `s2' in string `s1'. Example:

      char *p = ustrstr("hello world", "world");

Return value: Returns a pointer within `s1', or NULL if `s2' wasn't found.

See also: uconvert, ustrchr, ustrrchr, ustrpbrk, ustrtok.

char *ustrpbrk(const char *s, const char *set);

This function finds the first character in `s' that matches any character in `set'. Example:

      char *p = ustrpbrk("one,two-three.four", "-. ");

Return value: Returns a pointer to the first match, or NULL if none are found.

See also: uconvert, ustrchr, ustrrchr, ustrstr, ustrtok.

char *ustrtok(char *s, const char *set);

This function retrieves tokens from `s' which are delimited by characters from `set'. To initiate the search, pass the string to be searched as `s'. For the remaining tokens, pass NULL instead. Warning: Since ustrtok alters the string it is parsing, you should always copy the string to a temporary buffer before parsing it. Also, this function is not re-entrant (ie. you cannot parse two strings at the same time). Example:

      char *word;
      char string[]="some-words with dashes";
      char *temp = ustrdup(string);
      word = ustrtok(temp, " -");
      while (word) {
         allegro_message("Found `%s'\n", word);
         word = ustrtok(NULL, " -");
      }
      free(temp);

Return value: Returns a pointer to the token, or NULL if no more are found.

See also: uconvert, ustrchr, ustrrchr, ustrstr, ustrpbrk, ustrtok_r, allegro_message, ustrncpy.

Examples using this: exgui.

char *ustrtok_r(char *s, const char *set, char **last);

Reentrant version of ustrtok. The `last' parameter is used to keep track of where the parsing is up to and must be a pointer to a char * variable allocated by the user that remains the same while parsing the same string. Example:

      char *word, *last;
      char string[]="some-words with dashes";
      char *temp = ustrdup(string);
      word = ustrtok_r(string, " -", &last);
      while (word) {
         allegro_message("Found `%s'\n", word);
         word = ustrtok_r(NULL, " -", &last);
      }
      free(temp);

Return value: Returns a pointer to the token, or NULL if no more are found. You can free the memory pointed to by `last' once NULL is returned.

See also: ustrtok.

double uatof(const char *s);

Convert as much of the string as possible to an equivalent double precision real number. This function is almost like `ustrtod(s, NULL)'.

Return value: Returns the equivalent value, or zero if the string does not represent a number.

See also: uconvert, ustrtol, ustrtod.

long ustrtol(const char *s, char **endp, int base);

This function converts the initial part of `s' to a signed integer, setting `*endp' to point to the first unused character, if `endp' is not a NULL pointer. The `base' argument indicates what base the digits (or letters) should be treated as. If `base' is zero, the base is determined by looking for `0x', `0X', or `0' as the first part of the string, and sets the base used to 16, 16, or 8 if it finds one. The default base is 10 if none of those prefixes are found. Example:

      char *endp, *string = "456.203 askdfg";
      int number = ustrtol(string, &endp, 10);

Return value: Returns the string converted as a value of type `long int'. If nothing was converted, returns zero with `*endp' pointing to the beginning of `s'.

See also: uconvert, ustrtod, uatof.

double ustrtod(const char *s, char **endp);

This function converts as many characters of `s' that look like a floating point number into one, and sets `*endp' to point to the first unused character, if `endp' is not a NULL pointer. Example:

      char *endp, *string = "456.203 askdfg";
      double number = ustrtod(string, &endp);

Return value: Returns the string converted as a value of type `double'. If nothing was converted, returns zero with *endp pointing to the beginning of s.

See also: uconvert, ustrtol, uatof.

const char *ustrerror(int err);

This function returns a string that describes the error code `err', which normally comes from the variable `errno'. Example:

      PACKFILE *input_file = pack_fopen("badname", "r");
      if (input_file == NULL)
         allegro_message("%s\nSorry!\n", ustrerror(errno));

Return value: Returns a pointer to a static string that should not be modified or freed. If you make subsequent calls to ustrerror(), the string will be overwritten.

See also: uconvert, allegro_error.

int usprintf(char *buf, const char *format, ...);

This function writes formatted data into the output buffer. A NULL character is written to mark the end of the string. You should try to avoid this function because it is very easy to overflow the destination buffer. Use uszprintf instead.

Return value: Returns the number of characters written, not including the terminating null character.

See also: uconvert, uszprintf, uvsprintf.

Examples using this: exkeys.

int uszprintf(char *buf, int size, const char *format, ...);

This function writes formatted data into the output buffer, whose length in bytes is specified by `size' and which is guaranteed to be NULL terminated. Example:

      char buffer[10];
      int player_score;
      ...
      uszprintf(buffer, sizeof(buffer), "Your score is: %d", player_score);

Return value: Returns the number of characters that would have been written without eventual truncation (like with usprintf), not including the terminating null character.

See also: uconvert, usprintf, uvszprintf.

Examples using this: exgui.

int uvsprintf(char *buf, const char *format, va_list args);

This is like usprintf(), but you pass the variable argument list directly, instead of the arguments themselves. You can use this function to implement printf like functions, also called variadic functions. You should try to avoid this function because it is very easy to overflow the destination buffer. Use uvszprintf instead.

Return value: Returns the number of characters written, not including the terminating null character.

See also: uconvert, usprintf, uvszprintf.

int uvszprintf(char *buf, int size, const char *format, va_list args);

This is like uszprintf(), but you pass the variable argument list directly, instead of the arguments themselves. Example:

      #include <stdarg.h>

      void log_message(const char *format, ...)
      {
         char buffer[100];
         va_list parameters;
         
         va_start(parameters, format);
         uvszprintf(buffer, sizeof(buffer), format, parameters);
         va_end(parameters);
         
         append_buffer_to_logfile(log_name, buffer);
         send_buffer_to_other_networked_players(multicast_ip, buffer);
         and_also_print_it_on_the_screen(cool_font, buffer);
      }
      
      void some_other_function(void)
      {
         log_message("Hello %s, are you %d years old?\n", "Dave", 25);
      }

Return value: Returns the number of characters that would have been written without eventual truncation (like with uvsprintf), not including the terminating null character.

See also: uconvert, uszprintf, uvsprintf.

Back to contents