---

Formatted Printing Functions.

Variations of formatted printing functions. More...

Functions
int	trio_printf (const char *format,...)
	Print to standard output stream. More...
int	trio_vprintf (const char *format, va_list args)
	Print to standard output stream. More...
int	trio_printfv (const char *format, trio_pointer_t *args)
	Print to standard output stream. More...
int	trio_fprintf (FILE *file, const char *format,...)
	Print to file. More...
int	trio_vfprintf (FILE *file, const char *format, va_list args)
	Print to file. More...
int	trio_fprintfv (FILE *file, const char *format, trio_pointer_t *args)
	Print to file. More...
int	trio_dprintf (int fd, const char *format,...)
	Print to file descriptor. More...
int	trio_vdprintf (int fd, const char *format, va_list args)
	Print to file descriptor. More...
int	trio_dprintfv (int fd, const char *format, trio_pointer_t *args)
	Print to file descriptor. More...
int	trio_sprintf (char *buffer, const char *format,...)
	Print to string. More...
int	trio_vsprintf (char *buffer, const char *format, va_list args)
	Print to string. More...
int	trio_sprintfv (char *buffer, const char *format, trio_pointer_t *args)
	Print to string. More...
int	trio_snprintf (char *buffer, size_t max, const char *format,...)
	Print at most max characters to string. More...
int	trio_vsnprintf (char *buffer, size_t max, const char *format, va_list args)
	Print at most max characters to string. More...
int	trio_snprintfv (char *buffer, size_t max, const char *format, trio_pointer_t *args)
	Print at most max characters to string. More...

---

Detailed Description

Variations of formatted printing functions.

SYNOPSIS

cc ... -ltrio -lm

#include <trio.h>

DESCRIPTION

This documentation is incomplete. The documentation of the printf family in [C99] and [UNIX98] also applies to the trio counterparts.

All these functions outputs a string which is formatted according to the format string and the consecutive arguments. The format string is described in the Formatting section below.

trio_printf, trio_vprintf, and trio_printfv writes the output to the standard output stream (stdout).

trio_fprintf, trio_vfprintf, and trio_fprintfv writes the output to a given output stream.

trio_dprintf, trio_vdprintf, and trio_dprintfv writes the output to a file descriptor (this includes, for example, sockets).

trio_sprintf, trio_vsprintf, and trio_sprintfv writes the output into buffer.

trio_snprintf, trio_vsnprintf, and trio_snprintfv writes max - 1 characters into buffer followed by a terminating zero character. If max is 1, then buffer will be an empty string. If max is 0, then buffer is left untouched, and can consequently be NULL. The number of characters that would have been written to buffer, had there been sufficient space, is returned.

trio_snprintfcat appends the formatted text at the end of buffer.

trio_asprintf and trio_vasprintf allocates and returns an allocated string in buffer containing the formatted text.

FORMATTING

The format string can contain normal text and conversion indicators. The normal text can be any character except the nil character (\000 = '\0') and the percent character (\045 = '%'). Conversion indicators consists of an indication character (%), followed by zero or more conversion modifiers, and exactly one conversion specifier.

Modifiers

Some modifiers exhibit the same behaviour for all specifiers, other modifiers indicate different behaviours for different specifiers, and other modifiers are only applicable to certain specifiers. The relationship is described for each modifier. The number 9 is used to denotes an arbitrary integer.

Positional ( 9$ ) [UNIX98]

Normally the arguments supplied to these functions are interpreted incrementially from left to right. Arguments can be referenced specifically in the format string. The modifier n$ selects the nth argument. The first argument is referred as 1$. If this modifier is used, it must be the first modifier after the indication character. n$ can also be used for argument width, precision, and base.

The performance penalty of using positionals is almost neglible (contrary to most other printf implementations).

• Reference Mix. Mixing normal and positional specifiers is allowed [TRIO]. For example,

    trio_printf("%d %3$d %2$d\n", 1, 2, 3);
  

  results in

    1 3 2
  

  Arguments for the printf family are passed on the stack. On most platforms it is not possible to determine the size of individual stack elements, so it is essential that the format string corresponds exactly to the passed arguments. If this is not the case, incorrect values may be put into the result.

• Reference Gap. For the same reason it is also essential that the format string does not contain any "gaps" in the positional arguments. For example,

    trio_printf("%1$d %3$d\n", 1, 2, 3);
  

  is NOT allowed. The format string parser has no knowledge about whether the second argument is, say, an integer or a long double (which have different sizes).
  [UNIX98] describes this as unspecified behaviour. [TRIO] will detect reference gaps and return an error.

• Double Reference. It is also not allowed to reference an argument twice or more. For example,

    trio_printf("%1$d %1$lf\n", 1);
  

  is NOT allowed, because it references the first argument as two differently sized objects.
  [UNIX98] describes this as unspecified behaviour. [TRIO] will detect double references and return an error.

The following two statements are equivalent

  trio_printf("|%d %s\n|", 42, "meanings");
  |42 meanings|

  trio_printf("|%1$d %2$s|\n", 42, "meanings");
  |42 meanings|

Width ( 9 )

Specifies the minimum width of a field. If the fields has less characters than specified by the width, the field will be left adjusted and padded by spaces. The adjustment and padding can be changed by the Alignment ( - ) and Padding ( 0 ) modifiers.

