1 \input texinfo @c -*-texinfo-*-
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.
11 @settitle GNU @code{autosprintf}
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
26 @dircategory C++ libraries
28 * autosprintf: (autosprintf). Support for printf format strings in C++.
33 This file provides documentation for GNU @code{autosprintf} library.
36 Copyright (C) 2002-2003, 2006-2007, 2015 Free Software Foundation, Inc.
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.
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}.
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}.
59 @title GNU autosprintf, version @value{VERSION}
60 @subtitle Formatted Output to Strings in C++
64 @vskip 0pt plus 1filll
66 Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc.
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.
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}.
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}.
88 @node Top, Introduction, (dir), (dir)
91 This manual documents the GNU autosprintf class, version @value{VERSION}.
94 * Introduction:: Introduction
95 * Class autosprintf:: The @code{autosprintf} class
96 * Using autosprintf:: Using @code{autosprintf} in own programs
101 @node Introduction, Class autosprintf, Top, Top
102 @chapter Introduction
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.
108 It allows to write code like
111 cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
118 cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
121 The benefits of the autosprintf syntax are:
125 It reuses the standard POSIX printf facility. Easy migration from C to C++.
128 English sentences are kept together.
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.
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;}).
141 @node Class autosprintf, Using autosprintf, Introduction, Top
142 @chapter The @code{autosprintf} class
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
149 The constructor @code{autosprintf (const char *format, ...)} takes a format
150 string and additional arguments, like the C function @code{printf}.
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.
158 The destructor @code{~autosprintf ()} destroys the encapsulated string.
160 An @code{operator <<} is provided that outputs the encapsulated string to the
161 given @code{ostream}.
163 @node Using autosprintf, , Class autosprintf, Top
164 @chapter Using @code{autosprintf} in own programs
166 To use the @code{autosprintf} class in your programs, you need to add
169 #include "autosprintf.h"
170 using gnu::autosprintf;
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.
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
188 @c texinfo-column-for-description: 32