gettext-runtime/libasprintf/autosprintf.info

   1 This is autosprintf.info, produced by makeinfo version 5.1 from
   2 autosprintf.texi.
   3
   4 Copyright (C) 2002-2003, 2006-2007 Free Software Foundation, Inc.
   5
   6    This manual is free documentation.  It is dually licensed under the
   7 GNU FDL and the GNU GPL. This means that you can redistribute this
   8 manual under either of these two licenses, at your choice.
   9
  10    This manual is covered by the GNU FDL. Permission is granted to copy,
  11 distribute and/or modify this document under the terms of the GNU Free
  12 Documentation License (FDL), either version 1.2 of the License, or (at
  13 your option) any later version published by the Free Software Foundation
  14 (FSF); with no Invariant Sections, with no Front-Cover Text, and with no
  15 Back-Cover Texts.  A copy of the license is at
  16 <http://www.gnu.org/licenses/fdl.html>.
  17
  18    This manual is covered by the GNU GPL. You can redistribute it and/or
  19 modify it under the terms of the GNU General Public License (GPL),
  20 either version 2 of the License, or (at your option) any later version
  21 published by the Free Software Foundation (FSF). A copy of the license
  22 is at <http://www.gnu.org/licenses/gpl.html>.
  23 INFO-DIR-SECTION C++ libraries
  24 START-INFO-DIR-ENTRY
  25 * autosprintf: (autosprintf).   Support for printf format strings in C++.
  26 END-INFO-DIR-ENTRY
  27
  28    This file provides documentation for GNU 'autosprintf' library.
  29
  30 \1f
  31 File: autosprintf.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  32
  33 GNU autosprintf
  34 ***************
  35
  36 This manual documents the GNU autosprintf class, version 1.0.
  37
  38 * Menu:
  39
  40 * Introduction::                Introduction
  41 * Class autosprintf::           The 'autosprintf' class
  42 * Using autosprintf::           Using 'autosprintf' in own programs
  43
  44 \1f
  45 File: autosprintf.info,  Node: Introduction,  Next: Class autosprintf,  Prev: Top,  Up: Top
  46
  47 1 Introduction
  48 **************
  49
  50 This package makes the C formatted output routines ('fprintf' et al.)
  51 usable in C++ programs, for use with the '<string>' strings and the
  52 '<iostream>' streams.
  53
  54    It allows to write code like
  55
  56      cerr << autosprintf ("syntax error in %s:%d: %s", filename, line, errstring);
  57
  58 instead of
  59
  60      cerr << "syntax error in " << filename << ":" << line << ": " << errstring;
  61
  62    The benefits of the autosprintf syntax are:
  63
  64    * It reuses the standard POSIX printf facility.  Easy migration from
  65      C to C++.
  66
  67    * English sentences are kept together.
  68
  69    * It makes internationalization possible.  Internationalization
  70      requires format strings, because in some cases the translator needs
  71      to change the order of a sentence, and more generally it is easier
  72      for the translator to work with a single string for a sentence than
  73      with multiple string pieces.
  74
  75    * It reduces the risk of programming errors due to forgotten state in
  76      the output stream (e.g. 'cout << hex;' not followed by 'cout <<
  77      dec;').
  78
  79 \1f
  80 File: autosprintf.info,  Node: Class autosprintf,  Next: Using autosprintf,  Prev: Introduction,  Up: Top
  81
  82 2 The 'autosprintf' class
  83 *************************
  84
  85 An instance of class 'autosprintf' just contains a string with the
  86 formatted output result.  Such an instance is usually allocated as an
  87 automatic storage variable, i.e. on the stack, not with 'new' on the
  88 heap.
  89
  90    The constructor 'autosprintf (const char *format, ...)' takes a
  91 format string and additional arguments, like the C function 'printf'.
  92
  93    Conversions to 'char *' and 'std::string' are defined that return the
  94 encapsulated string.  The conversion to 'char *' returns a freshly
  95 allocated copy of the encapsulated string; it needs to be freed using
  96 'delete[]'.  The conversion to 'std::string' returns a copy of the
  97 encapsulated string, with automatic memory management.
  98
  99    The destructor '~autosprintf ()' destroys the encapsulated string.
 100
 101    An 'operator <<' is provided that outputs the encapsulated string to
 102 the given 'ostream'.
 103
 104 \1f
 105 File: autosprintf.info,  Node: Using autosprintf,  Prev: Class autosprintf,  Up: Top
 106
 107 3 Using 'autosprintf' in own programs
 108 *************************************
 109
 110 To use the 'autosprintf' class in your programs, you need to add
 111
 112      #include "autosprintf.h"
 113      using gnu::autosprintf;
 114
 115 to your source code.  The include file defines the class 'autosprintf',
 116 in a namespace called 'gnu'.  The 'using' statement makes it possible to
 117 use the class without the (otherwise natural) 'gnu::' prefix.
 118
 119    When linking your program, you need to link with 'libasprintf',
 120 because that's where the class is defined.  In projects using GNU
 121 'autoconf', this means adding 'AC_LIB_LINKFLAGS([asprintf])' to
 122 'configure.in' or 'configure.ac', and using the @LIBASPRINTF@ Makefile
 123 variable that it provides.
 124
 125
 126 \1f
 127 Tag Table:
 128 Node: Top\7f1339
 129 Node: Introduction\7f1699
 130 Node: Class autosprintf\7f2852
 131 Node: Using autosprintf\7f3863
 132 \1f
 133 End Tag Table