gettext-runtime/libasprintf/autosprintf.texi

   1 \input texinfo          @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename autosprintf.info
   4 @c The @ifset makeinfo ... @end ifset conditional evaluates to true in makeinfo
   5 @c for info and html output, but to false in texi2html.
   6 @ifnottex
   7 @ifclear texi2html
   8 @set makeinfo
   9 @end ifclear
  10 @end ifnottex
  11 @settitle GNU @code{autosprintf}
  12 @finalout
  13 @c Indices:
  14 @c   none
  15 @c Unused predefined indices:
  16 @c   cp = concept         @cindex
  17 @c   fn = function        @findex
  18 @c   vr = variable        @vindex
  19 @c   ky = keystroke       @kindex
  20 @c   pg = program         @pindex
  21 @c   tp = type            @tindex
  22 @c %**end of header
  23 @set VERSION 1.0
  24
  25 @ifinfo
  26 @dircategory C++ libraries
  27 @direntry
  28 * autosprintf: (autosprintf).   Support for printf format strings in C++.
  29 @end direntry
  30 @end ifinfo
  31
  32 @ifinfo
  33 This file provides documentation for GNU @code{autosprintf} library.
  34
  35 @copying
  36 Copyright (C) 2002-2003, 2006-2007, 2015 Free Software Foundation, Inc.
  37
  38 This manual is free documentation.  It is dually licensed under the
  39 GNU FDL and the GNU GPL.  This means that you can redistribute this
  40 manual under either of these two licenses, at your choice.
  41
  42 This manual is covered by the GNU FDL.  Permission is granted to copy,
  43 distribute and/or modify this document under the terms of the
  44 GNU Free Documentation License (FDL), either version 1.2 of the
  45 License, or (at your option) any later version published by the
  46 Free Software Foundation (FSF); with no Invariant Sections, with no
  47 Front-Cover Text, and with no Back-Cover Texts.
  48 A copy of the license is at @url{http://www.gnu.org/licenses/fdl.html}.
  49
  50 This manual is covered by the GNU GPL.  You can redistribute it and/or
  51 modify it under the terms of the GNU General Public License (GPL), either
  52 version 2 of the License, or (at your option) any later version published
  53 by the Free Software Foundation (FSF).
  54 A copy of the license is at @url{http://www.gnu.org/licenses/gpl.html}.
  55 @end copying
  56 @end ifinfo
  57
  58 @titlepage
  59 @title GNU autosprintf, version @value{VERSION}
  60 @subtitle Formatted Output to Strings in C++
  61 @author Bruno Haible
  62
  63 @page
  64 @vskip 0pt plus 1filll
  65 @c @insertcopying
  66 Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc.
  67
  68 This manual is free documentation.  It is dually licensed under the
  69 GNU FDL and the GNU GPL.  This means that you can redistribute this
  70 manual under either of these two licenses, at your choice.
  71
  72 This manual is covered by the GNU FDL.  Permission is granted to copy,
  73 distribute and/or modify this document under the terms of the
  74 GNU Free Documentation License (FDL), either version 1.2 of the
  75 License, or (at your option) any later version published by the
  76 Free Software Foundation (FSF); with no Invariant Sections, with no
  77 Front-Cover Text, and with no Back-Cover Texts.
  78 A copy of the license is at @url{http://www.gnu.org/licenses/fdl.html}.
  79
  80 This manual is covered by the GNU GPL.  You can redistribute it and/or
  81 modify it under the terms of the GNU General Public License (GPL), either
  82 version 2 of the License, or (at your option) any later version published
  83 by the Free Software Foundation (FSF).
  84 A copy of the license is at @url{http://www.gnu.org/licenses/gpl.html}.
  85 @end titlepage
  86
  87 @ifset makeinfo
  88 @node Top, Introduction, (dir), (dir)
  89 @top GNU autosprintf
  90
  91 This manual documents the GNU autosprintf class, version @value{VERSION}.
  92
  93 @menu
  94 * Introduction::                Introduction
  95 * Class autosprintf::           The @code{autosprintf} class
  96 * Using autosprintf::           Using @code{autosprintf} in own programs
  97 @end menu
  98
  99 @end ifset
 100
 101 @node Introduction, Class autosprintf, Top, Top
 102 @chapter Introduction
 103
 104 This package makes the C formatted output routines (@code{fprintf} et al.)
 105 usable in C++ programs, for use with the @code{<string>} strings and the
 106 @code{<iostream>} streams.
 107
 108 It allows to write code like
 109
 110 @smallexample
 111 cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
 112 @end smallexample
 113
 114 @noindent
 115 instead of
 116
 117 @smallexample
 118 cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
 119 @end smallexample
 120
 121 The benefits of the autosprintf syntax are:
 122
 123 @itemize @bullet
 124 @item
 125 It reuses the standard POSIX printf facility. Easy migration from C to C++.
 126
 127 @item
 128 English sentences are kept together.
 129
 130 @item
 131 It makes internationalization possible. Internationalization requires format
 132 strings, because in some cases the translator needs to change the order of a
 133 sentence, and more generally it is easier for the translator to work with a
 134 single string for a sentence than with multiple string pieces.
 135
 136 @item
 137 It reduces the risk of programming errors due to forgotten state in the
 138 output stream (e.g.@: @code{cout << hex;} not followed by @code{cout << dec;}).
 139 @end itemize
 140
 141 @node Class autosprintf, Using autosprintf, Introduction, Top
 142 @chapter The @code{autosprintf} class
 143
 144 An instance of class @code{autosprintf} just contains a string with the
 145 formatted output result. Such an instance is usually allocated as an
 146 automatic storage variable, i.e.@: on the stack, not with @code{new} on the
 147 heap.
 148
 149 The constructor @code{autosprintf (const char *format, ...)} takes a format
 150 string and additional arguments, like the C function @code{printf}.
 151
 152 Conversions to @code{char *} and @code{std::string} are defined that return
 153 the encapsulated string.  The conversion to @code{char *} returns a freshly
 154 allocated copy of the encapsulated string; it needs to be freed using
 155 @code{delete[]}.  The conversion to @code{std::string} returns a copy of
 156 the encapsulated string, with automatic memory management.
 157
 158 The destructor @code{~autosprintf ()} destroys the encapsulated string.
 159
 160 An @code{operator <<} is provided that outputs the encapsulated string to the
 161 given @code{ostream}.
 162
 163 @node Using autosprintf,  , Class autosprintf, Top
 164 @chapter Using @code{autosprintf} in own programs
 165
 166 To use the @code{autosprintf} class in your programs, you need to add
 167
 168 @smallexample
 169 #include "autosprintf.h"
 170 using gnu::autosprintf;
 171 @end smallexample
 172
 173 @noindent
 174 to your source code.
 175 The include file defines the class @code{autosprintf}, in a namespace called
 176 @code{gnu}. The @samp{using} statement makes it possible to use the class
 177 without the (otherwise natural) @code{gnu::} prefix.
 178
 179 When linking your program, you need to link with @code{libasprintf}, because
 180 that's where the class is defined. In projects using GNU @code{autoconf},
 181 this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in}
 182 or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that
 183 it provides.
 184
 185 @bye
 186
 187 @c Local variables:
 188 @c texinfo-column-for-description: 32
 189 @c End: