gnu/dist/gettext/gettext-runtime/libasprintf/autosprintf_all.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52a
   4      from autosprintf.texi on 18 January 2004 -->
   5
   6 <TITLE>GNU autosprintf</TITLE>
   7 </HEAD>
   8 <BODY>
   9 <H1>GNU autosprintf, version 1.0</H1>
  10 <H2>Formatted Output to Strings in C++</H2>
  11 <ADDRESS>Bruno Haible</ADDRESS>
  12 <P>
  13 <P><HR><P>
  14 <H1>Table of Contents</H1>
  15 <UL>
  16 <LI><A NAME="TOC1" HREF="autosprintf.html#SEC1">1  Introduction</A>
  17 <LI><A NAME="TOC2" HREF="autosprintf.html#SEC2">2  The <CODE>autosprintf</CODE> class</A>
  18 <LI><A NAME="TOC3" HREF="autosprintf.html#SEC3">3  Using <CODE>autosprintf</CODE> in own programs</A>
  19 </UL>
  20 <P><HR><P>
  21
  22
  23 <H1><A NAME="SEC1" HREF="autosprintf.html#TOC1">1  Introduction</A></H1>
  24
  25 <P>
  26 This package makes the C formatted output routines (<CODE>fprintf</CODE> et al.)
  27 usable in C++ programs, for use with the <CODE>&#60;string&#62;</CODE> strings and the
  28 <CODE>&#60;iostream&#62;</CODE> streams.
  29
  30 </P>
  31 <P>
  32 It allows to write code like
  33
  34 </P>
  35
  36 <PRE>
  37 cerr &#60;&#60; autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
  38 </PRE>
  39
  40 <P>
  41 instead of
  42
  43 </P>
  44
  45 <PRE>
  46 cerr &#60;&#60; "syntax error in " &#60;&#60; filename &#60;&#60; ":" &#60;&#60; line &#60;&#60; ": " &#60;&#60; errstring;
  47 </PRE>
  48
  49 <P>
  50 The benefits of the autosprintf syntax are:
  51
  52 </P>
  53
  54 <UL>
  55 <LI>
  56
  57 It reuses the standard POSIX printf facility. Easy migration from C to C++.
  58
  59 <LI>
  60
  61 English sentences are kept together.
  62
  63 <LI>
  64
  65 It makes internationalization possible. Internationalization requires format
  66 strings, because in some cases the translator needs to change the order of a
  67 sentence, and more generally it is easier for the translator to work with a
  68 single string for a sentence than with multiple string pieces.
  69
  70 <LI>
  71
  72 It reduces the risk of programming errors due to forgotten state in the
  73 output stream (e.g. <CODE>cout &#60;&#60; hex;</CODE> not followed by <CODE>cout &#60;&#60; dec;</CODE>).
  74 </UL>
  75
  76
  77
  78 <H1><A NAME="SEC2" HREF="autosprintf.html#TOC2">2  The <CODE>autosprintf</CODE> class</A></H1>
  79
  80 <P>
  81 An instance of class <CODE>autosprintf</CODE> just contains a string with the
  82 formatted output result. Such an instance is usually allocated as an
  83 automatic storage variable, i.e. on the stack, not with <CODE>new</CODE> on the
  84 heap.
  85
  86 </P>
  87 <P>
  88 The constructor <CODE>autosprintf (const char *format, ...)</CODE> takes a format
  89 string and additional arguments, like the C function <CODE>printf</CODE>.
  90
  91 </P>
  92 <P>
  93 Conversions to <CODE>char *</CODE> and <CODE>std::string</CODE> are defined that return
  94 the encapsulated string.
  95
  96 </P>
  97 <P>
  98 The destructor <CODE>~autosprintf ()</CODE> destroys the encapsulated string.
  99
 100 </P>
 101 <P>
 102 An <CODE>operator &#60;&#60;</CODE> is provided that outputs the encapsulated string to the
 103 given <CODE>ostream</CODE>.
 104
 105 </P>
 106
 107
 108 <H1><A NAME="SEC3" HREF="autosprintf.html#TOC3">3  Using <CODE>autosprintf</CODE> in own programs</A></H1>
 109
 110 <P>
 111 To use the <CODE>autosprintf</CODE> class in your programs, you need to add
 112
 113 </P>
 114
 115 <PRE>
 116 #include "autosprintf.h"
 117 using gnu::autosprintf;
 118 </PRE>
 119
 120 <P>
 121 to your source code.
 122 The include file defines the class <CODE>autosprintf</CODE>, in a namespace called
 123 <CODE>gnu</CODE>. The <SAMP>`using&acute;</SAMP> statement makes it possible to use the class
 124 without the (otherwise natural) <CODE>gnu::</CODE> prefix.
 125
 126 </P>
 127 <P>
 128 When linking your program, you need to link with <CODE>libasprintf</CODE>, because
 129 that's where the class is defined. In projects using GNU <CODE>autoconf</CODE>,
 130 this means adding <SAMP>`AC_LIB_LINKFLAGS([asprintf])&acute;</SAMP> to <CODE>configure.in</CODE>
 131 or <CODE>configure.ac</CODE>, and using the @LIBASPRINTF@ Makefile variable that
 132 it provides.
 133
 134 </P>
 135 <P><HR><P>
 136 This document was generated on 18 January 2004 using the
 137 <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>
 138 translator version 1.52a.</P>
 139 </BODY>
 140 </HTML>