Pileus Git - ~andy/fetchmail/blob - trio/doc/doc.h

   1 /*************************************************************************
   2  *
   3  * $Id: doc.h,v 1.20 2006/08/18 11:32:08 breese Exp $
   4  *
   5  * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg.
   6  *
   7  * Permission to use, copy, modify, and distribute this software for any
   8  * purpose with or without fee is hereby granted, provided that the above
   9  * copyright notice and this permission notice appear in all copies.
  10  *
  11  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  12  * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  13  * MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND
  14  * CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER.
  15  *
  16  ************************************************************************/
  17
  18 /**
  19 @mainpage
  20
  21 @author Bjørn Reese
  22 @author Daniel Stenberg
  23
  24 @section intro Introduction
  25
  26 Trio is a fully matured and stable set of printf and string functions
  27 designed be used by applications with focus on portability or with the
  28 need for additional features that are not supported by standard stdio
  29 implementation.
  30
  31 There are several cases where you may want to consider using trio:
  32
  33 @li Portability across heterogeneous platforms.
  34 @li Embedded systems without stdio support.
  35 @li Extendability of unsupported features.
  36 @li Your native version does not do everything you need.
  37
  38 When you write applications that must be portable to a wide range of
  39 platforms you often have to deal with inadequate implementations of the
  40 stdio library functions. Most notably is the lack of secure formatting
  41 functions, such as snprintf, or the lack of parameter reordering commonly
  42 used for the internationalization of applications, such as the <num>$
  43 modifier. Sometimes the feature you need is simply not present in stdio.
  44 So you end up spending much effort on determining which platforms supports
  45 what, and to write your own versions of various features. This is where
  46 trio can help you. Trio is a platform-independent implementation of the
  47 stdio printf and scanf functions and the string library functions.
  48
  49 The functionality described in the stdio standards is a compromise, and
  50 does unfortunately not include a mechanism to extend the functionality for
  51 an individual application. Oftentimes an application has the need for an
  52 extra feature, and the application code can become much more clear and
  53 readable by using an extension mechanism. Trio supports a range of useful
  54 extensions such as user-defined specifiers, passing of arguments in arrays,
  55 localized string scanning, thousand-separators, and arbitrary integer bases.
  56
  57 Trio fully implements the C99 (ISO/IEC 9899:1999) and UNIX98 (the Single
  58 Unix Specification, Version 2) standards, as well as many features from
  59 other implemenations, e.g. the GNU libc and BSD4.
  60
  61 @section examples Examples
  62
  63 @subsection ex1 Binary Numbers
  64 Output an integer as a binary number using a trio extension.
  65 @verbatim
  66   trio_printf("%..2i\n", number);
  67 @endverbatim
  68
  69 @subsection ex2 Thousand-separator
  70 Output a number with thousand-separator using a trio extension.
  71 @verbatim
  72   trio_printf("%'f\n", 12345.6);
  73 @endverbatim
  74 The thousand-separator described by the locale is used.
  75
  76 @subsection ex3 Fixed Length Array and Sticky Modifier
  77 Output an fixed length array of floating-point numbers.
  78 @verbatim
  79   double array[] = {1.0, 2.0, 3.0};
  80   printf("%.2f %.2f %.2f\n", array[0], array[1], array[2]);
  81 @endverbatim
  82 The same with two trio extensions (arguments are passed in an array, and
  83 the first formatting specifier sets the sticky option so we do not have
  84 to type all the formatting modifiers for the remaining formatting specifiers)
  85 @verbatim
  86   trio_printfv("%!.2f %f %f\n", array);
  87 @endverbatim
  88 Another, and more powerful, application of being able to pass arguments in
  89 an array is the creation of the printf/scanf statement at run-time, where
  90 the formatting string, and thus the argument list, is based on an external
  91 configuration file.
  92
  93 @subsection ex4 Localized scanning
  94 Parse a string consisting of one or more upper-case alphabetic characters
  95 followed by one or more numeric characters.
  96 @verbatim
  97   sscanf(buffer, "%[A-Z]%[0-9]", alphabetic, numeric);
  98 @endverbatim
  99 The same but with locale using a trio extension.
 100 @verbatim
 101   trio_sscanf(buffer, "%[[:upper:]]%[[:digit:]]", alphabetic, numeric);
 102 @endverbatim
 103
 104 @section legal Legal Issues
 105 Trio is distributed under the following license, which allows practically
 106 anybody to use it in almost any kind of software, including proprietary
 107 software, without difficulty.
 108
 109 "Copyright (C) 1998-2001 Bjorn Reese and Daniel Stenberg.
 110
 111 Permission to use, copy, modify, and distribute this software for any
 112 purpose with or without fee is hereby granted, provided that the above
 113 copyright notice and this permission notice appear in all copies.
 114
 115 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
 116 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 117 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND
 118 CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER."
 119
 120 @section contribution Contribution
 121
 122 @subsection contribute Contribute
 123 We appreciate any type of contribution, from ideas over improvements to
 124 error corrections.
 125
 126 The project space contains references to bug and feature tracking,
 127 mailing-list, and the CVS repository. We prefer communication via the
 128 mailing-list, but do not require you to be subscribed, because trio is a
 129 small project.
 130
 131 The project space is located at http://sourceforge.net/projects/ctrio/
 132
 133 @subsection contributors Contributors
 134 We have received contributions from the following persons (in alphabetic
 135 order sorted by surname)
 136
 137 @li Craig Berry
 138 @li Karl Bochert
 139 @li Stan Boehm
 140 @li David Byron
 141 @li Brian Chapman
 142 @li Robert Collins
 143 @li Danny Dulai
 144 @li Bob Friesenhahn
 145 @li Jon Foster
 146 @li John Fotheringham
 147 @li Markus Henke
 148 @li Ken Gibson
 149 @li Paul Janzen
 150 @li Patrick Jessee
 151 @li Richard Jinks
 152 @li Tero Jänkä
 153 @li Howard Kapustein
 154 @li Rune Enggaard Lausen
 155 @li Mehdi Lavasani
 156 @li Alexander Lukyanov
 157 @li Andreas Maus
 158 @li Mikey Menezes
 159 @li Emmanuel Mogenet
 160 @li Jacob Navia
 161 @li Jose Ortiz
 162 @li Joe Orton
 163 @li Gisli Ottarsson
 164 @li Mark Pickelmann
 165 @li Olli Savia
 166 @li Shaun Tancheff
 167 @li Marc Werwerft
 168 @li Igor Zlatkovic
 169
 170 Please let us know, and accept our apology, if we have omitted anybody.
 171
 172 */