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@ifclear texi2html 23@firstparagraphindent insert 24@end ifclear 25@c %**end of header 26@set VERSION 1.0 27 28@ifinfo 29@dircategory C++ libraries 30@direntry 31* autosprintf: (autosprintf). Support for printf format strings in C++. 32@end direntry 33@end ifinfo 34 35@ifinfo 36This file provides documentation for GNU @code{autosprintf} library. 37 38@copying 39Copyright (C) 2002-2003, 2006-2007, 2018-2019 Free Software Foundation, Inc. 40 41This manual is free documentation. It is dually licensed under the 42GNU FDL and the GNU GPL. This means that you can redistribute this 43manual under either of these two licenses, at your choice. 44 45This manual is covered by the GNU FDL. Permission is granted to copy, 46distribute and/or modify this document under the terms of the 47GNU Free Documentation License (FDL), either version 1.2 of the 48License, or (at your option) any later version published by the 49Free Software Foundation (FSF); with no Invariant Sections, with no 50Front-Cover Text, and with no Back-Cover Texts. 51A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. 52 53This manual is covered by the GNU GPL. You can redistribute it and/or 54modify it under the terms of the GNU General Public License (GPL), either 55version 2 of the License, or (at your option) any later version published 56by the Free Software Foundation (FSF). 57A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. 58@end copying 59@end ifinfo 60 61@titlepage 62@title GNU autosprintf, version @value{VERSION} 63@subtitle Formatted Output to Strings in C++ 64@author Bruno Haible 65 66@ifnothtml 67@page 68@vskip 0pt plus 1filll 69@c @insertcopying 70Copyright (C) 2002-2003, 2006-2007, 2018-2019 Free Software Foundation, Inc. 71 72This manual is free documentation. It is dually licensed under the 73GNU FDL and the GNU GPL. This means that you can redistribute this 74manual under either of these two licenses, at your choice. 75 76This manual is covered by the GNU FDL. Permission is granted to copy, 77distribute and/or modify this document under the terms of the 78GNU Free Documentation License (FDL), either version 1.2 of the 79License, or (at your option) any later version published by the 80Free Software Foundation (FSF); with no Invariant Sections, with no 81Front-Cover Text, and with no Back-Cover Texts. 82A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. 83 84This manual is covered by the GNU GPL. You can redistribute it and/or 85modify it under the terms of the GNU General Public License (GPL), either 86version 2 of the License, or (at your option) any later version published 87by the Free Software Foundation (FSF). 88A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. 89@end ifnothtml 90@end titlepage 91 92@c Table of Contents 93@contents 94 95@ifnottex 96@node Top 97@top GNU autosprintf 98 99This manual documents the GNU autosprintf class, version @value{VERSION}. 100 101@menu 102* Introduction:: Introduction 103* Class autosprintf:: The @code{autosprintf} class 104* Using autosprintf:: Using @code{autosprintf} in own programs 105* Licenses:: 106@end menu 107 108@end ifnottex 109 110@node Introduction 111@chapter Introduction 112 113This package makes the C formatted output routines (@code{fprintf} et al.) 114usable in C++ programs, for use with the @code{<string>} strings and the 115@code{<iostream>} streams. 116 117It allows to write code like 118 119@smallexample 120cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring); 121@end smallexample 122 123@noindent 124instead of 125 126@smallexample 127cerr << "syntax error in " << filename << ":" << line << ": " << errstring; 128@end smallexample 129 130The benefits of the autosprintf syntax are: 131 132@itemize @bullet 133@item 134It reuses the standard POSIX printf facility. Easy migration from C to C++. 135 136@item 137English sentences are kept together. 138 139@item 140It makes internationalization possible. Internationalization requires format 141strings, because in some cases the translator needs to change the order of a 142sentence, and more generally it is easier for the translator to work with a 143single string for a sentence than with multiple string pieces. 144 145@item 146It reduces the risk of programming errors due to forgotten state in the 147output stream (e.g.@: @code{cout << hex;} not followed by @code{cout << dec;}). 148@end itemize 149 150@node Class autosprintf 151@chapter The @code{autosprintf} class 152 153An instance of class @code{autosprintf} just contains a string with the 154formatted output result. Such an instance is usually allocated as an 155automatic storage variable, i.e.@: on the stack, not with @code{new} on the 156heap. 157 158The constructor @code{autosprintf (const char *format, ...)} takes a format 159string and additional arguments, like the C function @code{printf}. 160 161Conversions to @code{char *} and @code{std::string} are defined that return 162the encapsulated string. The conversion to @code{char *} returns a freshly 163allocated copy of the encapsulated string; it needs to be freed using 164@code{delete[]}. The conversion to @code{std::string} returns a copy of 165the encapsulated string, with automatic memory management. 166 167The destructor @code{~autosprintf ()} destroys the encapsulated string. 168 169An @code{operator <<} is provided that outputs the encapsulated string to the 170given @code{ostream}. 171 172@node Using autosprintf 173@chapter Using @code{autosprintf} in own programs 174 175To use the @code{autosprintf} class in your programs, you need to add 176 177@smallexample 178#include "autosprintf.h" 179using gnu::autosprintf; 180@end smallexample 181 182@noindent 183to your source code. 184The include file defines the class @code{autosprintf}, in a namespace called 185@code{gnu}. The @samp{using} statement makes it possible to use the class 186without the (otherwise natural) @code{gnu::} prefix. 187 188When linking your program, you need to link with @code{libasprintf}, because 189that's where the class is defined. In projects using GNU @code{autoconf}, 190this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in} 191or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that 192it provides. 193 194@node Licenses 195@appendix Licenses 196@cindex Licenses 197 198The files of this package are covered by the licenses indicated in each 199particular file or directory. Here is a summary: 200 201@itemize @bullet 202@item 203The @code{libasprintf} library is covered by the 204GNU Lesser General Public License (LGPL), either version 2.1 of the 205License, or (at your option) any later version published by the 206Free Software Foundation (FSF). 207A copy of the license is included in @ref{GNU LGPL}. 208 209@item 210This manual is free documentation. It is dually licensed under the 211GNU FDL and the GNU GPL. This means that you can redistribute this 212manual under either of these two licenses, at your choice. 213@* 214This manual is covered by the GNU FDL. Permission is granted to copy, 215distribute and/or modify this document under the terms of the 216GNU Free Documentation License (FDL), either version 1.2 of the 217License, or (at your option) any later version published by the 218Free Software Foundation (FSF); with no Invariant Sections, with no 219Front-Cover Text, and with no Back-Cover Texts. 220A copy of the license is included in @ref{GNU FDL}. 221@* 222This manual is covered by the GNU GPL. You can redistribute it and/or 223modify it under the terms of the GNU General Public License (GPL), either 224version 2 of the License, or (at your option) any later version published 225by the Free Software Foundation (FSF). 226A copy of the license is included in @ref{GNU GPL}. 227@end itemize 228 229@menu 230* GNU LGPL:: GNU Lesser General Public License 231* GNU GPL:: GNU General Public License 232* GNU FDL:: GNU Free Documentation License 233@end menu 234 235@page 236@node GNU LGPL 237@appendixsec GNU LESSER GENERAL PUBLIC LICENSE 238@cindex :GPL, GNU Lesser General Public License 239@cindex License, GNU LGPL 240@include lgpl.texi 241@page 242@node GNU GPL 243@appendixsec GNU GENERAL PUBLIC LICENSE 244@cindex GPL, GNU General Public License 245@cindex License, GNU GPL 246@include gpl.texi 247@page 248@node GNU FDL 249@appendixsec GNU Free Documentation License 250@cindex FDL, GNU Free Documentation License 251@cindex License, GNU FDL 252@include fdl.texi 253 254@bye 255 256@c Local variables: 257@c texinfo-column-for-description: 32 258@c End: 259