extend API To read line/token to stralloc to allow clearing the

stralloc first.
  add stralloc_zero to clear a stralloc

CHANGES

@@ -1,6 +1,9 @@
 0.21:
   errno cleanup and man page updates (Rolf Eike Beer)
   implement iob_prefetch with madvise MADV_WILLNEED if it's defined
+  extend API To read line/token to stralloc to allow clearing the
+    stralloc first.
+  add stralloc_zero to clear a stralloc
 
 0.20:
   add errmsg API

buffer.h

@@ -104,10 +104,17 @@ int buffer_get_token_sa(buffer* b,stralloc* sa,const char* charset,unsigned int
 /* read line from buffer to stralloc */
 int buffer_getline_sa(buffer* b,stralloc* sa);
 
+/* same as buffer_get_token_sa but empty sa first */
+int buffer_get_new_token_sa(buffer* b,stralloc* sa,const char* charset,unsigned int setlen);
+/* same as buffer_getline_sa but empty sa first */
+int buffer_getnewline_sa(buffer* b,stralloc* sa);
+
 typedef int (*sa_predicate)(stralloc* sa);
 
 /* like buffer_get_token_sa but the token ends when your predicate says so */
 int buffer_get_token_sa_pred(buffer* b,stralloc* sa,sa_predicate p);
+/* same, but clear sa first */
+int buffer_get_new_token_sa_pred(buffer* b,stralloc* sa,sa_predicate p);
 
 /* make a buffer from a stralloc.
  * Do not change the stralloc after this! */

buffer/buffer_get_new_token_sa.3

@@ -0,0 +1,26 @@
+.TH buffer_get_new_token_sa 3
+.SH NAME
+buffer_get_new_token_sa \- read token from buffer
+.SH SYNTAX
+.nf
+.B #include <stralloc.h>
+.B #include <buffer.h>
+
+int \fBbuffer_get_new_token_sa\fP(buffer* \fIb\fR,stralloc* \fIsa\fR,
+                    const char* \fIcharset\fR,unsigned int \fIsetlen\fR);
+.SH DESCRIPTION
+buffer_get_new_token_sa copies data from the \fIb\fR to \fIsa\fR until
+one of the delimiters in \fIcharset\fR is found, overwriting the
+previous content of \fIsa\fR.  That delimiter is also copied to
+\fIsa\fR.
+
+If reading from the buffer or allocating memory fails,
+buffer_get_new_token_sa returns -1 and sets \fIerrno\fR appropriately.  At
+that point \fIsa\fR may already contain a partial token.
+
+On success, buffer_get_new_token_sa returns 0.
+
+If you want to read from a non-blocking socket, use buffer_get_token_sa
+instead.
+.SH "SEE ALSO"
+buffer_getline_sa(3), buffer_get_token(3), buffer(3)

buffer/buffer_get_new_token_sa.c

@@ -0,0 +1,7 @@
+#include "stralloc.h"
+#include "buffer.h"
+
+int buffer_get_new_token_sa(buffer* b,stralloc* sa,const char* charset,unsigned int setlen) {
+  stralloc_zero(sa);
+  return buffer_get_token_sa(b,sa,charset,setlen);
+}

buffer/buffer_get_new_token_sa_pred.3

@@ -0,0 +1,33 @@
+.TH buffer_get_new_token_sa_pred 3
+.SH NAME
+buffer_get_new_token_sa_pred \- read token from buffer
+.SH SYNTAX
+.nf
+.B #include <stralloc.h>
+.B #include <buffer.h>
+
+int \fBbuffer_get_new_token_sa_pred\fP(buffer* \fIb\fR,stralloc* \fIsa\fR,
+                 int (*\fIpredicate\fR)(stralloc* * \fIsa\fR));
+.SH DESCRIPTION
+buffer_get_token_sa_pred copies data from \fIb\fR to \fIsa\fR until
+\fIpredicate\fR(\fIsa\fR) returns 1 or -1.
+
+If \fIpredicate\fR returns 1 once a '\\n' was read, that new-line
+character is still appended to \fIsa\fR -- use stralloc_chop or
+stralloc_chomp to get rid of it.  \fIpredicate\fR can also return 0
+(indicating further input is required to complete the token) or -1
+(abort and return -1; use this if \fIpredicate\fR wants to enfore a
+maximum message size or does timeout handling or detects a malformed
+message).
+
+If reading from the buffer or allocating memory fails,
+buffer_get_new_token_sa_pred returns -1 and sets \fIerrno\fR
+appropriately.  At that point \fIsa\fR may already contain a partial
+token.
+
+On success, buffer_get_new_token_sa_pred returns 0.
+
+If you want to read from a non-blocking socket, use
+buffer_get_token_sa_pred instead.
+.SH "SEE ALSO"
+buffer_getline_sa(3), buffer_get_token(3), buffer(3)

buffer/buffer_get_new_token_sa_pred.c

@@ -0,0 +1,7 @@
+#include "stralloc.h"
+#include "buffer.h"
+
+int buffer_get_new_token_sa_pred(buffer* b,stralloc* sa,sa_predicate p) {
+  stralloc_zero(sa);
+  return buffer_get_token_sa_pred(b,sa,p);
+}

buffer/buffer_get_token_pred.3

@@ -18,6 +18,6 @@ to complete the token) or -1 (abort and return -1; use this if
 handling or detects a malformed message).
 
 buffer_get_token_pred returns the number of bytes copied or -1 on
