@@@ fltfmt mess

[mLib] / utils / gprintf.h

/* -*-c-*-
 *
 * Generalized string formatting
 *
 * (c) 2023 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

#ifndef MLIB_GPRINTF_H
#define MLIB_GPRINTF_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stdarg.h>

#ifndef MLIB_MACROS_H
#  include "macros.h"
#endif

/*----- Data structures ---------------------------------------------------*/

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*/, ...);
};

extern const struct gprintf_ops file_printops;

/*----- Functions provided ------------------------------------------------*/

/* --- @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
 *		@...@ = format arguments
 *		@va_list *ap@ = captured format-arguments tail
 *
 * Returns:	The number of characters written to the string.
 *
 * 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_memputf@ --- *
 *
 * 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 formatted length.
 *
 * 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 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 -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif