nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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 @c %**end of header
23 @set VERSION 1.0
24  
25 @ifinfo
26 @dircategory C++ libraries
27 @direntry
28 * autosprintf: (autosprintf). Support for printf format strings in C++.
29 @end direntry
30 @end ifinfo
31  
32 @ifinfo
33 This file provides documentation for GNU @code{autosprintf} library.
34  
35 @copying
36 Copyright (C) 2002-2003, 2006-2007, 2015-2016 Free Software Foundation, Inc.
37  
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.
41  
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}.
49  
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}.
55 @end copying
56 @end ifinfo
57  
58 @titlepage
59 @title GNU autosprintf, version @value{VERSION}
60 @subtitle Formatted Output to Strings in C++
61 @author Bruno Haible
62  
63 @page
64 @vskip 0pt plus 1filll
65 @c @insertcopying
66 Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc.
67  
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.
71  
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}.
79  
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}.
85 @end titlepage
86  
87 @ifset makeinfo
88 @node Top, Introduction, (dir), (dir)
89 @top GNU autosprintf
90  
91 This manual documents the GNU autosprintf class, version @value{VERSION}.
92  
93 @menu
94 * Introduction:: Introduction
95 * Class autosprintf:: The @code{autosprintf} class
96 * Using autosprintf:: Using @code{autosprintf} in own programs
97 @end menu
98  
99 @end ifset
100  
101 @node Introduction, Class autosprintf, Top, Top
102 @chapter Introduction
103  
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.
107  
108 It allows to write code like
109  
110 @smallexample
111 cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
112 @end smallexample
113  
114 @noindent
115 instead of
116  
117 @smallexample
118 cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
119 @end smallexample
120  
121 The benefits of the autosprintf syntax are:
122  
123 @itemize @bullet
124 @item
125 It reuses the standard POSIX printf facility. Easy migration from C to C++.
126  
127 @item
128 English sentences are kept together.
129  
130 @item
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.
135  
136 @item
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;}).
139 @end itemize
140  
141 @node Class autosprintf, Using autosprintf, Introduction, Top
142 @chapter The @code{autosprintf} class
143  
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
147 heap.
148  
149 The constructor @code{autosprintf (const char *format, ...)} takes a format
150 string and additional arguments, like the C function @code{printf}.
151  
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.
157  
158 The destructor @code{~autosprintf ()} destroys the encapsulated string.
159  
160 An @code{operator <<} is provided that outputs the encapsulated string to the
161 given @code{ostream}.
162  
163 @node Using autosprintf, , Class autosprintf, Top
164 @chapter Using @code{autosprintf} in own programs
165  
166 To use the @code{autosprintf} class in your programs, you need to add
167  
168 @smallexample
169 #include "autosprintf.h"
170 using gnu::autosprintf;
171 @end smallexample
172  
173 @noindent
174 to your source code.
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.
178  
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
183 it provides.
184  
185 @bye
186  
187 @c Local variables:
188 @c texinfo-column-for-description: 32
189 @c End: