rom/exec/vnewrawdofmt.c

   1 /*
   2     Copyright © 1995-2011, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc: Format a string and emit it.
   6     Lang: english
   7 */
   8 #include <dos/dos.h>
   9 #include <aros/libcall.h>
  10 #include <aros/asmcall.h>
  11 #include <proto/exec.h>
  12 #include <string.h>
  13
  14 #include <stdarg.h>
  15
  16 #include "exec_intern.h"
  17 #include "exec_util.h"
  18
  19 /*****************************************************************************
  20
  21     NAME */
  22
  23         AROS_LH4I(STRPTR,VNewRawDoFmt,
  24
  25 /*  SYNOPSIS */
  26         AROS_LHA(CONST_STRPTR, FormatString, A0),
  27         AROS_LHA(VOID_FUNC,    PutChProc,    A2),
  28         AROS_LHA(APTR,         PutChData,    A3),
  29         AROS_LHA(va_list,      DataStream,   A1),
  30
  31 /*  LOCATION */
  32         struct ExecBase *, SysBase, 137, Exec)
  33
  34 /*  FUNCTION
  35         printf-style formatting function with callback hook and C-style
  36         DataStream.
  37
  38     INPUTS
  39         FormatString - Pointer to the format string with any of the following
  40                        DataStream formatting options allowed:
  41
  42                        %[leftalign][minwidth.][maxwidth][size][type]
  43
  44                        leftalign - '-' means align left. Default: align right.
  45                        minwidth  - minimum width of field. Defaults to 0.
  46                        maxwidth  - maximum width of field (for strings only).
  47                                    Defaults to no limit.
  48
  49                        size      - 'l' means LONG. Defaults to WORD, if nothing is specified.
  50
  51                        type      - 'b' BSTR. It will use the internal representation
  52                                        of the BSTR defined by the ABI.
  53                                    'c' single character.
  54                                    'd' signed decimal number.
  55                                    's' C string. NULL terminated.
  56                                    'u' unsigned decimal number.
  57                                    'x' unsigned hexdecimal number.
  58                                    'P' pointer. Size depends on the architecture.
  59                                    'p' The same as 'P', for AmigaOS v4 compatibility.
  60
  61         PutChProc    - Callback function. Called for each character, including
  62                        the NULL terminator. The function should be declared as
  63                        follows:
  64
  65                        APTR PutChProc(APTR PutChData, UBYTE char);
  66
  67                        The function should return new value for PutChData variable.
  68
  69                        Additionally, PutChProc can be set to one of the following
  70                        magic values:
  71
  72                          RAWFMTFUNC_STRING - Write output to string buffer pointed
  73                                              to by PutChData which is incremented
  74                                              every character.
  75                          RAWFMTFUNC_SERIAL - Write output to debug output. PutChData
  76                                              is ignored and not touched.
  77                          RAWFMTFUNC_COUNT  - Count number of characters in the result.
  78                                              PutChData is a pointer to ULONG which
  79                                              is incremented every character. Initial
  80                                              value of the counter is kept as it is.
  81
  82         PutChData    - Data propagated to each call of the callback hook.
  83
  84         DataStream   - C-style data stream (va_list variable)
  85
  86     RESULT
  87         Final PutChData value.
  88
  89     NOTES
  90         The field size defaults to WORDs which may be different from the
  91         default integer size of the compiler.
  92
  93     EXAMPLE
  94         Build a sprintf style function:
  95
  96             void my_sprintf(UBYTE *buffer, UBYTE *format, ...)
  97             {
  98                 va_list args;
  99
 100                 va_start(args, format);
 101                 VNewRawDoFmt(format, RAWFMTFUNC_STRING, buffer, args);
 102                 va_end(args);
 103             }
 104
 105     BUGS
 106         PutChData cannot be modified from the callback hook on non-m68k
 107         systems.
 108
 109     SEE ALSO
 110
 111     INTERNALS
 112         In AROS this function supports also 'i' type specifier
 113         standing for full IPTR argument. This makes difference on
 114         64-bit machines. At the moment this addition is not stable
 115         and subject to change. Consider using %P or %p to output
 116         full 64-bit pointers.
 117
 118         When locale.library starts up this function is replaced
 119         with advanced version, supporting extensions supported
 120         by FormatString() function.
 121
 122 ******************************************************************************/
 123 {
 124     AROS_LIBFUNC_INIT
 125
 126     return InternalRawDoFmt(FormatString, NULL, PutChProc, PutChData, DataStream);
 127
 128     AROS_LIBFUNC_EXIT
 129 } /* VNewRawDoFmt */