gnu/dist/gettext/gettext-runtime/libasprintf/README

   1             GNU libasprintf - automatic formatted output to strings
   2
   3 This package makes the C formatted output routines (fprintf et al.) usable
   4 in C++ programs.
   5
   6
   7 Sample use
   8 ----------
   9
  10   char *pathname = autosprintf ("%s/%s", directory, filename);
  11   cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
  12
  13
  14 Benefits
  15 --------
  16
  17 The benefits of autosprintf over the usual "piecewise meal" idiom
  18
  19   cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
  20
  21 are:
  22
  23   - Reuses of the standard POSIX printf facility. Easy migration from C to C++.
  24
  25   - English sentences are kept together.
  26
  27   - Internationalization requires format strings, because
  28     1. Internationalization requires the ability for the translator to change
  29        the order of parts of a sentence. The POSIX printf formatted output
  30        functions (and thus also autosprintf) support this through the %m$ and
  31        *m$ syntax.
  32     2. Translators are used to translate one string per sentence, not
  33        multiple strings per sentence, and not C++ code statements.
  34
  35   - Reduces the risk of programming errors due to forgotten state in the
  36     output stream (e.g.  'cout << hex;'  not followed by  'cout << dec;').
  37
  38 The benefits of autosprintf over C sprintf are:
  39
  40   - Autosprintf avoids buffer overruns and truncated results.
  41     The C sprintf() function often leads to buffer overruns. On the other
  42     hand, the C snprintf() function requires extra coding for an a priori
  43     estimate of the result's size and truncates the result if the estimate
  44     was too low.
  45
  46   - Autosprintf avoids memory leaks.
  47     Temporarily allocated memory is cleaned up automatically.
  48
  49
  50 Installation
  51 ------------
  52
  53 See INSTALL. Usually "./configure; make; make install" should work.
  54
  55 The installed files are:
  56   - An include file "autosprintf.h" which defines the class 'autosprintf',
  57     in the namespace 'gnu'.
  58   - A library libasprintf containing this class.
  59
  60
  61 Use
  62 ---
  63
  64 To use the class autosprintf, use
  65
  66   #include "autosprintf.h"
  67   using gnu::autosprintf;
  68
  69 and link with the linker option
  70
  71   -lasprintf
  72
  73
  74 Misc notes
  75 ----------
  76
  77 An instance of class 'autosprintf' contains the formatted output result;
  78 this string is freed when the instance's destructor is run.
  79
  80 The class name 'autosprintf' is meant to remind the C function sprintf(),
  81 the GNU C library function asprintf(), and the C++ autoptr programming idiom.
  82
  83
  84 Distribution
  85 ------------
  86     http://www.haible.de/bruno/gnu/libasprintf-1.0.tar.gz
  87
  88 Homepage
  89 --------
  90     http://www.haible.de/bruno/packages-libasprintf.html
  91
  92 Bug reports to:
  93 ---------------
  94     <bug-gnu-gettext@gnu.org>
  95
  96
  97 Bruno Haible <brunoe@clisp.org>