gettext-runtime/libasprintf/autosprintf.info

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