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