The width is specified as a number. If an asterix ( * ) is used instead, the width will be read from the argument list.

Prefixes, such as 0x for hexadecimal integers, are part of width.

  trio_printf("|%10i|\n", 42);
  |        42|

Precision ( .9 )

The precision has different semantics for the various data types. The precision specifies the maximum number of printed characters for strings, the number of digits after the decimal-point for floating-point numbers, the number of significant digits for the g (and G) representation of floating-point numbers, the minimum number of printed digits for integers.

  trio_printf("|%10.8i|%.8i|\n", 42, 42);
  |  00000042|00000042|

Base ( ..9 ) [TRIO]

Sets the base that the associated integer must be converted to. The base can be between 2 and 36 (both included).

  trio_printf("|%10.8.2i|%10..2i|%..2i|\n", 42, 42, 42);
  |  00101010|    101010|101010|

  trio_printf("|%*.8.*i|\n", 10, 2, 42);
  |  00101010|

Padding ( 0 )

Integer and floating point numbers are prepended by zeros. The number of leading zeros are determined by the precision. If precision is not present, width is used instead.

Short ( h )

Integer arguments are read as an ( unsigned ) short int. String and character arguments are read as char * and char respectively.

Short short ( hh ) [C99, GNU]

The argument is read as an ( unsigned ) char.

Fixed Size ( I ) [MSVC]

The argument is read as a fixed sized integer. The modifier is followed by a number, which specifies the number of bits in the integer, and can be one of the following

• I8
• I16
• I32
• I64 (if 64-bits integers are supported)

Works only for integers (i, u, d, o, x, X)

Largest ( j ) [C99]

The argument is read as an intmax_t / uintmax_t, which is defined to be the largest signed/unsigned integer.

Long ( l )

An integral argument is read as an ( unsigned ) long int. A string argument is read as a wchar_t *, and output as a multi-byte character sequence.

Long long ( ll ) [C99, UNIX98, GNU]

The argument is read as an ( unsigned ) long long int.

Long double ( L ) [C99, UNIX98, GNU]

The argument is read as a long double.

ptrdiff_t ( t ) [C99]

The argument is read as a ptrdiff_t, which is defined to be the signed integer type of the result of subtracting two pointers.

Quad ( q ) [BSD, GNU]

Corresponds to the long long modifier ( ll ).

Wide ( w ) [MISC]

For a string argument this is equivalent to using the long modifier ( l ).

size_t ( z ) [C99]

The argument is read as a size_t, which is defined to be the type returned by the sizeof operator.

size_t ( Z ) [GNU]

Corresponds to the size_t modifier ( z ).

Alternative ( # )

Prepend radix indicator for hexadecimal, octal, and binary integer numbers and for pointers. Always add a decimal-pointer for floating-point numbers. Escape non-printable characters for strings.

Spacing ( )

Prepend leading spaces when necessary.

Sign ( + )

Always prepend a sign to numbers. Normally only the negative sign is prepended to a number. With this modifier the positive sign may also be prepended.

Alignment ( - )

The output will be left-j

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
 <title>TRIO</title>
 <link href="trio.css" rel="stylesheet" type="text/css">
</head>
<body>
<!-- Generated by Doxygen 1.2.12 -->
<center>
<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="modules.html">Modules</a> &nbsp; </center>
<hr><h1>Dynamic String Functions.</h1>Dynamic string functions. 
<a href="#_details">More...</a><table border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC trio_string_t *&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a3">trio_string_create</a> (int initial_size)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Create a new dynamic string.</em> <a href="#a3">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC void&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a4">trio_string_destroy</a> (trio_string_t *self)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Deallocate the dynamic string and its contents.</em> <a href="#a4">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC char *&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a5">trio_string_get</a> (trio_string_t *self, int offset)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Get a pointer to the content.</em> <a href="#a5">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC char *&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a6">trio_string_extract</a> (trio_string_t *self)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Extract the content.</em> <a href="#a6">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC void&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a7">trio_xstring_set</a> (trio_string_t *self, char *buffer)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Set the content of the dynamic string.</em> <a href="#a7">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC int&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a10">trio_string_append</a> (trio_string_t *self, trio_string_t *other)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Append the second string to the first.</em> <a href="#a10">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>TRIO_STRING_PUBLIC int&nbsp;</td><td valign=bottom><a class="el" href="group___dynamic_strings.html#a13">trio_string_contains</a> (trio_string_t *self, trio_string_t *other)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Search for the first occurrence of second parameter in the first.</em> <a href="#a13">More...</a><em></em></font><br><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
Dynamic string functions.
<p>
<b>SYNOPSIS</b>
<p>
<div class="fragment"><pre>
cc ... -ltrio -lm

#include &lt;triostr.h&gt;
</pre></div>
<p>
<b>DESCRIPTION</b> <hr><h2>Function Documentation</h2>
<a name="a10" doxytag="triostr.c::trio_string_append"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> TRIO_STRING_PUBLIC int trio_string_append </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">trio_string_t *&nbsp;</td>
          <td class="mdname" nowrap>&nbsp; <em>self</em>, </td>
        </tr>
        <tr>
          <td></td>
          <td></td>
          <td class="md" nowrap>trio_string_t *&nbsp;</td>
          <td class="mdname" nowrap>&nbsp; <em>other</em></td>
        </tr>
        <tr>
          <td></td>
          <td class="md">)