@@@ doc wip

[mLib] / struct / buf.3.in

diff --git a/struct/buf.3.in b/struct/buf.3.in
index 083c599..1de59e1 100644 (file)
--- a/struct/buf.3.in
+++ b/struct/buf.3.in
@@ -80,19 +80,6 @@
 .\" @dbuf_getbyte
 .\" @dbuf_putbyte
 .
-.\" @buf_getf64
-.\" @buf_getf64l
-.\" @buf_getf64b
-.\" @buf_putf64
-.\" @buf_putf64l
-.\" @buf_putf64b
-.\" @dbuf_getf64
-.\" @dbuf_getf64l
-.\" @dbuf_getf64b
-.\" @dbuf_putf64
-.\" @dbuf_putf64l
-.\" @dbuf_putf64b
-.
 .\" @buf_putstrf
 .\" @buf_vputstrf
 .\" @dbuf_putstrf
@@ -165,6 +152,31 @@
 .\" @dbuf_putk64b
 .\" @dbuf_putk64l
 .
+.\" @buf_getf32
+.\" @buf_getf32l
+.\" @buf_getf32b
+.\" @buf_putf32
+.\" @buf_putf32l
+.\" @buf_putf32b
+.\" @buf_getf64
+.\" @buf_getf64l
+.\" @buf_getf64b
+.\" @buf_putf64
+.\" @buf_putf64l
+.\" @buf_putf64b
+.\" @dbuf_getf32
+.\" @dbuf_getf32l
+.\" @dbuf_getf32b
+.\" @dbuf_putf32
+.\" @dbuf_putf32l
+.\" @dbuf_putf32b
+.\" @dbuf_getf64
+.\" @dbuf_getf64l
+.\" @dbuf_getf64b
+.\" @dbuf_putf64
+.\" @dbuf_putf64l
+.\" @dbuf_putf64b
+.
 .\" @buf_getbuf8
 .\" @buf_getbuf16
 .\" @buf_getbuf16b
@@ -567,6 +579,19 @@ and
 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
 .PP
+.BI "int buf_getf32(buf *" b ", float " x );
+.BI "int buf_getf32l(buf *" b ", float " x );
+.BI "int buf_getf32b(buf *" b ", float " x );
+.BI "int buf_getf64(buf *" b ", double " x );
+.BI "int buf_getf64l(buf *" b ", double " x );
+.BI "int buf_getf64b(buf *" b ", double " x );
+.BI "int buf_putf32(buf *" b ", float *" x_out );
+.BI "int buf_putf32l(buf *" b ", float *" x_out );
+.BI "int buf_putf32b(buf *" b ", float *" x_out );
+.BI "int buf_putf64(buf *" b ", double *" x_out );
+.BI "int buf_putf64l(buf *" b ", double *" x_out );
+.BI "int buf_putf64b(buf *" b ", double *" x_out );
+.PP
 .ta 2n
 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
 .I "   body"
@@ -624,23 +649,14 @@ and
 .BR z :
 .nf
 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
-.BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p );
 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
-.BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p ", ...);"
 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
-.BI "int dbuf_vputstr" suff "(dbuf *" db ", const char *" p ", va_list *" ap );
 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
-.BI "int dbuf_putdstr" suff "(dbuf *" db ", dstr *" d );
 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
-.BI "int dbuf_getdstr" suff "(dbuf *" db ", dstr *" d );
 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
-.BI "int dbuf_putbuf" suff "(dbuf *" db ", buf *" bb );
 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
-.BI "int dbuf_getbuf" suff "(dbuf *" db ", buf *" bb );
 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
-.BI "int dbuf_putmem" suff "(dbuf *" db ", const void *" p ", size_t " sz );
 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
-.BI "void d*buf_getmem" suff "(dbuf *" db ", size_t *" sz );
 .PP
 .fi
 For
@@ -652,9 +668,7 @@ and
 .BR 64b :
 .nf
 .BI "int buf_putf" suff "(buf *" b ", double " x );
-.BI "int dbuf_putf" suff "(dbuf *" db ", double " x );
 .BI "int buf_getf" suff "(buf *" b ", double *" x );
-.BI "int dbuf_getf" suff "(dbuf *" db ", double *" x );
 .fi
 .
 .\"--------------------------------------------------------------------------
@@ -859,29 +873,61 @@ type; see
 .BR bits (3).
 .PP
 The functions
+.BR buf_getf32 ,
+.BR buf_getf32l ,
+and
+.BR buf_getf32b ,
+and
 .BR buf_getf64 ,
 .BR buf_getf64l ,
 and
-.BR buf_getf64b
-read 64-bit floating-point values
-in IEEE\ 754 Binary64 format
+.BR buf_getf64b ,
+read floating-point values
+in IEEE\ 754 Binary32 and Binary64 format
 from the buffer;
-as usual, the suffix indicates the byte ordering convention.
+as usual, the suffix indicates the format and byte ordering convention.
 On success, they store the result in
 .BI *x
 and return zero;
 on failure, they break the buffer and return zero.
 The functions
+.BR buf_putf32 ,
+.BR buf_putf32l ,
+and
+.BR buf_putf32b ,
+and
 .BR buf_putf64 ,
 .BR buf_putf64l ,
 and
 .BR buf_putf64b
 write floating-point numbers
-in IEEE\ 754 Binary64 format
+in IEEE\ 754 Binary32 and Binary64 format
 from the buffer.
 On success, they return zero; on failure, they return \-1.
 Note that these functions use IEEE\ 754 format
-even if this is not the platform-native floating-point representation.
+even if this is not the platform-native floating-point representation:
+they use the
+.BR fltfmt (3)
+functions to do their work.
+Specifically,
+they use the
+.B FLTRND_NEAREVEN
+rounding convention,
+and they ignore
+.BR FLTERR_INEXACT ,
+.BR FLTERR_UFLOW ,
+and
+.B FLTERR_OFLOW
+errors,
+and fail on
+.B FLTERR_INVAL
+and
+.B FLTERR_REPR
+errors.
+If more subtle control over error handling is necessary,
+use the
+.BR fltfmt (3)
+functions directly.
 .PP
 The function
 .B buf_putstrf
@@ -1186,6 +1232,7 @@ clear its broken flag.
 .BR bits (3),
 .BR control (3),
 .BR dstr (3),
+.BR fltfmt (3),
 .BR gprintf (3),
 .BR mLib (3).
 .