Improving default flush mechanism

Author: Telemechanics

inc/BufPrint.h

@@ -10,7 +10,7 @@
  ****************************************************************************
  *            HEADER
  *
- *   $Id: BufPrint.h 4915 2021-12-01 18:26:55Z wini $
+ *   $Id: BufPrint.h 5029 2022-01-16 21:32:09Z wini $
  *
  *   COPYRIGHT:  Real Time Logic LLC, 2008 - 2022
  *
@@ -85,25 +85,38 @@ BA_API int basnprintf(char* buf, int len, const char* fmt, ...);
 
 /** BufPrint flush callback function.
 
-A BufPrint instance calls the flush callback function when buffer is
-full. The callback can either extend the buffer or flush and reset the
-buffer.
+A BufPrint instance calls the flush callback function when the buffer
+is full or when #BufPrint::flush is called. The callback can either
+extend the buffer or flush and reset the buffer.
+
+The following default callback is set if no callback is installed when
+calling the BufPrint constructor:
+
+\code
+BufPrint_defaultFlush(struct BufPrint* bp, int sizeRequired)
+{
+   bp->cursor=0; // Reset
+   baAssert(sizeRequired == 0); // Program error in code calling BufPrint_xxx
+   return sizeRequired ? -1 : 0;
+}
+\endcode
 
 \param o the object. BufPrint is typically upcasted to the derived object.
-\param sizeRequired the required expands size if the callback is
-expanding the buffer. Not used when flushing and resetting the buffer.
+\param sizeRequired the minimum size the buffer must expand. Note that
+sizeRequired will be zero when the callback is called via
+BufPrint::flush
+
 */
 typedef int (*BufPrint_Flush)(struct BufPrint* o, int sizeRequired);
 
 /** The BufPrint class, which implements an ANSI compatible printf
-    method, is an abstract class used as a base for many of the
-    Barracuda classes.
-
-    The output from printf is formatted in an internal buffer. This
-    class does not allocate memory for the buffer. Thus, any class
-    using BufPrint must provide a buffer BufPrint can use. BufPrint
-    calls the callback function BufPrint_Flush when the buffer is
-    full.
+    method, is a base class used by several other classes.
+
+    This class does not allocate memory for the buffer. Thus, any
+    class using BufPrint must provide a buffer BufPrint can use. The
+    output from printf is formatted in the buffer passed into the
+    constructor. BufPrint calls the callback function BufPrint_Flush
+    when the buffer is full. See #BufPrint_Flush for additional details.
  */
 typedef struct BufPrint
 {
@@ -114,7 +127,8 @@ typedef struct BufPrint
 
           \param userData an optional argument stored in the BufPrint
           object and accessible in the flush callback.
-          \param flush a pointer to the flush callback function.
+          \param flush a pointer to the flush callback function. See
+          #BufPrint_Flush for details.
 
           \sa setBuf(), getUserData()
       */
@@ -127,7 +141,8 @@ typedef struct BufPrint
        \param size the buffer size
        \param userData an optional argument stored in the BufPrint
        object and accessible in the flush callback.
-       \param flush a pointer to the flush callback function.
+       \param flush a pointer to the flush callback function. See
+       #BufPrint_Flush for details.
        
        \sa setBuf(), getUserData()
    */

inc/JEncoder.h

@@ -11,9 +11,9 @@
  ****************************************************************************
  *			      HEADER
  *
- *   $Id: JEncoder.h 4915 2021-12-01 18:26:55Z wini $
+ *   $Id: JEncoder.h 5029 2022-01-16 21:32:09Z wini $
  *
- *   COPYRIGHT:  Real Time Logic LLC, 2006-2018
+ *   COPYRIGHT:  Real Time Logic LLC, 2006-2022
  *
  *   This software is copyrighted by and is the sole property of Real
  *   Time Logic LLC.  All rights, title, ownership, or other interests in
@@ -49,7 +49,19 @@
 /** The JEncoder can serialize a JSON JVAL syntax tree to the JSON
     text format. The JEncoder can also be used for assembling JSON
     text from calling the primitive methods in this class.
- */
+
+Example:
+\code
+   JErr err;
+   char buf[40]; //Must be sufficiently large for the JSON string
+   BufPrint jBuf(buf,sizeof(buf));
+   JEncoder jEnc(&err,&jBuf);
+   jEnc.set("{d}", "The number of the day is", 5);
+   //jBuf.buf == buf
+   buf[jBuf.cursor]=0; // So we can use printf
+   printf("%s\n",buf); // Prints: {"The number of the day is":5}
+\endcode
+*/
 typedef struct JEncoder
 {
 #ifdef __cplusplus

src/BufPrint.c

@@ -10,7 +10,7 @@
  ****************************************************************************
  *            PROGRAM MODULE
  *
- *   $Id: BufPrint.c 4975 2021-12-29 01:54:26Z wini $
+ *   $Id: BufPrint.c 5029 2022-01-16 21:32:09Z wini $
  *
  *   COPYRIGHT:  Real Time Logic, 2002 - 2022
  *
@@ -46,11 +46,15 @@
  ***************************************************************************/
 
 static int
-sprintfIsFull(struct BufPrint* print, int sizeRequired)
+BufPrint_defaultFlush(struct BufPrint* bp, int sizeRequired)
 {
-   (void)print; /* not used */
-   (void)sizeRequired; /* not used */
-   return -1; /* Failed, buffer is full */
+   bp->cursor=0; /* Reset */
+   /* Buffer is full if sizeRequired set (if not a
+    * BufPrint_flush() call)
+    * This indicates a program error.
+    */
+   baAssert(sizeRequired == 0); /* Program error in code calling BufPrint_xxx */
+   return sizeRequired ? -1 : 0;
 }
 
 
@@ -61,7 +65,7 @@ basnprintf(char* buf, int len, const char* fmt, ...)
    va_list varg;
    BufPrint bufPrint;
    /* (len -1) -> -1 -> space for the string terminator */
-   BufPrint_constructor2(&bufPrint, buf, (len -1), 0, sprintfIsFull);
+   BufPrint_constructor2(&bufPrint, buf, (len -1), 0, BufPrint_defaultFlush);
    va_start(varg, fmt);
    retv = BufPrint_vprintf(&bufPrint, fmt, varg);
    if( retv >= 0 )
@@ -82,7 +86,7 @@ basprintf(char* buf, const char* fmt, ...)
    BufPrint bufPrint;
    /* We have no idea what the size is so let's set it to fffff */
    BufPrint_constructor2(
-      &bufPrint, buf, (int)((unsigned int)(~0)/2u), 0, sprintfIsFull);
+      &bufPrint, buf, (int)((unsigned int)(~0)/2u), 0, BufPrint_defaultFlush);
    bufPrint.cursor = 0; /* Start position is beginning of buf */
    va_start(varg, fmt);
    retv = BufPrint_vprintf(&bufPrint, fmt, varg);
@@ -204,7 +208,7 @@ BufPrint_constructor(BufPrint* o, void* userData, BufPrint_Flush flush)
 {
    memset(o, 0, sizeof(BufPrint));
    o->userData = userData;
-   o->flushCB = flush ? flush : sprintfIsFull;
+   o->flushCB = flush ? flush : BufPrint_defaultFlush;
 }
 
 BA_API void
@@ -1098,6 +1102,10 @@ BufPrint_flush(BufPrint* o)
    if(!o)
       return -1;
    if(o->cursor)
-      return o->flushCB(o, 0);
+   {
+      int rsp = o->flushCB(o, 0);
+      o->cursor=0;
+      return rsp;
+   }
    return 0;
 }