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 24This file provides documentation for GNU @code{autosprintf} library. 25 26Copyright (C) 2002 Free Software Foundation, Inc. 27 28Permission is granted to make and distribute verbatim copies of 29this manual provided the copyright notice and this permission notice 30are preserved on all copies. 31 32@ignore 33Permission is granted to process this file through TeX and print the 34results, provided the printed document carries copying permission 35notice 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 39Permission is granted to copy and distribute modified versions of this 40manual under the conditions for verbatim copying, provided that the entire 41resulting derived work is distributed under the terms of a permission 42notice identical to this one. 43 44Permission is granted to copy and distribute translations of this manual 45into another language, under the above conditions for modified versions, 46except that this permission notice may be stated in a translation approved 47by 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 57Copyright @copyright{} 2002 Free Software Foundation, Inc. 58 59Permission is granted to make and distribute verbatim copies of 60this manual provided the copyright notice and this permission notice 61are preserved on all copies. 62 63Permission is granted to copy and distribute modified versions of this 64manual under the conditions for verbatim copying, provided that the entire 65resulting derived work is distributed under the terms of a permission 66notice identical to this one. 67 68Permission is granted to copy and distribute translations of this manual 69into another language, under the above conditions for modified versions, 70except that this permission notice may be stated in a translation approved 71by the Foundation. 72@end titlepage 73 74@ifinfo 75@node Top, Introduction, (dir), (dir) 76@top GNU autosprintf 77 78This 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 91This package makes the C formatted output routines (@code{fprintf} et al.) 92usable in C++ programs, for use with the @code{<string>} strings and the 93@code{<iostream>} streams. 94 95It allows to write code like 96 97@smallexample 98cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring); 99@end smallexample 100 101@noindent 102instead of 103 104@smallexample 105cerr << "syntax error in " << filename << ":" << line << ": " << errstring; 106@end smallexample 107 108The benefits of the autosprintf syntax are: 109 110@itemize @bullet 111@item 112It reuses the standard POSIX printf facility. Easy migration from C to C++. 113 114@item 115English sentences are kept together. 116 117@item 118It makes internationalization possible. Internationalization requires format 119strings, because in some cases the translator needs to change the order of a 120sentence, and more generally it is easier for the translator to work with a 121single string for a sentence than with multiple string pieces. 122 123@item 124It reduces the risk of programming errors due to forgotten state in the 125output 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 131An instance of class @code{autosprintf} just contains a string with the 132formatted output result. Such an instance is usually allocated as an 133automatic storage variable, i.e. on the stack, not with @code{new} on the 134heap. 135 136The constructor @code{autosprintf (const char *format, ...)} takes a format 137string and additional arguments, like the C function @code{printf}. 138 139Conversions to @code{char *} and @code{std::string} are defined that return 140the encapsulated string. 141 142The destructor @code{~autosprintf ()} destroys the encapsulated string. 143 144An @code{operator <<} is provided that outputs the encapsulated string to the 145given @code{ostream}. 146 147@node Using autosprintf, , Class autosprintf, Top 148@chapter Using @code{autosprintf} in own programs 149 150To use the @code{autosprintf} class in your programs, you need to add 151 152@smallexample 153#include "autosprintf.h" 154using gnu::autosprintf; 155@end smallexample 156 157@noindent 158to your source code. 159The 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 161without the (otherwise natural) @code{gnu::} prefix. 162 163When linking your program, you need to link with @code{libasprintf}, because 164that's where the class is defined. In projects using GNU @code{autoconf}, 165this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in} 166or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that 167it provides. 168 169@bye 170 171@c Local variables: 172@c texinfo-column-for-description: 32 173@c End: 174