\input texinfo          @c -*-texinfo-*-
@c %**start of header
@setfilename autosprintf.info
@settitle GNU @code{autosprintf}
@finalout
@c Indices:
@c   none
@c Unused predefined indices:
@c   cp = concept         @cindex
@c   fn = function        @findex
@c   vr = variable        @vindex
@c   ky = keystroke       @kindex
@c   pg = program         @pindex
@c   tp = type            @tindex
@c %**end of header
@set VERSION 1.0

@dircategory C++ libraries
@direntry
* autosprintf: (autosprintf).   Support for printf format strings in C++.
@end direntry

@ifinfo
This file provides documentation for GNU @code{autosprintf} library.

Copyright (C) 2002 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@titlepage
@title GNU autosprintf, version @value{VERSION}
@subtitle Formatted Output to Strings in C++
@author Bruno Haible

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2002 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU autosprintf

This manual documents the GNU autosprintf class, version @value{VERSION}.

@menu
* Introduction::                Introduction
* Class autosprintf::           The @code{autosprintf} class
* Using autosprintf::           Using @code{autosprintf} in own programs
@end menu

@end ifinfo

@node Introduction, Class autosprintf, Top, Top
@chapter Introduction

This package makes the C formatted output routines (@code{fprintf} et al.)
usable in C++ programs, for use with the @code{<string>} strings and the
@code{<iostream>} streams.

It allows to write code like

@smallexample
cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
@end smallexample

@noindent
instead of

@smallexample
cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
@end smallexample

The benefits of the autosprintf syntax are:

@itemize @bullet
@item
It reuses the standard POSIX printf facility. Easy migration from C to C++.

@item
English sentences are kept together.

@item
It makes internationalization possible. Internationalization requires format
strings, because in some cases the translator needs to change the order of a
sentence, and more generally it is easier for the translator to work with a
single string for a sentence than with multiple string pieces.

@item
It reduces the risk of programming errors due to forgotten state in the
output stream (e.g. @code{cout << hex;} not followed by @code{cout << dec;}).
@end itemize

@node Class autosprintf, Using autosprintf, Introduction, Top
@chapter The @code{autosprintf} class

An instance of class @code{autosprintf} just contains a string with the
formatted output result. Such an instance is usually allocated as an
automatic storage variable, i.e. on the stack, not with @code{new} on the
heap.

The constructor @code{autosprintf (const char *format, ...)} takes a format
string and additional arguments, like the C function @code{printf}.

Conversions to @code{char *} and @code{std::string} are defined that return
the encapsulated string.

The destructor @code{~autosprintf ()} destroys the encapsulated string.

An @code{operator <<} is provided that outputs the encapsulated string to the
given @code{ostream}.

@node Using autosprintf,  , Class autosprintf, Top
@chapter Using @code{autosprintf} in own programs

To use the @code{autosprintf} class in your programs, you need to add

@smallexample
#include "autosprintf.h"
using gnu::autosprintf;
@end smallexample

@noindent
to your source code.
The include file defines the class @code{autosprintf}, in a namespace called
@code{gnu}. The @samp{using} statement makes it possible to use the class
without the (otherwise natural) @code{gnu::} prefix.

When linking your program, you need to link with @code{libasprintf}, because
that's where the class is defined. In projects using GNU @code{autoconf},
this means adding @samp{AC_LIB_LINKFLAGS([asprintf])} to @code{configure.in}
or @code{configure.ac}, and using the @@LIBASPRINTF@@ Makefile variable that
it provides.

@bye

@c Local variables:
@c texinfo-column-for-description: 32
@c End: