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