rom/exec/vnewrawdofmt.c

   1 /*
   2     Copyright © 1995-2008, 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_util.h"
  17
  18 /*****************************************************************************
  19
  20     NAME */
  21
  22         AROS_LH4I(STRPTR,VNewRawDoFmt,
  23
  24 /*  SYNOPSIS */
  25         AROS_LHA(CONST_STRPTR, FormatString, A0),
  26         AROS_LHA(VOID_FUNC,    PutChProc,    A2),
  27         AROS_LHA(APTR,         PutChData,    A3),
  28         AROS_LHA(va_list,      DataStream,   A1),
  29
  30 /*  LOCATION */
  31         struct ExecBase *, SysBase, 87, Exec)
  32
  33 /*  FUNCTION
  34         printf-style formatting function with callback hook and C-style
  35         DataStream.
  36
  37     INPUTS
  38         FormatString - Pointer to the format string with any of the following
  39                        DataStream formatting options allowed:
  40
  41                        %[leftalign][minwidth.][maxwidth][size][type]
  42
  43                        leftalign - '-' means align left. Default: align right.
  44                        minwidth  - minimum width of field. Defaults to 0.
  45                        maxwidth  - maximum width of field (for strings only).
  46                                    Defaults to no limit.
  47
  48                        size      - 'w' means WORD.
  49                                    'l' means IPTR (LONG on 32-bit architectures and QUAD on 64-bit).
  50
  51                                    defaults to WORD, if nothing is specified.
  52
  53                        type      - 'b' BSTR. It will use the internal representation
  54                                        of the BSTR defined by the ABI.
  55                                    'c' single character.
  56                                    'd' signed decimal number.
  57                                    's' C string. NULL terminated.
  58                                    'u' unsigned decimal number.
  59                                    'x' unsigned hexdecimal number.
  60
  61         DataStream   - C-style data stream (va_list variable)
  62
  63         PutChProc    - Callback function. In caseCalled for each character, including
  64                        the NULL terminator. The fuction is called as follow:
  65
  66                        AROS_UFC2(void, PutChProc,
  67                                  AROS_UFCA(UBYTE, char,      D0),
  68                                  AROS_UFCA(APTR , PutChData, A3));
  69
  70         PutChData    - Data propagated to each call of the callback hook.
  71
  72     RESULT
  73         Pointer to the rest of the DataStream.
  74
  75     NOTES
  76         The field size defaults to words which may be different from the
  77         default integer size of the compiler.
  78
  79     EXAMPLE
  80         Build a sprintf style function:
  81
  82             static void callback(UBYTE chr __reg(d0), UBYTE **data __reg(a3))
  83             {
  84                *(*data)++=chr;
  85             }
  86
  87             void my_sprintf(UBYTE *buffer, UBYTE *format, ...)
  88             {
  89                 va_list args;
  90
  91                 va_start(args, format);
  92                 VNewRawDoFmt(format, args, &callback, &buffer);
  93                 va_end(args);
  94             }
  95
  96         The above example uses __stackparm attribute in the function
  97         prototype in order to make sure that arguments are all passed on
  98         the stack on all architectures. The alternative is to use
  99         VNewRawDoFmt() function which takes DataStream in the form of
 100         va_list instead of linear array.
 101
 102     BUGS
 103         PutChData cannot be modified from the callback hook on non-m68k
 104         systems.
 105
 106     SEE ALSO
 107
 108     INTERNALS
 109
 110 ******************************************************************************/
 111 {
 112     AROS_LIBFUNC_INIT
 113
 114     return InternalRawDoFmt(FormatString, NULL, PutChProc, PutChData, DataStream);
 115
 116     AROS_LIBFUNC_EXIT
 117 } /* VNewRawDoFmt */