README
1 GNU libasprintf - automatic formatted output to strings
2
3This package makes the C formatted output routines (fprintf et al.) usable
4in C++ programs.
5
6
7Sample use
8----------
9
10 char *pathname = autosprintf ("%s/%s", directory, filename);
11 cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
12
13
14Benefits
15--------
16
17The benefits of autosprintf over the usual "piecewise meal" idiom
18
19 cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
20
21are:
22
23 - Reuses of the standard POSIX printf facility. Easy migration from C to C++.
24
25 - English sentences are kept together.
26
27 - Internationalization requires format strings, because
28 1. Internationalization requires the ability for the translator to change
29 the order of parts of a sentence. The POSIX printf formatted output
30 functions (and thus also autosprintf) support this through the %m$ and
31 *m$ syntax.
32 2. Translators are used to translate one string per sentence, not
33 multiple strings per sentence, and not C++ code statements.
34
35 - Reduces the risk of programming errors due to forgotten state in the
36 output stream (e.g. 'cout << hex;' not followed by 'cout << dec;').
37
38The benefits of autosprintf over C sprintf are:
39
40 - Autosprintf avoids buffer overruns and truncated results.
41 The C sprintf() function often leads to buffer overruns. On the other
42 hand, the C snprintf() function requires extra coding for an a priori
43 estimate of the result's size and truncates the result if the estimate
44 was too low.
45
46 - Autosprintf avoids memory leaks.
47 Temporarily allocated memory is cleaned up automatically.
48
49
50Installation
51------------
52
53See INSTALL. Usually "./configure; make; make install" should work.
54
55The installed files are:
56 - An include file "autosprintf.h" which defines the class 'autosprintf',
57 in the namespace 'gnu'.
58 - A library libasprintf containing this class.
59
60
61Use
62---
63
64To use the class autosprintf, use
65
66 #include "autosprintf.h"
67 using gnu::autosprintf;
68
69and link with the linker option
70
71 -lasprintf
72
73
74Misc notes
75----------
76
77An instance of class 'autosprintf' contains the formatted output result;
78this string is freed when the instance's destructor is run.
79
80The class name 'autosprintf' is meant to remind the C function sprintf(),
81the GNU C library function asprintf(), and the C++ autoptr programming idiom.
82
83
84Distribution
85------------
86
87 https://haible.de/bruno/gnu/libasprintf-1.0.tar.gz
88
89Homepage
90--------
91
92 https://haible.de/bruno/packages-libasprintf.html
93
94Bug reports
95-----------
96
97Report bugs
98 - in the bug tracker at <https://savannah.gnu.org/projects/gettext>
99 - or by email to <bug-gettext@gnu.org>.
100
101
102Bruno Haible <brunoe@clisp.org>
103