gnu/dist/gettext/gettext-runtime/libasprintf/autosprintf.texi

   1 \input texinfo          @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename autosprintf.info
   4 @settitle GNU @code{autosprintf}
   5 @finalout
   6 @c Indices:
   7 @c   none
   8 @c Unused predefined indices:
   9 @c   cp = concept         @cindex
  10 @c   fn = function        @findex
  11 @c   vr = variable        @vindex
  12 @c   ky = keystroke       @kindex
  13 @c   pg = program         @pindex
  14 @c   tp = type            @tindex
  15 @c %**end of header
  16 @set VERSION 1.0
  17
  18 @dircategory C++ libraries
  19 @direntry
  20 * autosprintf: (autosprintf).   Support for printf format strings in C++.
  21 @end direntry
  22
  23 @ifinfo
  24 This file provides documentation for GNU @code{autosprintf} library.
  25
  26 Copyright (C) 2002 Free Software Foundation, Inc.
  27
  28 Permission is granted to make and distribute verbatim copies of
  29 this manual provided the copyright notice and this permission notice
  30 are preserved on all copies.
  31
  32 @ignore
  33 Permission is granted to process this file through TeX and print the
  34 results, provided the printed document carries copying permission
  35 notice identical to this one except for the removal of this paragraph
  36 (this paragraph not being relevant to the printed manual).
  37
  38 @end ignore
  39 Permission is granted to copy and distribute modified versions of this
  40 manual under the conditions for verbatim copying, provided that the entire
  41 resulting derived work is distributed under the terms of a permission
  42 notice identical to this one.
  43
  44 Permission is granted to copy and distribute translations of this manual
  45 into another language, under the above conditions for modified versions,
  46 except that this permission notice may be stated in a translation approved
  47 by the Foundation.
  48 @end ifinfo
  49
  50 @titlepage
  51 @title GNU autosprintf, version @value{VERSION}
  52 @subtitle Formatted Output to Strings in C++
  53 @author Bruno Haible
  54
  55 @page
  56 @vskip 0pt plus 1filll
  57 Copyright @copyright{} 2002 Free Software Foundation, Inc.
  58
  59 Permission is granted to make and distribute verbatim copies of
  60 this manual provided the copyright notice and this permission notice
  61 are preserved on all copies.
  62
  63 Permission is granted to copy and distribute modified versions of this
  64 manual under the conditions for verbatim copying, provided that the entire
  65 resulting derived work is distributed under the terms of a permission
  66 notice identical to this one.
  67
  68 Permission is granted to copy and distribute translations of this manual
  69 into another language, under the above conditions for modified versions,
  70 except that this permission notice may be stated in a translation approved
  71 by the Foundation.
  72 @end titlepage
  73
  74 @ifinfo
  75 @node Top, Introduction, (dir), (dir)
  76 @top GNU autosprintf
  77
  78 This manual documents the GNU autosprintf class, version @value{VERSION}.
  79
  80 @menu
  81 * Introduction::                Introduction
  82 * Class autosprintf::           The @code{autosprintf} class
  83 * Using autosprintf::           Using @code{autosprintf} in own programs
  84 @end menu
  85
  86 @end ifinfo
  87
  88 @node Introduction, Class autosprintf, Top, Top
  89 @chapter Introduction
  90
  91 This package makes the C formatted output routines (@code{fprintf} et al.)
  92 usable in C++ programs, for use with the @code{<string>} strings and the
  93 @code{<iostream>} streams.
  94
  95 It allows to write code like
  96
  97 @smallexample
  98 cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
  99 @end smallexample
 100
 101 @noindent
 102 instead of
 103
 104 @smallexample
 105 cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
 106 @end smallexample
 107
 108 The benefits of the autosprintf syntax are:
 109
 110 @itemize @bullet
 111 @item
 112 It reuses the standard POSIX printf facility. Easy migration from C to C++.
 113
 114 @item
 115 English sentences are kept together.
 116
 117 @item
 118 It makes internationalization possible. Internationalization requires format
 119 strings, because in some cases the translator needs to change the order of a
 120 sentence, and more generally it is easier for the translator to work with a
 121 single string for a sentence than with multiple string pieces.
 122
 123 @item
 124 It reduces the risk of programming errors due to forgotten state in the
 125 output stream (e.g. @code{cout << hex;} not followed by @code{cout << dec;}).
 126 @end itemize
 127
 128 @node Class autosprintf, Using autosprintf, Introduction, Top
 129 @chapter The @code{autosprintf} class
 130
 131 An instance of class @code{autosprintf} just contains a string with the
 132 formatted output result. Such an instance is usually allocated as an
 133 automatic storage variable, i.e. on the stack, not with @code{new} on the
 134 heap.
 135
 136 The constructor @code{autosprintf (const char *format, ...)} takes a format
 137 string and additional arguments, like the C function @code{printf}.
 138
 139 Conversions to @code{char *} and @code{std::string} are defined that return
 140 the encapsulated string.
 141
 142 The destructor @code{~autosprintf ()} destroys the encapsulated string.
 143
 144 An @code{operator <<} is provided that outputs the encapsulated string to the
 145 given @code{ostream}.
 146
 147 @node Using autosprintf,  , Class autosprintf, Top
 148 @chapter Using @code{autosprintf} in own programs
 149
 150 To use the @code{autosprintf} class in your programs, you need to add
 151
 152 @smallexample
 153 #include "autosprintf.h"
 154 using gnu::autosprintf;
 155 @end smallexample
 156
 157 @noindent
 158 to your source code.
 159 The include file defines the class @code{autosprintf}, in a namespace called
 160 @code{gnu}. The @samp{using} statement makes it possible to use the class
 161 without the (otherwise natural) @code{gnu::} prefix.
 162
 163 When linking your program, you need to link with @code{libasprintf}, because
 164 that's where the class is defined. In projects using GNU @code{autoconf},
 165 this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in}
 166 or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that
 167 it provides.
 168
 169 @bye
 170
 171 @c Local variables:
 172 @c texinfo-column-for-description: 32
 173 @c End: