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 33This file provides documentation for GNU @code{autosprintf} library. 34 35@copying 36Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc. 37 38This manual is free documentation. It is dually licensed under the 39GNU FDL and the GNU GPL. This means that you can redistribute this 40manual under either of these two licenses, at your choice. 41 42This manual is covered by the GNU FDL. Permission is granted to copy, 43distribute and/or modify this document under the terms of the 44GNU Free Documentation License (FDL), either version 1.2 of the 45License, or (at your option) any later version published by the 46Free Software Foundation (FSF); with no Invariant Sections, with no 47Front-Cover Text, and with no Back-Cover Texts. 48A copy of the license is at @url{http://www.gnu.org/licenses/fdl.html}. 49 50This manual is covered by the GNU GPL. You can redistribute it and/or 51modify it under the terms of the GNU General Public License (GPL), either 52version 2 of the License, or (at your option) any later version published 53by the Free Software Foundation (FSF). 54A 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 66Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc. 67 68This manual is free documentation. It is dually licensed under the 69GNU FDL and the GNU GPL. This means that you can redistribute this 70manual under either of these two licenses, at your choice. 71 72This manual is covered by the GNU FDL. Permission is granted to copy, 73distribute and/or modify this document under the terms of the 74GNU Free Documentation License (FDL), either version 1.2 of the 75License, or (at your option) any later version published by the 76Free Software Foundation (FSF); with no Invariant Sections, with no 77Front-Cover Text, and with no Back-Cover Texts. 78A copy of the license is at @url{http://www.gnu.org/licenses/fdl.html}. 79 80This manual is covered by the GNU GPL. You can redistribute it and/or 81modify it under the terms of the GNU General Public License (GPL), either 82version 2 of the License, or (at your option) any later version published 83by the Free Software Foundation (FSF). 84A 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 91This 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 104This package makes the C formatted output routines (@code{fprintf} et al.) 105usable in C++ programs, for use with the @code{<string>} strings and the 106@code{<iostream>} streams. 107 108It allows to write code like 109 110@smallexample 111cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring); 112@end smallexample 113 114@noindent 115instead of 116 117@smallexample 118cerr << "syntax error in " << filename << ":" << line << ": " << errstring; 119@end smallexample 120 121The benefits of the autosprintf syntax are: 122 123@itemize @bullet 124@item 125It reuses the standard POSIX printf facility. Easy migration from C to C++. 126 127@item 128English sentences are kept together. 129 130@item 131It makes internationalization possible. Internationalization requires format 132strings, because in some cases the translator needs to change the order of a 133sentence, and more generally it is easier for the translator to work with a 134single string for a sentence than with multiple string pieces. 135 136@item 137It reduces the risk of programming errors due to forgotten state in the 138output 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 144An instance of class @code{autosprintf} just contains a string with the 145formatted output result. Such an instance is usually allocated as an 146automatic storage variable, i.e.@: on the stack, not with @code{new} on the 147heap. 148 149The constructor @code{autosprintf (const char *format, ...)} takes a format 150string and additional arguments, like the C function @code{printf}. 151 152Conversions to @code{char *} and @code{std::string} are defined that return 153the encapsulated string. The conversion to @code{char *} returns a freshly 154allocated copy of the encapsulated string; it needs to be freed using 155@code{delete[]}. The conversion to @code{std::string} returns a copy of 156the encapsulated string, with automatic memory management. 157 158The destructor @code{~autosprintf ()} destroys the encapsulated string. 159 160An @code{operator <<} is provided that outputs the encapsulated string to the 161given @code{ostream}. 162 163@node Using autosprintf, , Class autosprintf, Top 164@chapter Using @code{autosprintf} in own programs 165 166To use the @code{autosprintf} class in your programs, you need to add 167 168@smallexample 169#include "autosprintf.h" 170using gnu::autosprintf; 171@end smallexample 172 173@noindent 174to your source code. 175The 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 177without the (otherwise natural) @code{gnu::} prefix. 178 179When linking your program, you need to link with @code{libasprintf}, because 180that's where the class is defined. In projects using GNU @code{autoconf}, 181this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in} 182or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that 183it provides. 184 185@bye 186 187@c Local variables: 188@c texinfo-column-for-description: 32 189@c End: 190