| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename autosprintf.info |
| @c The @ifset makeinfo ... @end ifset conditional evaluates to true in makeinfo |
| @c for info and html output, but to false in texi2html. |
| @ifnottex |
| @ifclear texi2html |
| @set makeinfo |
| @end ifclear |
| @end ifnottex |
| @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 |
| @ifclear texi2html |
| @firstparagraphindent insert |
| @end ifclear |
| @c %**end of header |
| @set VERSION 1.0 |
| |
| @ifinfo |
| @dircategory C++ libraries |
| @direntry |
| * autosprintf: (autosprintf). Support for printf format strings in C++. |
| @end direntry |
| @end ifinfo |
| |
| @ifinfo |
| This file provides documentation for GNU @code{autosprintf} library. |
| |
| @copying |
| Copyright (C) 2002-2003, 2006-2007, 2018-2019 Free Software Foundation, Inc. |
| |
| This manual is free documentation. It is dually licensed under the |
| GNU FDL and the GNU GPL. This means that you can redistribute this |
| manual under either of these two licenses, at your choice. |
| |
| This manual is covered by the GNU FDL. Permission is granted to copy, |
| distribute and/or modify this document under the terms of the |
| GNU Free Documentation License (FDL), either version 1.2 of the |
| License, or (at your option) any later version published by the |
| Free Software Foundation (FSF); with no Invariant Sections, with no |
| Front-Cover Text, and with no Back-Cover Texts. |
| A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. |
| |
| This manual is covered by the GNU GPL. You can redistribute it and/or |
| modify it under the terms of the GNU General Public License (GPL), either |
| version 2 of the License, or (at your option) any later version published |
| by the Free Software Foundation (FSF). |
| A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. |
| @end copying |
| @end ifinfo |
| |
| @titlepage |
| @title GNU autosprintf, version @value{VERSION} |
| @subtitle Formatted Output to Strings in C++ |
| @author Bruno Haible |
| |
| @ifnothtml |
| @page |
| @vskip 0pt plus 1filll |
| @c @insertcopying |
| Copyright (C) 2002-2003, 2006-2007, 2018-2019 Free Software Foundation, Inc. |
| |
| This manual is free documentation. It is dually licensed under the |
| GNU FDL and the GNU GPL. This means that you can redistribute this |
| manual under either of these two licenses, at your choice. |
| |
| This manual is covered by the GNU FDL. Permission is granted to copy, |
| distribute and/or modify this document under the terms of the |
| GNU Free Documentation License (FDL), either version 1.2 of the |
| License, or (at your option) any later version published by the |
| Free Software Foundation (FSF); with no Invariant Sections, with no |
| Front-Cover Text, and with no Back-Cover Texts. |
| A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. |
| |
| This manual is covered by the GNU GPL. You can redistribute it and/or |
| modify it under the terms of the GNU General Public License (GPL), either |
| version 2 of the License, or (at your option) any later version published |
| by the Free Software Foundation (FSF). |
| A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. |
| @end ifnothtml |
| @end titlepage |
| |
| @c Table of Contents |
| @contents |
| |
| @ifnottex |
| @node Top |
| @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 |
| * Licenses:: |
| @end menu |
| |
| @end ifnottex |
| |
| @node Introduction |
| @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 |
| @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 conversion to @code{char *} returns a freshly |
| allocated copy of the encapsulated string; it needs to be freed using |
| @code{delete[]}. The conversion to @code{std::string} returns a copy of |
| the encapsulated string, with automatic memory management. |
| |
| 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 |
| @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. |
| |
| @node Licenses |
| @appendix Licenses |
| @cindex Licenses |
| |
| The files of this package are covered by the licenses indicated in each |
| particular file or directory. Here is a summary: |
| |
| @itemize @bullet |
| @item |
| The @code{libasprintf} library is covered by the |
| GNU Lesser General Public License (LGPL), either version 2.1 of the |
| License, or (at your option) any later version published by the |
| Free Software Foundation (FSF). |
| A copy of the license is included in @ref{GNU LGPL}. |
| |
| @item |
| This manual is free documentation. It is dually licensed under the |
| GNU FDL and the GNU GPL. This means that you can redistribute this |
| manual under either of these two licenses, at your choice. |
| @* |
| This manual is covered by the GNU FDL. Permission is granted to copy, |
| distribute and/or modify this document under the terms of the |
| GNU Free Documentation License (FDL), either version 1.2 of the |
| License, or (at your option) any later version published by the |
| Free Software Foundation (FSF); with no Invariant Sections, with no |
| Front-Cover Text, and with no Back-Cover Texts. |
| A copy of the license is included in @ref{GNU FDL}. |
| @* |
| This manual is covered by the GNU GPL. You can redistribute it and/or |
| modify it under the terms of the GNU General Public License (GPL), either |
| version 2 of the License, or (at your option) any later version published |
| by the Free Software Foundation (FSF). |
| A copy of the license is included in @ref{GNU GPL}. |
| @end itemize |
| |
| @menu |
| * GNU LGPL:: GNU Lesser General Public License |
| * GNU GPL:: GNU General Public License |
| * GNU FDL:: GNU Free Documentation License |
| @end menu |
| |
| @page |
| @node GNU LGPL |
| @appendixsec GNU LESSER GENERAL PUBLIC LICENSE |
| @cindex :GPL, GNU Lesser General Public License |
| @cindex License, GNU LGPL |
| @include lgpl.texi |
| @page |
| @node GNU GPL |
| @appendixsec GNU GENERAL PUBLIC LICENSE |
| @cindex GPL, GNU General Public License |
| @cindex License, GNU GPL |
| @include gpl.texi |
| @page |
| @node GNU FDL |
| @appendixsec GNU Free Documentation License |
| @cindex FDL, GNU Free Documentation License |
| @cindex License, GNU FDL |
| @include fdl.texi |
| |
| @bye |
| |
| @c Local variables: |
| @c texinfo-column-for-description: 32 |
| @c End: |