X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/e63124bc579bfd97cfe2f620ddd84df9f20477d8..08bb7015a9e28c5c9d38fe05a6f6644bc21fa527:/utils/gprintf.h

diff --git a/utils/gprintf.h b/utils/gprintf.h
index 9e32338..bcef7bb 100644
--- a/utils/gprintf.h
+++ b/utils/gprintf.h
@@ -36,6 +36,10 @@
 
 #include <stdarg.h>
 
+#ifndef MLIB_ARENA_H
+#  include "arena.h"
+#endif
+
 #ifndef MLIB_MACROS_H
 #  include "macros.h"
 #endif
@@ -45,46 +49,70 @@
 struct gprintf_ops {
   int (*putch)(void */*out*/, int /*ch*/);
   int (*putm)(void */*out*/, const char */*p*/, size_t /*sz*/);
-  PRINTF_LIKE(3, 4) int (*nputf)
-    (void */*out*/, size_t /*maxsz*/, const char */*p*/, ...);
+  PRINTF_LIKE(3, 4)
+    int (*nputf)(void */*out*/, size_t /*maxsz*/, const char */*p*/, ...);
 };
 
 extern const struct gprintf_ops file_printops;
 
 /*----- Functions provided ------------------------------------------------*/
 
-/* --- @vgprintf@ --- *
+/* --- @gprintf@, @vgprintf@ --- *
  *
  * Arguments:	@const struct gprintf_ops *ops@ = output operations
  *		@void *out@ = context for output operations
  *		@const char *p@ = pointer to @printf@-style format string
- *		@va_list *ap@ = argument handle
+ *		@...@ = format arguments
+ *		@va_list *ap@ = captured format-arguments tail
  *
  * Returns:	The number of characters written to the string.
  *
- * Use:		As for @gprintf@, but takes a reified argument tail.
+ * Use:		Formats a @printf@-like message and writes the result using
+ *		the given output operations.  This is the backend machinery
+ *		for @dstr_putf@, for example.
+ *
+ *		The @gprintf@ function receives its format arguments as a
+ *		variable-length argument tail; the @vgprintf@ function
+ *		receives them as %%\emph{a pointer to}%% a captured argument
+ *		tail; it updates @*ap@, leaving it ready to read the next
+ *		unused argument.
  */
 
+extern PRINTF_LIKE(3, 4)
+  int gprintf(const struct gprintf_ops */*ops*/, void */*out*/,
+	      const char */*p*/, ...);
 extern int vgprintf(const struct gprintf_ops */*ops*/, void */*out*/,
 		    const char */*p*/, va_list */*ap*/);
 
-/* --- @gprintf@ --- *
+/* --- @gprintf_memputf@ --- *
  *
- * Arguments:	@const struct gprintf_ops *ops@ = output operations
- *		@void *out@ = context for output operations
- *		@const char *p@ = pointer to @printf@-style format string
- *		@...@ = argument handle
+ * Arguments:	@arena *a@ = memory allocation arena
+ *		@char **buf_inout@ = address of output buffer pointer
+ *		@size_t *sz_inout@ = address of buffer size
+ *		@size_t maxsz@ = buffer size needed for this operation
+ *		@const char *p@ = pointer to format string
+ *		@va_list *ap@ = captured format-arguments tail
  *
- * Returns:	The number of characters written to the string.
+ * Returns:	The formatted length.
  *
- * Use:		Formats a @printf@-like message and writes the result using
- *		the given output operations.  This is the backend machinery
- *		for @dstr_putf@, for example.
+ * Use:		Generic utility for mostly implementing the @nputf@ output
+ *		function, if you don't have a better option.
+ *
+ *		On entry, @*buf_inout@ should be null or a buffer pointer,
+ *		with @*sz_inout@ either zero or the buffer's size,
+ *		respectively.  On exit, @*buf_input@ and @*sz_inout@ will be
+ *		updated, if necessary, to describe a sufficiently large
+ *		buffer, and the formatted string will have been written to
+ *		the buffer.
+ *
+ *		When the buffer is no longer required, free it using
+ *		@x_free@.
  */
 
-extern int PRINTF_LIKE(3, 4)
-  gprintf(const struct gprintf_ops */*ops*/, void */*out*/,
-	  const char */*p*/, ...);
+extern size_t gprintf_memputf(arena */*a*/,
+			      char **/*buf_inout*/, size_t */*sz_inout*/,
+			      size_t /*maxsz*/,
+			      const char */*p*/, va_list /*ap*/);
 
 /*----- That's all, folks -------------------------------------------------*/