mingw/share/doc/libasprintf/autosprintf_all.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52b
   4      from autosprintf.texi on 1 September 2007 -->
   5
   6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
   7 <TITLE>GNU autosprintf</TITLE>
   8 </HEAD>
   9 <BODY>
  10 <H1>GNU autosprintf, version 1.0</H1>
  11 <H2>Formatted Output to Strings in C++</H2>
  12 <ADDRESS>Bruno Haible</ADDRESS>
  13 <P>
  14 <P><HR><P>
  15 <H1>Table of Contents</H1>
  16 <UL>
  17 <LI><A NAME="TOC1" HREF="autosprintf.html#SEC1">1  Introduction</A>
  18 <LI><A NAME="TOC2" HREF="autosprintf.html#SEC2">2  The <CODE>autosprintf</CODE> class</A>
  19 <LI><A NAME="TOC3" HREF="autosprintf.html#SEC3">3  Using <CODE>autosprintf</CODE> in own programs</A>
  20 </UL>
  21 <P><HR><P>
  22
  23 <P>
  24 Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc.
  25
  26 </P>
  27 <P>
  28 This manual is free documentation.  It is dually licensed under the
  29 GNU FDL and the GNU GPL.  This means that you can redistribute this
  30 manual under either of these two licenses, at your choice.
  31
  32 </P>
  33 <P>
  34 This manual is covered by the GNU FDL.  Permission is granted to copy,
  35 distribute and/or modify this document under the terms of the
  36 GNU Free Documentation License (FDL), either version 1.2 of the
  37 License, or (at your option) any later version published by the
  38 Free Software Foundation (FSF); with no Invariant Sections, with no
  39 Front-Cover Text, and with no Back-Cover Texts.
  40 A copy of the license is at <A HREF="http://www.gnu.org/licenses/fdl.html">http://www.gnu.org/licenses/fdl.html</A>.
  41
  42 </P>
  43 <P>
  44 This manual is covered by the GNU GPL.  You can redistribute it and/or
  45 modify it under the terms of the GNU General Public License (GPL), either
  46 version 2 of the License, or (at your option) any later version published
  47 by the Free Software Foundation (FSF).
  48 A copy of the license is at <A HREF="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</A>.
  49
  50 </P>
  51
  52
  53
  54 <H1><A NAME="SEC1" HREF="autosprintf.html#TOC1">1  Introduction</A></H1>
  55
  56 <P>
  57 This package makes the C formatted output routines (<CODE>fprintf</CODE> et al.)
  58 usable in C++ programs, for use with the <CODE>&#60;string&#62;</CODE> strings and the
  59 <CODE>&#60;iostream&#62;</CODE> streams.
  60
  61 </P>
  62 <P>
  63 It allows to write code like
  64
  65 </P>
  66
  67 <PRE>
  68 cerr &#60;&#60; autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
  69 </PRE>
  70
  71 <P>
  72 instead of
  73
  74 </P>
  75
  76 <PRE>
  77 cerr &#60;&#60; "syntax error in " &#60;&#60; filename &#60;&#60; ":" &#60;&#60; line &#60;&#60; ": " &#60;&#60; errstring;
  78 </PRE>
  79
  80 <P>
  81 The benefits of the autosprintf syntax are:
  82
  83 </P>
  84
  85 <UL>
  86 <LI>
  87
  88 It reuses the standard POSIX printf facility. Easy migration from C to C++.
  89
  90 <LI>
  91
  92 English sentences are kept together.
  93
  94 <LI>
  95
  96 It makes internationalization possible. Internationalization requires format
  97 strings, because in some cases the translator needs to change the order of a
  98 sentence, and more generally it is easier for the translator to work with a
  99 single string for a sentence than with multiple string pieces.
 100
 101 <LI>
 102
 103 It reduces the risk of programming errors due to forgotten state in the
 104 output stream (e.g. <CODE>cout &#60;&#60; hex;</CODE> not followed by <CODE>cout &#60;&#60; dec;</CODE>).
 105 </UL>
 106
 107
 108
 109 <H1><A NAME="SEC2" HREF="autosprintf.html#TOC2">2  The <CODE>autosprintf</CODE> class</A></H1>
 110
 111 <P>
 112 An instance of class <CODE>autosprintf</CODE> just contains a string with the
 113 formatted output result. Such an instance is usually allocated as an
 114 automatic storage variable, i.e. on the stack, not with <CODE>new</CODE> on the
 115 heap.
 116
 117 </P>
 118 <P>
 119 The constructor <CODE>autosprintf (const char *format, ...)</CODE> takes a format
 120 string and additional arguments, like the C function <CODE>printf</CODE>.
 121
 122 </P>
 123 <P>
 124 Conversions to <CODE>char *</CODE> and <CODE>std::string</CODE> are defined that return
 125 the encapsulated string.  The conversion to <CODE>char *</CODE> returns a freshly
 126 allocated copy of the encapsulated string; it needs to be freed using
 127 <CODE>delete[]</CODE>.  The conversion to <CODE>std::string</CODE> returns a copy of
 128 the encapsulated string, with automatic memory management.
 129
 130 </P>
 131 <P>
 132 The destructor <CODE>~autosprintf ()</CODE> destroys the encapsulated string.
 133
 134 </P>
 135 <P>
 136 An <CODE>operator &#60;&#60;</CODE> is provided that outputs the encapsulated string to the
 137 given <CODE>ostream</CODE>.
 138
 139 </P>
 140
 141
 142 <H1><A NAME="SEC3" HREF="autosprintf.html#TOC3">3  Using <CODE>autosprintf</CODE> in own programs</A></H1>
 143
 144 <P>
 145 To use the <CODE>autosprintf</CODE> class in your programs, you need to add
 146
 147 </P>
 148
 149 <PRE>
 150 #include "autosprintf.h"
 151 using gnu::autosprintf;
 152 </PRE>
 153
 154 <P>
 155 to your source code.
 156 The include file defines the class <CODE>autosprintf</CODE>, in a namespace called
 157 <CODE>gnu</CODE>. The <SAMP>&lsquo;using&rsquo;</SAMP> statement makes it possible to use the class
 158 without the (otherwise natural) <CODE>gnu::</CODE> prefix.
 159
 160 </P>
 161 <P>
 162 When linking your program, you need to link with <CODE>libasprintf</CODE>, because
 163 that's where the class is defined. In projects using GNU <CODE>autoconf</CODE>,
 164 this means adding <SAMP>&lsquo;AC_LIB_LINKFLAGS([asprintf])&rsquo;</SAMP> to <CODE>configure.in</CODE>
 165 or <CODE>configure.ac</CODE>, and using the @LIBASPRINTF@ Makefile variable that
 166 it provides.
 167
 168 </P>
 169 <P><HR><P>
 170 This document was generated on 1 September 2007 using the
 171 <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>
 172 translator version 1.52b.</P>
 173 </BODY>
 174 </HTML>