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