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' can be used, but effectively ignored for
  50                                    backwards compatibility with original RawDoFmt().
  51                                    In C arguments are always at least int-sized.
  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                                    'P' pointer. Size depends on the architecture.
  61                                    'p' The same as 'P', for AmigaOS v4 compatibility.
  62
  63         PutChProc    - Callback function. Called for each character, including
  64                        the NULL terminator. The function should be declared as
  65                        follows:
  66
  67                        APTR PutChProc(APTR PutChData, UBYTE char);
  68
  69                        The function should return new value for PutChData variable.
  70
  71                        Additionally, PutChProc can be set to one of the following
  72                        magic values:
  73
  74                          RAWFMTFUNC_STRING - Write output to string buffer pointed
  75                                              to by PutChData which is incremented
  76                                              every character.
  77                          RAWFMTFUNC_SERIAL - Write output to debug output. PutChData
  78                                              is ignored and not touched.
  79                          RAWFMTFUNC_COUNT  - Count number of characters in the result.
  80                                              PutChData is a pointer to ULONG which
  81                                              is incremented every character. Initial
  82                                              value of the counter is kept as it is.
  83
  84         PutChData    - Data propagated to each call of the callback hook.
  85
  86         DataStream   - C-style data stream (va_list variable)
  87
  88     RESULT
  89         Final PutChData value.
  90
  91     NOTES
  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
 107     SEE ALSO
 108
 109     INTERNALS
 110         In AROS this function supports also 'i' type specifier
 111         standing for full IPTR argument. This makes difference on
 112         64-bit machines. At the moment this addition is not stable
 113         and subject to change. Consider using %P or %p to output
 114         full 64-bit pointers.
 115
 116         When locale.library starts up this function is replaced
 117         with advanced version, supporting extensions supported
 118         by FormatString() function.
 119
 120 ******************************************************************************/
 121 {
 122     AROS_LIBFUNC_INIT
 123
 124     return InternalRawDoFmt(FormatString, NULL, PutChProc, PutChData, DataStream);
 125
 126     AROS_LIBFUNC_EXIT
 127 } /* VNewRawDoFmt */