-\fIerrno\fR (setting errno appropriately).
+error (setting \fIerrno\fR appropriately).
 .SH "SEE ALSO"
 buffer_init(3), buffer_feed(3), buffer_peek(3), buffer_seek(3), buffer(3)

buffer/buffer_get_token_sa_pred.3

@@ -9,7 +9,7 @@ buffer_get_token_sa_pred \- read token from buffer
 int \fBbuffer_get_token_sa_pred\fP(buffer* \fIb\fR,stralloc* \fIsa\fR,
                  int (*\fIpredicate\fR)(stralloc* * \fIsa\fR));
 .SH DESCRIPTION
-buffer_get_token_sa_pred appends data from the \fIb\fR to \fIsa\fR until
+buffer_get_token_sa_pred appends data from \fIb\fR to \fIsa\fR until
 \fIpredicate\fR(\fIsa\fR) returns 1 or -1.
 
 If \fIpredicate\fR returns 1 once a '\\n' was read, that new-line

buffer/buffer_getline.3

@@ -0,0 +1,20 @@
+.TH buffer_getline 3
+.SH NAME
+buffer_getline \- read line from buffer
+.SH SYNTAX
+.B #include <buffer.h>
+
+int \fBbuffer_getline\fP(buffer* \fIb\fR,char* \fIx\fR,unsigned int \fIlen\fR);
+.SH DESCRIPTION
+buffer_getline copies data from \fIb\fR to \fIx\fR[0], \fIx\fR[1], ...,
+\fIx\fR[\fIlen\fR-1] until \fIlen\fR bytes have been copied or a
+new-line character ('\\n') is encountered.  That character is also
+copied.
+
+buffer_getline returns the number of bytes read (excluding the '\\n') or
+-1 on error (setting \fIerrno\fR appropriately).
+
+Note that line is not 0-terminated to make reading lines with 0-bytes
+possible through this interface.
+.SH "SEE ALSO"
+buffer_init(3), buffer_feed(3), buffer_peek(3), buffer_seek(3), buffer(3)

buffer/buffer_getnewline_sa.3

@@ -0,0 +1,24 @@
+.TH buffer_getnewline_sa 3
+.SH NAME
+buffer_getnewline_sa \- read line from buffer
+.SH SYNTAX
+.nf
+.B #include <stralloc.h>
+.B #include <buffer.h>
+
+int \fBbuffer_getnewline_sa\fP(buffer* \fIb\fR,stralloc* \fIsa\fR);
+.SH DESCRIPTION
+buffer_getnewline_sa copies data from the \fIb\fR to \fIsa\fR until a '\\n'
+is found, overwriting the previous content of \fIsa\fR.  The new-line
+is also appended to \fIsa\fR.
+
+If reading from the buffer or allocating memory fails,
+buffer_getnewline_sa returns -1 and sets \fIerrno\fR appropriately.  At
+that point \fIsa\fR may be empty or it may already contain a partial
+token.
+
+On success, buffer_getnewline_sa returns 0.
+
+To read from a non-blocking socket, use buffer_getline_sa.
+.SH "SEE ALSO"
+buffer_get_token_sa(3), buffer(3)

buffer/buffer_getnewline_sa.c

@@ -0,0 +1,7 @@
+#include "stralloc.h"
+#include "buffer.h"
+
+int buffer_getnewline_sa(buffer* b,stralloc* sa) {
+  stralloc_zero(sa);
+  return buffer_getline_sa(b,sa);
+}

stralloc.h

@@ -91,6 +91,8 @@ int stralloc_diffs(const stralloc* a,const char* b) __pure__;
 /* stralloc_0 appends \0 */
 #define stralloc_0(sa) stralloc_append(sa,"")
 
+#define stralloc_zero(sa) stralloc_copys(sa,"")
+
 /* stralloc_catulong0 appends a '0' padded ASCII representation of in */
 int stralloc_catulong0(stralloc* sa,unsigned long in,unsigned int n);
 
@@ -130,10 +132,22 @@ int buffer_get_token_sa(buffer* b,stralloc* sa,const char* charset,unsigned int
 /* read line from buffer to stralloc */
 int buffer_getline_sa(buffer* b,stralloc* sa);
 
+/* same as buffer_get_token_sa but empty sa first */
+int buffer_get_new_token_sa(buffer* b,stralloc* sa,const char* charset,unsigned int setlen);
+/* same as buffer_getline_sa but empty sa first */
+int buffer_getnewline_sa(buffer* b,stralloc* sa);
+
 typedef int (*sa_predicate)(stralloc* sa);
 
 /* like buffer_get_token_sa but the token ends when your predicate says so */
 int buffer_get_token_sa_pred(buffer* b,stralloc* sa,sa_predicate p);
+/* same, but clear sa first */
+int buffer_get_new_token_sa_pred(buffer* b,stralloc* sa,sa_predicate p);
+
+
+/* make a buffer from a stralloc.
+ * Do not change the stralloc after this! */
+void buffer_fromsa(buffer* b,stralloc* sa);
 #endif
 
 #endif

stralloc/stralloc_zero.3

@@ -0,0 +1,13 @@
+.TH stralloc_zero 3
+.SH NAME
+stralloc_zero \- set length of stralloc to 0
+.SH SYNTAX
+.B #include <stralloc.h>
+
+int \fBstralloc_zero\fP(stralloc* \fIsa\fR);
+.SH DESCRIPTION
+stralloc_zero sets the length of the stralloc to 0.
+
+It is a shortcut for stralloc_copys(\fIsa\fR,"").
+.SH "SEE ALSO"
+stralloc_copys(3)