<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Unicode routines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Unicode routines">Unicode routines</a></h1>
<ul>
<li><a href="#_ustrdup">_ustrdup</a> — Duplicates a string with a custom memory allocator.
<li><a href="#do_uconvert">do_uconvert</a> — Converts a string to another encoding format.
<li><a href="#empty_string">empty_string</a> — Universal string NULL terminator.
<li><a href="#get_uformat">get_uformat</a> — Finds out what text encoding format is currently selected.
<li><a href="#need_uconvert">need_uconvert</a> — Tells if a string requires encoding conversion.
<li><a href="#register_uformat">register_uformat</a> — Installs handler functions for a new text encoding format.
<li><a href="#set_ucodepage">set_ucodepage</a> — Sets 8-bit to Unicode conversion tables.
<li><a href="#set_uformat">set_uformat</a> — Set the global current text encoding format.
<li><a href="#uatof">uatof</a> — Converts a string into a double.
<li><a href="#uconvert">uconvert</a> — High level string encoding conversion wrapper.
<li><a href="#uconvert_ascii">uconvert_ascii</a> — Converts string from ASCII into the current format.
<li><a href="#uconvert_size">uconvert_size</a> — Number of bytes needed to store a string after conversion.
<li><a href="#uconvert_toascii">uconvert_toascii</a> — Converts strings from the current format into ASCII.
<li><a href="#ucwidth">ucwidth</a> — Low level helper function for testing Unicode text data.
<li><a href="#ugetat">ugetat</a> — Finds out the value of a character in a string.
<li><a href="#ugetc">ugetc</a> — Low level helper function for reading Unicode text data.
<li><a href="#ugetx">ugetx</a> — Low level helper function for reading Unicode text data.
<li><a href="#ugetxc">ugetxc</a> — Low level helper function for reading Unicode text data.
<li><a href="#uinsert">uinsert</a> — Inserts a character in a string.
<li><a href="#uisdigit">uisdigit</a> — Tells if a character is a digit.
<li><a href="#uisok">uisok</a> — Low level helper function for testing Unicode text data.
<li><a href="#uisspace">uisspace</a> — Tells if a character is whitespace.
<li><a href="#uoffset">uoffset</a> — Finds the offset of a character in a string.
<li><a href="#uremove">uremove</a> — Removes a character from a string.
<li><a href="#usetat">usetat</a> — Replaces a character in a string.
<li><a href="#usetc">usetc</a> — Low level helper function for writing Unicode text data.
<li><a href="#usprintf">usprintf</a> — Writes formatted data into a buffer.
<li><a href="#ustrcat">ustrcat</a> — Concatenates a string to another one.
<li><a href="#ustrchr">ustrchr</a> — Finds the first occurrence of a character in a string.
<li><a href="#ustrcmp">ustrcmp</a> — Compares two strings.
<li><a href="#ustrcpy">ustrcpy</a> — Copies a string into another one.
<li><a href="#ustrdup">ustrdup</a> — Duplicates a string.
<li><a href="#ustrerror">ustrerror</a> — Returns a string describing errno.
<li><a href="#ustricmp">ustricmp</a> — Compares two strings ignoring case.
<li><a href="#ustrlen">ustrlen</a> — Tells the number of characters in a string.
<li><a href="#ustrlwr">ustrlwr</a> — Replaces all letters with lower case.
<li><a href="#ustrncat">ustrncat</a> — Concatenates a string to another one, specifying size.
<li><a href="#ustrncmp">ustrncmp</a> — Compares up to n letters of two strings.
<li><a href="#ustrncpy">ustrncpy</a> — Copies a string into another one, specifying size.
<li><a href="#ustrnicmp">ustrnicmp</a> — Compares up to n letters of two strings ignoring case.
<li><a href="#ustrpbrk">ustrpbrk</a> — Finds the first character that matches any in a set.
<li><a href="#ustrrchr">ustrrchr</a> — Finds the last occurrence of a character in a string.
<li><a href="#ustrsize">ustrsize</a> — Size of the string in bytes without null terminator.
<li><a href="#ustrsizez">ustrsizez</a> — Size of the string in bytes including null terminator.
<li><a href="#ustrstr">ustrstr</a> — Finds the first occurrence of a string in another one.
<li><a href="#ustrtod">ustrtod</a> — Converts a string into a floating point number.
<li><a href="#ustrtok">ustrtok</a> — Retrieves tokens from a string.
<li><a href="#ustrtok_r">ustrtok_r</a> — Reentrant function to retrieve tokens from a string.
<li><a href="#ustrtol">ustrtol</a> — Converts a string into an integer.
<li><a href="#ustrupr">ustrupr</a> — Replaces all letters with upper case.
<li><a href="#ustrzcat">ustrzcat</a> — Concatenates a string to another one, specifying size.
<li><a href="#ustrzcpy">ustrzcpy</a> — Copies a string into another one, specifying size.
<li><a href="#ustrzncat">ustrzncat</a> — Concatenates a string to another one, specifying size.
<li><a href="#ustrzncpy">ustrzncpy</a> — Copies a string into another one, specifying size.
<li><a href="#uszprintf">uszprintf</a> — Writes formatted data into a buffer, specifying size.
<li><a href="#utolower">utolower</a> — Converts a letter to lower case.
<li><a href="#utoupper">utoupper</a> — Converts a letter to upper case.
<li><a href="#uvsprintf">uvsprintf</a> — Writes formatted data into a buffer, using variable arguments.
<li><a href="#uvszprintf">uvszprintf</a> — Writes formatted data into a buffer, using size and variable arguments.
<li><a href="#uwidth">uwidth</a> — Low level helper function for testing Unicode text data.
<li><a href="#uwidth_max">uwidth_max</a> — Number of bytes a character can occupy.
</ul>
<p>
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.
<p>
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.
<p>
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.
<p>
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).
<p>
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.
<p>
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.
<p><br>
<div class="al-api"><b>void <a name="set_uformat">set_uformat</a>(int type);</b></div><br>
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. <tt>`type'</tt> should be one of these values:
<blockquote class="text"><pre>
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
</pre></blockquote>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_uformat" title="Finds out what text encoding format is currently selected.">get_uformat</a>,
<a class="xref" href="#register_uformat" title="Installs handler functions for a new text encoding format.">register_uformat</a>,
<a class="xref" href="#set_ucodepage" title="Sets 8-bit to Unicode conversion tables.">set_ucodepage</a>,
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>,
<a class="xref" href="#uoffset" title="Finds the offset of a character in a string.">uoffset</a>,
<a class="xref" href="#ugetat" title="Finds out the value of a character in a string.">ugetat</a>,
<a class="xref" href="#usetat" title="Replaces a character in a string.">usetat</a>,
<a class="xref" href="#uinsert" title="Inserts a character in a string.">uinsert</a>,
<a class="xref" href="#uremove" title="Removes a character from a string.">uremove</a>,
<a class="xref" href="alleg000.html#allegro_init" title="Macro to initialise the Allegro library.">allegro_init</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>int <a name="get_uformat">get_uformat</a>(void);</b></div><br>
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:
<blockquote class="code"><pre>
switch(<a href="#get_uformat" class="autotype" title="Finds out what text encoding format is currently selected.">get_uformat</a>()) {
case U_ASCII:
do_something();
break;
case U_UTF8:
do_something_else();
break;
...
}</pre></blockquote>
<p><b>Return value:</b>
Returns the currently selected text encoding format. See the documentation
of set_uformat() for a list of encoding formats.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>.</blockquote>
<div class="al-api"><b>void <a name="register_uformat">register_uformat</a>(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));</b></div><br>
Installs a set of custom handler functions for a new text encoding
format. The <tt>`type'</tt> 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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>void <a name="set_ucodepage">set_ucodepage</a>(const unsigned short *table,
const unsigned short *extras);</b></div><br>
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.
<p>
The <tt>`table'</tt> parameter points to an array of 256 shorts, which contain the
Unicode value for each character in your codepage. The <tt>`extras'</tt> 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).
<p>
Allegro will use the <tt>`table'</tt> 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
<tt>`table'</tt> parameter looking for an index position pointing at the Unicode
value it is trying to convert (ie. the <tt>`table'</tt> parameter is also used for
reverse matching). If that fails, the <tt>`extras'</tt> list is used. If that fails
too, Allegro will put the character <tt>`^'</tt>, giving up the conversion.
<p>
Note that Allegro comes with a default <tt>`table'</tt> and <tt>`extras'</tt> parameters
set internally. The default <tt>`table'</tt> will convert 8-bit characters to <tt>`^'</tt>.
The default <tt>`extras'</tt> 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).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>.</blockquote>
<div class="al-api"><b>int <a name="need_uconvert">need_uconvert</a>(const char *s, int type, int newtype);</b></div><br>
Given a pointer to a string (<tt>`s'</tt>), a description of the type of the string
(<tt>`type'</tt>), and the type that you would like this string to be converted into
(<tt>`newtype'</tt>), this function tells you whether any conversion is required. No
conversion will be needed if <tt>`type'</tt> and <tt>`newtype'</tt> 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:
<blockquote class="code"><pre>
if (<a href="#need_uconvert" class="autotype" title="Tells if a string requires encoding conversion.">need_uconvert</a>(text, U_UTF8, U_CURRENT)) {
/* conversion is required */
}</pre></blockquote>
<p><b>Return value:</b>
Returns non-zero if any conversion is required or zero otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>,
<a class="xref" href="#get_uformat" title="Finds out what text encoding format is currently selected.">get_uformat</a>,
<a class="xref" href="#do_uconvert" title="Converts a string to another encoding format.">do_uconvert</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>.</blockquote>
<div class="al-api"><b>int <a name="uconvert_size">uconvert_size</a>(const char *s, int type, int newtype);</b></div><br>
Finds out how many bytes are required to store the specified string <tt>`s'</tt>
after a conversion from <tt>`type'</tt> to <tt>`newtype'</tt>, including the mandatory zero
terminator of the string. You can use U_CURRENT for either <tt>`type'</tt> or
<tt>`newtype'</tt> as a shortcut to represent whatever text encoding format is
currently selected. Example:
<blockquote class="code"><pre>
length = <a href="#uconvert_size" class="autotype" title="Number of bytes needed to store a string after conversion.">uconvert_size</a>(old_string, U_CURRENT, U_UNICODE);
new_string = malloc(length);
<a href="#ustrcpy" class="autotype" title="Copies a string into another one.">ustrcpy</a>(new_string, old_string);</pre></blockquote>
<p><b>Return value:</b>
Returns the number of bytes required to store the string after conversion.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#need_uconvert" title="Tells if a string requires encoding conversion.">need_uconvert</a>,
<a class="xref" href="#do_uconvert" title="Converts a string to another encoding format.">do_uconvert</a>.</blockquote>
<div class="al-api"><b>void <a name="do_uconvert">do_uconvert</a>(const char *s, int type,
char *buf, int newtype, int size);</b></div><br>
Converts the specified string <tt>`s'</tt> from <tt>`type'</tt> to <tt>`newtype'</tt>, storing at most
<tt>`size'</tt> bytes into the output <tt>`buf'</tt>. The type parameters can use the value
U_CURRENT as a shortcut to represent the currently selected encoding
format. Example:
<blockquote class="code"><pre>
char temp_string[256];
<a href="#do_uconvert" class="autotype" title="Converts a string to another encoding format.">do_uconvert</a>(input_string, U_CURRENT, temp_string, U_ASCII, 256);
</pre></blockquote>
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 <tt>`size'</tt> 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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>.</blockquote>
<div class="al-api"><b>char *<a name="uconvert">uconvert</a>(const char *s, int type,
char *buf, int newtype, int size);</b></div><br>
Higher level function running on top of do_uconvert(). This function
converts the specified string <tt>`s'</tt> from <tt>`type'</tt> to <tt>`newtype'</tt>, storing at most
<tt>`size'</tt> bytes into the output <tt>`buf'</tt> (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).
<p>
As a convenience, if <tt>`buf'</tt> is NULL it will convert the string into an
internal static buffer and the <tt>`size'</tt> 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:
<blockquote class="code"><pre>
char *p = <a href="#uconvert" class="autotype" title="High level string encoding conversion wrapper.">uconvert</a>(input_string, U_CURRENT, buffer, U_ASCII, 256);</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to <tt>`buf'</tt> (or the static buffer if you used NULL) if a
conversion was performed. Otherwise returns a copy of <tt>`s'</tt>. In any cases,
you should use the return value rather than assuming that the string will
always be moved to <tt>`buf'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_uformat" title="Set the global current text encoding format.">set_uformat</a>,
<a class="xref" href="#need_uconvert" title="Tells if a string requires encoding conversion.">need_uconvert</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#uconvert_ascii" title="Converts string from ASCII into the current format.">uconvert_ascii</a>,
<a class="xref" href="#uconvert_toascii" title="Converts strings from the current format into ASCII.">uconvert_toascii</a>,
<a class="xref" href="#do_uconvert" title="Converts a string to another encoding format.">do_uconvert</a>.</blockquote>
<div class="al-api"><b>char *<a name="uconvert_ascii">uconvert_ascii</a>(const char *s, char buf[]);</b></div><br>
Helper macro for converting strings from ASCII into the current encoding
format. Expands to uconvert(s, U_ASCII, buf, U_CURRENT, sizeof(buf)).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>char *<a name="uconvert_toascii">uconvert_toascii</a>(const char *s, char buf[]);</b></div><br>
Helper macro for converting strings from the current encoding format into
ASCII. Expands to uconvert(s, U_CURRENT, buf, U_ASCII, sizeof(buf)).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>.</blockquote>
<div class="al-api"><b>extern char <a name="empty_string">empty_string</a>[];</b></div><br>
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.
<p><br>
<div class="al-api"><b>int <a name="ugetc">ugetc</a>(const char *s);</b></div><br>
Low level helper function for reading Unicode text data. Example:
<blockquote class="code"><pre>
int first_unicode_letter = <a href="#ugetc" class="autotype" title="Low level helper function for reading Unicode text data.">ugetc</a>(text_string);</pre></blockquote>
<p><b>Return value:</b>
Returns the character pointed to by <tt>`s'</tt> in the current encoding format.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="ugetx">ugetx</a>(char **s);</b></div><br>
<div class="al-api-cont"><b>int <a name="ugetxc">ugetxc</a>(const char **s);</b></div><br>
Low level helper function for reading Unicode text data. ugetxc is provided
for working with pointer-to-pointer-to-const char data. Example:
<blockquote class="code"><pre>
char *p = string;
int first_letter, second_letter, third_letter;
first_letter = <a href="#ugetx" class="autotype" title="Low level helper function for reading Unicode text data.">ugetx</a>(&p);
second_letter = <a href="#ugetx" class="autotype" title="Low level helper function for reading Unicode text data.">ugetx</a>(&p);
third_letter = <a href="#ugetx" class="autotype" title="Low level helper function for reading Unicode text data.">ugetx</a>(&p);</pre></blockquote>
<p><b>Return value:</b>
Returns the character pointed to by <tt>`s'</tt> in the current encoding format, and
advances the pointer to the next character after the one just returned.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="usetc">usetc</a>(char *s, int c);</b></div><br>
Low level helper function for writing Unicode text data. Writes the
character <tt>`c'</tt> to the address pointed to by <tt>`s'</tt>.
<p><b>Return value:</b>
Returns the number of bytes written, which is equal to the width of the
character in the current encoding format.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="uwidth">uwidth</a>(const char *s);</b></div><br>
Low level helper function for testing Unicode text data.
<p><b>Return value:</b>
Returns the number of bytes occupied by the first character of the
specified string, in the current encoding format.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uwidth_max" title="Number of bytes a character can occupy.">uwidth_max</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="ucwidth">ucwidth</a>(int c);</b></div><br>
Low level helper function for testing Unicode text data.
<p><b>Return value:</b>
Returns the number of bytes that would be occupied by the specified
character value, when encoded in the current format.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uwidth_max" title="Number of bytes a character can occupy.">uwidth_max</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="uisok">uisok</a>(int c);</b></div><br>
Low level helper function for testing Unicode text data. Finds out if the
character value <tt>`c'</tt> 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.
<p><b>Return value:</b>
Returns non-zero if the value can be correctly encoded, zero otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>.</blockquote>
<div class="al-api"><b>int <a name="uoffset">uoffset</a>(const char *s, int index);</b></div><br>
Finds out the offset (in bytes from the start of the string) of the
character at the specified <tt>`index'</tt> in the string <tt>`s'</tt>. A zero <tt>`index'</tt>
parameter will return the first character of the string. If <tt>`index'</tt> is
negative, it counts backward from the end of the string, so an <tt>`index'</tt> of
`-1' will return an offset to the last character. Example:
<blockquote class="code"><pre>
int from_third_letter = <a href="#uoffset" class="autotype" title="Finds the offset of a character in a string.">uoffset</a>(text_string, 2);</pre></blockquote>
<p><b>Return value:</b>
Returns the offset in bytes to the specified character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ugetat" title="Finds out the value of a character in a string.">ugetat</a>,
<a class="xref" href="#usetat" title="Replaces a character in a string.">usetat</a>,
<a class="xref" href="#uinsert" title="Inserts a character in a string.">uinsert</a>,
<a class="xref" href="#uremove" title="Removes a character from a string.">uremove</a>.</blockquote>
<div class="al-api"><b>int <a name="ugetat">ugetat</a>(const char *s, int index);</b></div><br>
Finds out the character value at the specified <tt>`index'</tt> in the string. A
zero <tt>`index'</tt> parameter will return the first character of the string. If
<tt>`index'</tt> is negative, it counts backward from the end of the string, so an
<tt>`index'</tt> of `-1' will return the last character of the string. Example:
<blockquote class="code"><pre>
int third_letter = <a href="#ugetat" class="autotype" title="Finds out the value of a character in a string.">ugetat</a>(text_string, 2);</pre></blockquote>
<p><b>Return value:</b>
Returns the character value at the specified index in the string.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uoffset" title="Finds the offset of a character in a string.">uoffset</a>,
<a class="xref" href="#usetat" title="Replaces a character in a string.">usetat</a>,
<a class="xref" href="#uinsert" title="Inserts a character in a string.">uinsert</a>,
<a class="xref" href="#uremove" title="Removes a character from a string.">uremove</a>.</blockquote>
<div class="al-api"><b>int <a name="usetat">usetat</a>(char *s, int index, int c);</b></div><br>
Replaces the character at the specified index in the string with value <tt>`c'</tt>,
handling any adjustments for variable width data (ie. if <tt>`c'</tt> encodes to a
different width than the previous value at that location). If <tt>`index'</tt> is
negative, it counts backward from the end of the string. Example:
<blockquote class="code"><pre>
<a href="#usetat" class="autotype" title="Replaces a character in a string.">usetat</a>(text_string, 2, letter_a);</pre></blockquote>
<p><b>Return value:</b>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uoffset" title="Finds the offset of a character in a string.">uoffset</a>,
<a class="xref" href="#ugetat" title="Finds out the value of a character in a string.">ugetat</a>,
<a class="xref" href="#uinsert" title="Inserts a character in a string.">uinsert</a>,
<a class="xref" href="#uremove" title="Removes a character from a string.">uremove</a>.</blockquote>
<div class="al-api"><b>int <a name="uinsert">uinsert</a>(char *s, int index, int c);</b></div><br>
Inserts the character <tt>`c'</tt> at the specified <tt>`index'</tt> in the string, sliding
the rest of the data along to make room. If <tt>`index'</tt> is negative, it counts
backward from the end of the string. Example:
<blockquote class="code"><pre>
<a href="#uinsert" class="autotype" title="Inserts a character in a string.">uinsert</a>(text_string, 0, prefix_letter);</pre></blockquote>
<p><b>Return value:</b>
Returns the number of bytes by which the trailing part of the string was
moved.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uoffset" title="Finds the offset of a character in a string.">uoffset</a>,
<a class="xref" href="#ugetat" title="Finds out the value of a character in a string.">ugetat</a>,
<a class="xref" href="#usetat" title="Replaces a character in a string.">usetat</a>,
<a class="xref" href="#uremove" title="Removes a character from a string.">uremove</a>.</blockquote>
<div class="al-api"><b>int <a name="uremove">uremove</a>(char *s, int index);</b></div><br>
Removes the character at the specified <tt>`index'</tt> within the string, sliding
the rest of the data back to fill the gap. If <tt>`index'</tt> is negative, it
counts backward from the end of the string. Example:
<blockquote class="code"><pre>
int length_in_bytes = <a href="#ustrsizez" class="autotype" title="Size of the string in bytes including null terminator.">ustrsizez</a>(text_string);
...
length_in_bytes -= <a href="#uremove" class="autotype" title="Removes a character from a string.">uremove</a>(text_string, -1);</pre></blockquote>
<p><b>Return value:</b>
Returns the number of bytes by which the trailing part of the string was
moved.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uoffset" title="Finds the offset of a character in a string.">uoffset</a>,
<a class="xref" href="#ugetat" title="Finds out the value of a character in a string.">ugetat</a>,
<a class="xref" href="#usetat" title="Replaces a character in a string.">usetat</a>,
<a class="xref" href="#uinsert" title="Inserts a character in a string.">uinsert</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrsize">ustrsize</a>(const char *s);</b></div><br>
Returns the size of the specified string in bytes, not including the
trailing null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>,
<a class="xref" href="#empty_string" title="Universal string NULL terminator.">empty_string</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrsizez">ustrsizez</a>(const char *s);</b></div><br>
Returns the size of the specified string in bytes, including the trailing
null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#empty_string" title="Universal string NULL terminator.">empty_string</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>int <a name="uwidth_max">uwidth_max</a>(int type);</b></div><br>
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:
<blockquote class="code"><pre>
char *temp_buffer = malloc(256 * <a href="#uwidth_max" class="autotype" title="Number of bytes a character can occupy.">uwidth_max</a>(U_UTF8));</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>.</blockquote>
<div class="al-api"><b>int <a name="utolower">utolower</a>(int c);</b></div><br>
This function returns <tt>`c'</tt>, converting it to lower case if it is upper case.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#utoupper" title="Converts a letter to upper case.">utoupper</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="utoupper">utoupper</a>(int c);</b></div><br>
This function returns <tt>`c'</tt>, converting it to upper case if it is lower case.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#utolower" title="Converts a letter to lower case.">utolower</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#ugetx" title="Low level helper function for reading Unicode text data.">ugetx</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="uisspace">uisspace</a>(int c);</b></div><br>
Returns nonzero if <tt>`c'</tt> is whitespace, that is, carriage return, newline,
form feed, tab, vertical tab, or space. Example:
<blockquote class="code"><pre>
for (counter = 0; counter < <a href="#ustrlen" class="autotype" title="Tells the number of characters in a string.">ustrlen</a>(text_string); counter++) {
if (<a href="#uisspace" class="autotype" title="Tells if a character is whitespace.">uisspace</a>(<a href="#ugetat" class="autotype" title="Finds out the value of a character in a string.">ugetat</a>(text_string, counter)))
<a href="#usetat" class="autotype" title="Replaces a character in a string.">usetat</a>(text_string, counter, '_');
}</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uisdigit" title="Tells if a character is a digit.">uisdigit</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>int <a name="uisdigit">uisdigit</a>(int c);</b></div><br>
Returns nonzero if <tt>`c'</tt> is a digit.
<blockquote class="code"><pre>
for (counter = 0; counter < <a href="#ustrlen" class="autotype" title="Tells the number of characters in a string.">ustrlen</a>(text_string); counter++) {
if (<a href="#uisdigit" class="autotype" title="Tells if a character is a digit.">uisdigit</a>(<a href="#ugetat" class="autotype" title="Finds out the value of a character in a string.">ugetat</a>(text_string, counter)))
<a href="#usetat" class="autotype" title="Replaces a character in a string.">usetat</a>(text_string, counter, '*');
}</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uisspace" title="Tells if a character is whitespace.">uisspace</a>,
<a class="xref" href="#ugetc" title="Low level helper function for reading Unicode text data.">ugetc</a>,
<a class="xref" href="#usetc" title="Low level helper function for writing Unicode text data.">usetc</a>,
<a class="xref" href="#uwidth" title="Low level helper function for testing Unicode text data.">uwidth</a>,
<a class="xref" href="#ucwidth" title="Low level helper function for testing Unicode text data.">ucwidth</a>,
<a class="xref" href="#uisok" title="Low level helper function for testing Unicode text data.">uisok</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrdup">ustrdup</a>(const char *src)</b></div><br>
This functions copies the null-terminated string <tt>`src'</tt> into a newly
allocated area of memory, effectively duplicating it. Example:
<blockquote class="code"><pre>
void manipulate_string(const char *input_string)
{
char *temp_buffer = <a href="#ustrdup" class="autotype" title="Duplicates a string.">ustrdup</a>(input_string);
/* Now we can modify temp_buffer */
...</pre></blockquote>
<p><b>Return value:</b>
Returns the newly allocated string. This memory must be freed by the
caller. Returns NULL if it cannot allocate space for the duplicated string.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#_ustrdup" title="Duplicates a string with a custom memory allocator.">_ustrdup</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exconfig" title="Using the configuration routines.">exconfig</a>.</blockquote>
<div class="al-api"><b>char *<a name="_ustrdup">_ustrdup</a>(const char *src, void* (*malloc_func)(size_t))</b></div><br>
Does the same as ustrdup(), but allows the user to specify a custom memory
allocator function.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ustrdup" title="Duplicates a string.">ustrdup</a>,
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrcpy">ustrcpy</a>(char *dest, const char *src);</b></div><br>
This function copies <tt>`src'</tt> (including the terminating null character into
<tt>`dest'</tt>. You should try to avoid this function because it is very easy to
overflow the destination buffer. Use ustrzcpy instead.
<p><b>Return value:</b>
Returns the value of dest.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrzcpy" title="Copies a string into another one, specifying size.">ustrzcpy</a>,
<a class="xref" href="#ustrncpy" title="Copies a string into another one, specifying size.">ustrncpy</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrzcpy">ustrzcpy</a>(char *dest, int size, const char *src);</b></div><br>
This function copies <tt>`src'</tt> (including the terminating null character) into
<tt>`dest'</tt>, whose length in bytes is specified by <tt>`size'</tt> and which is
guaranteed to be null-terminated even if <tt>`src'</tt> is bigger than <tt>`size'</tt>.
<p>
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 <tt>`size'</tt> 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.
<p><b>Return value:</b>
Returns the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrcpy" title="Copies a string into another one.">ustrcpy</a>,
<a class="xref" href="#ustrzncpy" title="Copies a string into another one, specifying size.">ustrzncpy</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3buf" title="Mode-X triple buffering and retrace interrupt simulation.">ex3buf</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrcat">ustrcat</a>(char *dest, const char *src);</b></div><br>
This function concatenates <tt>`src'</tt> to the end of <tt>`dest`'</tt>. You should try to
avoid this function because it is very easy to overflow the destination
buffer, use ustrzcat instead.
<p><b>Return value:</b>
Returns the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrzcat" title="Concatenates a string to another one, specifying size.">ustrzcat</a>,
<a class="xref" href="#ustrncat" title="Concatenates a string to another one, specifying size.">ustrncat</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrzcat">ustrzcat</a>(char *dest, int size, const char *src);</b></div><br>
This function concatenates <tt>`src'</tt> to the end of <tt>`dest'</tt>, whose length in
bytes is specified by <tt>`size'</tt> and which is guaranteed to be null-terminated
even when <tt>`src'</tt> is bigger than <tt>`size'</tt>.
<p>
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 <tt>`size'</tt> 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.
<p><b>Return value:</b>
Returns the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrcat" title="Concatenates a string to another one.">ustrcat</a>,
<a class="xref" href="#ustrzncat" title="Concatenates a string to another one, specifying size.">ustrzncat</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrlen">ustrlen</a>(const char *s);</b></div><br>
This function returns the number of characters in <tt>`s'</tt>. Note that this
doesn't have to equal the string's size in bytes.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrcmp">ustrcmp</a>(const char *s1, const char *s2);</b></div><br>
This function compares <tt>`s1'</tt> and <tt>`s2'</tt>.
<p><b>Return value:</b>
Returns zero if the strings are equal, a positive number if <tt>`s1'</tt> comes
after <tt>`s2'</tt> in the ASCII collating sequence, else a negative number.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>,
<a class="xref" href="#ustrncmp" title="Compares up to n letters of two strings.">ustrncmp</a>,
<a class="xref" href="#ustricmp" title="Compares two strings ignoring case.">ustricmp</a>,
<a class="xref" href="#ustrnicmp" title="Compares up to n letters of two strings ignoring case.">ustrnicmp</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrncpy">ustrncpy</a>(char *dest, const char *src, int n);</b></div><br>
This function is like ustrcpy() except that no more than <tt>`n'</tt> characters
from <tt>`src'</tt> are copied into <tt>`dest'</tt>. If <tt>`src'</tt> is shorter than <tt>`n'</tt> characters,
null characters are appended to <tt>`dest'</tt> as padding until <tt>`n'</tt> characters have
been written.
<p>
Note that if <tt>`src'</tt> is longer than <tt>`n'</tt> characters, <tt>`dest'</tt> will not be
null-terminated.
<p><b>Return value:</b>
The return value is the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrcpy" title="Copies a string into another one.">ustrcpy</a>,
<a class="xref" href="#ustrzncpy" title="Copies a string into another one, specifying size.">ustrzncpy</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrzncpy">ustrzncpy</a>(char *dest, int size, const char *src, int n);</b></div><br>
This function is like ustrzcpy() except that no more than <tt>`n'</tt> characters
from <tt>`src'</tt> are copied into <tt>`dest'</tt> whose length in bytes is specified by
<tt>`size'</tt> and which is guaranteed to be null-terminated even if <tt>`src'</tt> is
bigger than <tt>`size'</tt>. If <tt>`src'</tt> is shorter than <tt>`n'</tt> characters,
null characters are appended to <tt>`dest'</tt> as padding until <tt>`n'</tt> characters have
been written. In any case, <tt>`dest'</tt> is guaranteed to be null-terminated.
<p>
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 <tt>`size'</tt> 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.
<p><b>Return value:</b>
The return value is the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrzcpy" title="Copies a string into another one, specifying size.">ustrzcpy</a>,
<a class="xref" href="#ustrncpy" title="Copies a string into another one, specifying size.">ustrncpy</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exkeys" title="How to get input from the keyboard in different ways.">exkeys</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrncat">ustrncat</a>(char *dest, const char *src, int n);</b></div><br>
This function is like ustrcat() except that no more than <tt>`n'</tt> characters
from <tt>`src'</tt> are appended to the end of <tt>`dest'</tt>. If the terminating null
character in <tt>`src'</tt> is reached before <tt>`n'</tt> characters have been written, the
null character is copied, but no other characters are written. If <tt>`n'</tt>
characters are written before a terminating null is encountered, the
function appends its own null character to <tt>`dest'</tt>, 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.
<p><b>Return value:</b>
The return value is the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrcat" title="Concatenates a string to another one.">ustrcat</a>,
<a class="xref" href="#ustrzncat" title="Concatenates a string to another one, specifying size.">ustrzncat</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrzncat">ustrzncat</a>(char *dest, int size, const char *src, int n);</b></div><br>
This function is like ustrzcat() except that no more than <tt>`n'</tt> characters
from <tt>`src'</tt> are appended to the end of <tt>`dest'</tt>. If the terminating null
character in <tt>`src'</tt> is reached before <tt>`n'</tt> characters have been written, the
null character is copied, but no other characters are written. Note that
<tt>`dest'</tt> is guaranteed to be null-terminated.
<p><b>Return value:</b>
The return value is the value of <tt>`dest'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrzcat" title="Concatenates a string to another one, specifying size.">ustrzcat</a>,
<a class="xref" href="#ustrncat" title="Concatenates a string to another one, specifying size.">ustrncat</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrncmp">ustrncmp</a>(const char *s1, const char *s2, int n);</b></div><br>
This function compares up to <tt>`n'</tt> characters of <tt>`s1'</tt> and <tt>`s2'</tt>. Example:
<blockquote class="code"><pre>
if (<a href="#ustrncmp" class="autotype" title="Compares up to n letters of two strings.">ustrncmp</a>(prefix, long_string, <a href="#ustrlen" class="autotype" title="Tells the number of characters in a string.">ustrlen</a>(prefix)) == 0) {
/* long_string starts with prefix */
}</pre></blockquote>
<p><b>Return value:</b>
Returns zero if the substrings are equal, a positive number if <tt>`s1'</tt> comes
after <tt>`s2'</tt> in the ASCII collating sequence, else a negative number.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>,
<a class="xref" href="#ustrcmp" title="Compares two strings.">ustrcmp</a>,
<a class="xref" href="#ustricmp" title="Compares two strings ignoring case.">ustricmp</a>,
<a class="xref" href="#ustrnicmp" title="Compares up to n letters of two strings ignoring case.">ustrnicmp</a>.</blockquote>
<div class="al-api"><b>int <a name="ustricmp">ustricmp</a>(const char *s1, const char *s2);</b></div><br>
This function compares <tt>`s1'</tt> and <tt>`s2'</tt>, ignoring case. Example:
<blockquote class="code"><pre>
if (<a href="#ustricmp" class="autotype" title="Compares two strings ignoring case.">ustricmp</a>(string, user_input) == 0) {
/* string and user_input are equal (ignoring case) */
}</pre></blockquote>
<p><b>Return value:</b>
Returns zero if the strings are equal, a positive number if <tt>`s1'</tt> comes
after <tt>`s2'</tt> in the ASCII collating sequence, else a negative number.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>,
<a class="xref" href="#ustrnicmp" title="Compares up to n letters of two strings ignoring case.">ustrnicmp</a>,
<a class="xref" href="#ustrcmp" title="Compares two strings.">ustrcmp</a>,
<a class="xref" href="#ustrncmp" title="Compares up to n letters of two strings.">ustrncmp</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exconfig" title="Using the configuration routines.">exconfig</a>.</blockquote>
<div class="al-api"><b>int <a name="ustrnicmp">ustrnicmp</a>(const char *s1, const char *s2, int n);</b></div><br>
This function compares up to <tt>`n'</tt> characters of <tt>`s1'</tt> and <tt>`s2'</tt>, ignoring
case. Example:
<blockquote class="code"><pre>
if (<a href="#ustrnicmp" class="autotype" title="Compares up to n letters of two strings ignoring case.">ustrnicmp</a>(prefix, long_string, <a href="#ustrlen" class="autotype" title="Tells the number of characters in a string.">ustrlen</a>(prefix)) == 0) {
/* long_string starts with prefix (ignoring case) */
}</pre></blockquote>
<p><b>Return value:</b>
Returns zero if the strings are equal, a positive number if <tt>`s1'</tt> comes
after <tt>`s2'</tt> in the ASCII collating sequence, else a negative number.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrsize" title="Size of the string in bytes without null terminator.">ustrsize</a>,
<a class="xref" href="#ustrsizez" title="Size of the string in bytes including null terminator.">ustrsizez</a>,
<a class="xref" href="#ustricmp" title="Compares two strings ignoring case.">ustricmp</a>,
<a class="xref" href="#ustrcmp" title="Compares two strings.">ustrcmp</a>,
<a class="xref" href="#ustrncmp" title="Compares up to n letters of two strings.">ustrncmp</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrlwr">ustrlwr</a>(char *s);</b></div><br>
This function replaces all upper case letters in <tt>`s'</tt> with lower case
letters. Example:
<blockquote class="code"><pre>
char buffer[] = "UPPER CASE STRING";
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>(<a href="#ustrlwr" class="autotype" title="Replaces all letters with lower case.">ustrlwr</a>(buffer));</pre></blockquote>
<p><b>Return value:</b>
The return value is the value of <tt>`s'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#utolower" title="Converts a letter to lower case.">utolower</a>,
<a class="xref" href="#ustrupr" title="Replaces all letters with upper case.">ustrupr</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrupr">ustrupr</a>(char *s);</b></div><br>
This function replaces all lower case letters in <tt>`s'</tt> with upper case
letters. Example:
<blockquote class="code"><pre>
char buffer[] = "lower case string";
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>(<a href="#ustrupr" class="autotype" title="Replaces all letters with upper case.">ustrupr</a>(buffer));</pre></blockquote>
<p><b>Return value:</b>
The return value is the value of <tt>`s'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#utolower" title="Converts a letter to lower case.">utolower</a>,
<a class="xref" href="#ustrlwr" title="Replaces all letters with lower case.">ustrlwr</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrchr">ustrchr</a>(const char *s, int c);</b></div><br>
Finds the first occurrence of the character <tt>`c'</tt> in the string <tt>`s'</tt>. Example:
<blockquote class="code"><pre>
char *p = <a href="#ustrchr" class="autotype" title="Finds the first occurrence of a character in a string.">ustrchr</a>("one,two,three,four", ',');</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the first occurrence of <tt>`c'</tt> in <tt>`s'</tt>, or NULL if no
match was found. Note that if <tt>`c'</tt> is NULL, this will return a pointer to
the end of the string.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrrchr" title="Finds the last occurrence of a character in a string.">ustrrchr</a>,
<a class="xref" href="#ustrstr" title="Finds the first occurrence of a string in another one.">ustrstr</a>,
<a class="xref" href="#ustrpbrk" title="Finds the first character that matches any in a set.">ustrpbrk</a>,
<a class="xref" href="#ustrtok" title="Retrieves tokens from a string.">ustrtok</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrrchr">ustrrchr</a>(const char *s, int c);</b></div><br>
Finds the last occurrence of the character <tt>`c'</tt> in the string <tt>`s'</tt>. Example:
<blockquote class="code"><pre>
char *p = <a href="#ustrrchr" class="autotype" title="Finds the last occurrence of a character in a string.">ustrrchr</a>("one,two,three,four", ',');</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer for the last occurrence of <tt>`c'</tt> in <tt>`s'</tt>, or NULL if no
match was found.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrchr" title="Finds the first occurrence of a character in a string.">ustrchr</a>,
<a class="xref" href="#ustrstr" title="Finds the first occurrence of a string in another one.">ustrstr</a>,
<a class="xref" href="#ustrpbrk" title="Finds the first character that matches any in a set.">ustrpbrk</a>,
<a class="xref" href="#ustrtok" title="Retrieves tokens from a string.">ustrtok</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrstr">ustrstr</a>(const char *s1, const char *s2);</b></div><br>
This function finds the first occurrence of string <tt>`s2'</tt> in string <tt>`s1'</tt>.
Example:
<blockquote class="code"><pre>
char *p = <a href="#ustrstr" class="autotype" title="Finds the first occurrence of a string in another one.">ustrstr</a>("hello world", "world");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer within <tt>`s1'</tt>, or NULL if <tt>`s2'</tt> wasn't found.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrchr" title="Finds the first occurrence of a character in a string.">ustrchr</a>,
<a class="xref" href="#ustrrchr" title="Finds the last occurrence of a character in a string.">ustrrchr</a>,
<a class="xref" href="#ustrpbrk" title="Finds the first character that matches any in a set.">ustrpbrk</a>,
<a class="xref" href="#ustrtok" title="Retrieves tokens from a string.">ustrtok</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrpbrk">ustrpbrk</a>(const char *s, const char *set);</b></div><br>
This function finds the first character in <tt>`s'</tt> that matches any character
in <tt>`set'</tt>. Example:
<blockquote class="code"><pre>
char *p = <a href="#ustrpbrk" class="autotype" title="Finds the first character that matches any in a set.">ustrpbrk</a>("one,two-three.four", "-. ");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the first match, or NULL if none are found.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrchr" title="Finds the first occurrence of a character in a string.">ustrchr</a>,
<a class="xref" href="#ustrrchr" title="Finds the last occurrence of a character in a string.">ustrrchr</a>,
<a class="xref" href="#ustrstr" title="Finds the first occurrence of a string in another one.">ustrstr</a>,
<a class="xref" href="#ustrtok" title="Retrieves tokens from a string.">ustrtok</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrtok">ustrtok</a>(char *s, const char *set);</b></div><br>
This function retrieves tokens from <tt>`s'</tt> which are delimited by characters
from <tt>`set'</tt>. To initiate the search, pass the string to be searched as <tt>`s'</tt>.
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:
<blockquote class="code"><pre>
char *word;
char string[]="some-words with dashes";
char *temp = <a href="#ustrdup" class="autotype" title="Duplicates a string.">ustrdup</a>(string);
word = <a href="#ustrtok" class="autotype" title="Retrieves tokens from a string.">ustrtok</a>(temp, " -");
while (word) {
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Found `%s'\n", word);
word = <a href="#ustrtok" class="autotype" title="Retrieves tokens from a string.">ustrtok</a>(NULL, " -");
}
free(temp);</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the token, or NULL if no more are found.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrchr" title="Finds the first occurrence of a character in a string.">ustrchr</a>,
<a class="xref" href="#ustrrchr" title="Finds the last occurrence of a character in a string.">ustrrchr</a>,
<a class="xref" href="#ustrstr" title="Finds the first occurrence of a string in another one.">ustrstr</a>,
<a class="xref" href="#ustrpbrk" title="Finds the first character that matches any in a set.">ustrpbrk</a>,
<a class="xref" href="#ustrtok_r" title="Reentrant function to retrieve tokens from a string.">ustrtok_r</a>,
<a class="xref" href="alleg000.html#allegro_message" title="Used mainly to show error messages to users.">allegro_message</a>,
<a class="xref" href="#ustrncpy" title="Copies a string into another one, specifying size.">ustrncpy</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>char *<a name="ustrtok_r">ustrtok_r</a>(char *s, const char *set, char **last);</b></div><br>
Reentrant version of ustrtok. The <tt>`last'</tt> 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:
<blockquote class="code"><pre>
char *word, *last;
char string[]="some-words with dashes";
char *temp = <a href="#ustrdup" class="autotype" title="Duplicates a string.">ustrdup</a>(string);
word = <a href="#ustrtok_r" class="autotype" title="Reentrant function to retrieve tokens from a string.">ustrtok_r</a>(string, " -", &last);
while (word) {
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Found `%s'\n", word);
word = <a href="#ustrtok_r" class="autotype" title="Reentrant function to retrieve tokens from a string.">ustrtok_r</a>(NULL, " -", &last);
}
free(temp);</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the token, or NULL if no more are found. You can free
the memory pointed to by <tt>`last'</tt> once NULL is returned.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ustrtok" title="Retrieves tokens from a string.">ustrtok</a>.</blockquote>
<div class="al-api"><b>double <a name="uatof">uatof</a>(const char *s);</b></div><br>
Convert as much of the string as possible to an equivalent double
precision real number. This function is almost like `ustrtod(s, NULL)'.
<p><b>Return value:</b>
Returns the equivalent value, or zero if the string does not represent a
number.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrtol" title="Converts a string into an integer.">ustrtol</a>,
<a class="xref" href="#ustrtod" title="Converts a string into a floating point number.">ustrtod</a>.</blockquote>
<div class="al-api"><b>long <a name="ustrtol">ustrtol</a>(const char *s, char **endp, int base);</b></div><br>
This function converts the initial part of <tt>`s'</tt> to a signed integer, setting
`*endp' to point to the first unused character, if <tt>`endp'</tt> is not a NULL
pointer. The <tt>`base'</tt> argument indicates what base the digits (or letters)
should be treated as. If <tt>`base'</tt> is zero, the base is determined by looking
for <tt>`0x'</tt>, <tt>`0X'</tt>, or <tt>`0'</tt> 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:
<blockquote class="code"><pre>
char *endp, *string = "456.203 askdfg";
int number = <a href="#ustrtol" class="autotype" title="Converts a string into an integer.">ustrtol</a>(string, &endp, 10);</pre></blockquote>
<p><b>Return value:</b>
Returns the string converted as a value of type `long int'. If nothing was
converted, returns zero with `*endp' pointing to the beginning of <tt>`s'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrtod" title="Converts a string into a floating point number.">ustrtod</a>,
<a class="xref" href="#uatof" title="Converts a string into a double.">uatof</a>.</blockquote>
<div class="al-api"><b>double <a name="ustrtod">ustrtod</a>(const char *s, char **endp);</b></div><br>
This function converts as many characters of <tt>`s'</tt> that look like a floating
point number into one, and sets `*endp' to point to the first unused
character, if <tt>`endp'</tt> is not a NULL pointer. Example:
<blockquote class="code"><pre>
char *endp, *string = "456.203 askdfg";
double number = <a href="#ustrtod" class="autotype" title="Converts a string into a floating point number.">ustrtod</a>(string, &endp);</pre></blockquote>
<p><b>Return value:</b>
Returns the string converted as a value of type <tt>`double'</tt>. If nothing was
converted, returns zero with *endp pointing to the beginning of s.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#ustrtol" title="Converts a string into an integer.">ustrtol</a>,
<a class="xref" href="#uatof" title="Converts a string into a double.">uatof</a>.</blockquote>
<div class="al-api"><b>const char *<a name="ustrerror">ustrerror</a>(int err);</b></div><br>
This function returns a string that describes the error code <tt>`err'</tt>, which
normally comes from the variable <tt>`errno'</tt>. Example:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *input_file = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("badname", "r");
if (input_file == NULL)
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("%s\nSorry!\n", <a href="#ustrerror" class="autotype" title="Returns a string describing errno.">ustrerror</a>(errno));</pre></blockquote>
<p><b>Return value:</b>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="alleg000.html#allegro_error" title="Stores the last Allegro error message.">allegro_error</a>.</blockquote>
<div class="al-api"><b>int <a name="usprintf">usprintf</a>(char *buf, const char *format, ...);</b></div><br>
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.
<p><b>Return value:</b>
Returns the number of characters written, not including the terminating
null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#uszprintf" title="Writes formatted data into a buffer, specifying size.">uszprintf</a>,
<a class="xref" href="#uvsprintf" title="Writes formatted data into a buffer, using variable arguments.">uvsprintf</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exkeys" title="How to get input from the keyboard in different ways.">exkeys</a>.</blockquote>
<div class="al-api"><b>int <a name="uszprintf">uszprintf</a>(char *buf, int size, const char *format, ...);</b></div><br>
This function writes formatted data into the output buffer, whose length
in bytes is specified by <tt>`size'</tt> and which is guaranteed to be NULL
terminated. Example:
<blockquote class="code"><pre>
char buffer[10];
int player_score;
...
<a href="#uszprintf" class="autotype" title="Writes formatted data into a buffer, specifying size.">uszprintf</a>(buffer, sizeof(buffer), "Your score is: %d", player_score);</pre></blockquote>
<p><b>Return value:</b>
Returns the number of characters that would have been written without
eventual truncation (like with usprintf), not including the terminating
null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#usprintf" title="Writes formatted data into a buffer.">usprintf</a>,
<a class="xref" href="#uvszprintf" title="Writes formatted data into a buffer, using size and variable arguments.">uvszprintf</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="uvsprintf">uvsprintf</a>(char *buf, const char *format, va_list args);</b></div><br>
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.
<p><b>Return value:</b>
Returns the number of characters written, not including the terminating
null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#usprintf" title="Writes formatted data into a buffer.">usprintf</a>,
<a class="xref" href="#uvszprintf" title="Writes formatted data into a buffer, using size and variable arguments.">uvszprintf</a>.</blockquote>
<div class="al-api"><b>int <a name="uvszprintf">uvszprintf</a>(char *buf, int size, const char *format, va_list args);</b></div><br>
This is like uszprintf(), but you pass the variable argument list
directly, instead of the arguments themselves. Example:
<blockquote class="code"><pre>
#include <stdarg.h>
void log_message(const char *format, ...)
{
char buffer[100];
va_list parameters;
va_start(parameters, format);
<a href="#uvszprintf" class="autotype" title="Writes formatted data into a buffer, using size and variable arguments.">uvszprintf</a>(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);
}</pre></blockquote>
<p><b>Return value:</b>
Returns the number of characters that would have been written without
eventual truncation (like with uvsprintf), not including the terminating
null character.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#uconvert" title="High level string encoding conversion wrapper.">uconvert</a>,
<a class="xref" href="#uszprintf" title="Writes formatted data into a buffer, specifying size.">uszprintf</a>,
<a class="xref" href="#uvsprintf" title="Writes formatted data into a buffer, using variable arguments.">uvsprintf</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
x86_64
>
media
>
main
>
by-pkgid
>
c13bc007afe382f898b3b1cfcaf62e82
>
files
>
775
