Improve buf_t API and documentation

* rename `buf_encode_byte()` as `buf_quote_byte()`
* change `buf_printf` return value for consistency
* let `strquote` always return the length of the conversion like `snprintf`
This commit is contained in:
Charlie Gordon 2024-07-18 23:20:19 +02:00
commit 65e1bfcea7
4 changed files with 254 additions and 25 deletions

View file

@ -170,6 +170,119 @@ FILENAME.
# C functions
### `struct buf_t;`
Fixed length character array handling
All output functions return the number of bytes actually written to the
output buffer and set a null terminator after any output.
### `buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos);`
Initialize a `buf_t` to output to a fixed length array at a given position.
* argument `bp` a valid pointer to fixed length buffer
* argument `buf` a valid pointer to a destination array of bytes
* argument `size` the length of the destination array
* argument `pos` the initial position for output.
Return the `buf_t` argument.
Note: `size` must be strictly positive and `pos` must be in range: `0 <= pos < size`
Note: this function does not set a null terminator at offset `pos`.
### `int buf_avail(buf_t *bp);`
Compute the number of bytes available in the destination array
* argument `bp` a valid pointer to fixed length buffer
Return the number of bytes, or `0` if the buffer is full.
### `buf_t *buf_init(buf_t *bp, char *buf, int size);`
Initialize a `buf_t` to output to a fixed length array.
* argument `bp` a valid pointer to fixed length buffer
* argument `buf` a valid pointer to a destination array of bytes
* argument `size` the length of the destination array
Return the `buf_t` argument.
### `int buf_printf(buf_t *bp, const char *fmt, ...);`
Format contents at the end of a fixed length buffer.
* argument `bp` a valid pointer to fixed length buffer
* argument `fmt` a valid pointer to a format string
Return the number of bytes actually written.
### `int buf_put_byte(buf_t *bp, unsigned char ch);`
Append a byte to a fixed length buffer.
* argument `bp` a valid pointer to fixed length buffer
* argument `ch` a byte
Return the number of bytes actually written.
### `int buf_putc_utf8(buf_t *bp, char32_t c);`
Encode a codepoint in UTF-8 at the end of a fixed length buffer.
* argument `bp` a valid pointer to fixed length buffer
* argument `c` a valid codepoint to encode
Return the number of bytes actually written.
Note: if the conversion does not fit in the destination, the
`len` field is not updated to avoid partial UTF-8 sequences.
### `int buf_puts(buf_t *bp, const char *str);`
Append a string to a fixed length buffer.
* argument `bp` a valid pointer to fixed length buffer
* argument `str` a valid pointer to a C string
Return the number of bytes actually written.
### `int buf_quote_byte(buf_t *bp, unsigned char ch);`
Encode a byte as a source code escape sequence into a fixed length buffer
* argument `bp` a valid pointer to fixed length buffer
* argument `ch` a byte value to encode as source
Return the number of bytes produced in the destination array,
not counting the null terminator
### `int buf_write(buf_t *bp, const void *src, int size);`
Write an array of bytes to a fixed length buffer.
* argument `bp` a valid pointer to fixed length buffer
* argument `src` a valid pointer to an array of bytes
* argument `size` the number of bytes to write.
Return the number of bytes actually written.
Note: content is truncated if it does not fit in the available
space in the destination buffer.
### `void qe_free(T **pp);`
Free the allocated memory pointed to by a pointer whose address is passed.
@ -344,6 +457,19 @@ Return the updated path length.
Note: truncation cannot be detected reliably
### `int byte_quote(char *dest, int size, unsigned char c);`
Encode a byte as a source code escape sequence
* argument `dest` a valid pointer to an array of bytes
* argument `size` the length of the destination array
* argument `c` a byte value to encode as source
Return the number of bytes produced in the destination array,
not counting the null terminator
### `void canonicalize_path(char *buf, int buf_size, const char *path);`
Normalize a path, removing redundant `.`, `..` and `/` parts.
@ -915,6 +1041,21 @@ Find a chunk of characters inside a string.
Return a pointer to the first character of the match if found,
`NULL` otherwise.
### `int strquote(char *dest, int size, const char *str, int len);`
Encode a string using source code escape sequences
* argument `dest` a valid pointer to an array of bytes
* argument `size` the length of the destination array
* argument `src` a valid pointer to a string to encode
* argument `len` the number of bytes to encode
Return the length of the converted string, not counting the null
terminator, possibly longer than the destination array length.
### `int strstart(const char *str, const char *val, const char **ptr);`
Test if `val` is a prefix of `str`.

2
qe.c
View file

@ -2001,7 +2001,7 @@ static void do_unknown_key(EditState *s) {
buf_init(out, buf, sizeof buf);
for (i = 0; i < qs->input_len; i++)
buf_encode_byte(out, qs->input_buf[i]);
buf_quote_byte(out, qs->input_buf[i]);
put_status(s, "Unknown key: %s", buf);
}

87
util.c
View file

@ -1672,6 +1672,15 @@ void free_strings(StringArray *cs) {
int buf_write(buf_t *bp, const void *src, int size)
{
/*@API buf
Write an array of bytes to a fixed length buffer.
@argument `bp` a valid pointer to fixed length buffer
@argument `src` a valid pointer to an array of bytes
@argument `size` the number of bytes to write.
@return the number of bytes actually written.
@note content is truncated if it does not fit in the available
space in the destination buffer.
*/
int n = 0;
if (bp->pos < bp->size) {
@ -1688,26 +1697,44 @@ int buf_write(buf_t *bp, const void *src, int size)
int buf_printf(buf_t *bp, const char *fmt, ...)
{
/*@API buf
Format contents at the end of a fixed length buffer.
@argument `bp` a valid pointer to fixed length buffer
@argument `fmt` a valid pointer to a format string
@return the number of bytes actually written.
*/
va_list ap;
char *dest = NULL;
int size = 0;
int written = 0;
int len;
if (bp->pos < bp->size) {
dest = bp->buf + bp->pos;
size = bp->size - bp->pos;
}
va_start(ap, fmt);
len = vsnprintf(bp->buf + bp->len,
(bp->pos < bp->size) ? bp->size - bp->pos : 1, fmt, ap);
len = vsnprintf(dest, size, fmt, ap);
va_end(ap);
bp->pos += len;
bp->len += len;
if (bp->len >= bp->size) {
bp->len = bp->size - 1;
if (bp->len < 0)
bp->len = 0;
if (bp->pos < bp->size) {
written = (len < size) ? len : size - 1;
bp->len += written;
}
return len;
bp->pos += len;
return written;
}
int buf_putc_utf8(buf_t *bp, char32_t c)
{
/*@API buf
Encode a codepoint in UTF-8 at the end of a fixed length buffer.
@argument `bp` a valid pointer to fixed length buffer
@argument `c` a valid codepoint to encode
@return the number of bytes actually written.
@note: if the conversion does not fit in the destination, the
`len` field is not updated to avoid partial UTF-8 sequences.
*/
if (c < 0x80) {
bp->pos++;
if (bp->pos < bp->size) {
@ -1755,12 +1782,29 @@ int strsubst(char *buf, int buf_size, const char *from,
}
int byte_quote(char *dest, int size, unsigned char c) {
/*@API utils
Encode a byte as a source code escape sequence
@argument `dest` a valid pointer to an array of bytes
@argument `size` the length of the destination array
@argument `c` a byte value to encode as source
@return the number of bytes produced in the destination array,
not counting the null terminator
*/
buf_t buf[1];
buf_init(buf, dest, size);
return buf_encode_byte(buf, c);
return buf_quote_byte(buf, c);
}
int strquote(char *dest, int size, const char *str, int len) {
/*@API utils
Encode a string using source code escape sequences
@argument `dest` a valid pointer to an array of bytes
@argument `size` the length of the destination array
@argument `src` a valid pointer to a string to encode
@argument `len` the number of bytes to encode
@return the length of the converted string, not counting the null
terminator, possibly longer than the destination array length.
*/
buf_t out[1];
buf_init(out, dest, size);
if (str) {
@ -1769,12 +1813,12 @@ int strquote(char *dest, int size, const char *str, int len) {
len = strlen(str);
buf_put_byte(out, '"');
for (i = 0; i < len; i++)
buf_encode_byte(out, str[i]);
buf_quote_byte(out, str[i]);
buf_put_byte(out, '"');
return out->pos;
} else {
return buf_puts(out, "null");
buf_puts(out, "null");
}
return out->pos;
}
#if 0
@ -1784,7 +1828,14 @@ int strunquote(char *dest, int size, const char *str, int len)
}
#endif
int buf_encode_byte(buf_t *out, unsigned char ch) {
int buf_quote_byte(buf_t *bp, unsigned char ch) {
/*@API buf
Encode a byte as a source code escape sequence into a fixed length buffer
@argument `bp` a valid pointer to fixed length buffer
@argument `ch` a byte value to encode as source
@return the number of bytes produced in the destination array,
not counting the null terminator
*/
int c;
if (((void)(c = 'n'), ch == '\n')
|| ((void)(c = 'r'), ch == '\r')
@ -1795,19 +1846,19 @@ int buf_encode_byte(buf_t *out, unsigned char ch) {
|| ((void)(c = '\''), ch == '\'') // XXX: need flag to make this optional
|| ((void)(c = '\"'), ch == '\"') // XXX: need flag to make this optional
|| ((void)(c = '\\'), ch == '\\')) {
return buf_printf(out, "\\%c", c);
return buf_printf(bp, "\\%c", c);
} else
if (ch < 32) {
//if (*p == '\e' && col > 9) {
// eb_write(b, b->total_size, "\n ", 10);
// col = 9;
//}
return buf_printf(out, "\\^%c", (ch + '@') & 127); // XXX: need flag to make this optional
return buf_printf(bp, "\\^%c", (ch + '@') & 127); // XXX: need flag to make this optional
} else
if (ch < 127) {
return buf_put_byte(out, ch);
return buf_put_byte(bp, ch);
} else {
return buf_printf(out, "\\0x%02X", ch); // XXX: need flag to make this optional
return buf_printf(bp, "\\0x%02X", ch); // XXX: need flag to make this optional
}
}

49
util.h
View file

@ -380,13 +380,25 @@ void free_strings(StringArray *cs);
typedef struct buf_t buf_t;
struct buf_t {
char *buf; /* pointer to the array holding the dynamic string */
/*@API buf
Fixed length character array handling
All output functions return the number of bytes actually written to the
output buffer and set a null terminator after any output.
*/
char *buf; /* pointer to the output array */
int size; /* size of the array pointed to by buf */
int len; /* length of output in buf. buf is null terminated */
int pos; /* output position into or beyond the end of buf */
};
static inline buf_t *buf_init(buf_t *bp, char *buf, int size) {
/*@API buf
Initialize a `buf_t` to output to a fixed length array.
@argument `bp` a valid pointer to fixed length buffer
@argument `buf` a valid pointer to a destination array of bytes
@argument `size` the length of the destination array
@return the `buf_t` argument.
*/
if (size > 0) {
bp->buf = buf;
bp->size = size;
@ -400,8 +412,16 @@ static inline buf_t *buf_init(buf_t *bp, char *buf, int size) {
}
static inline buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos) {
/* assuming 0 <= pos < size */
// XXX: Does not set a null byte?
/*@API buf
Initialize a `buf_t` to output to a fixed length array at a given position.
@argument `bp` a valid pointer to fixed length buffer
@argument `buf` a valid pointer to a destination array of bytes
@argument `size` the length of the destination array
@argument `pos` the initial position for output.
@return the `buf_t` argument.
@note `size` must be strictly positive and `pos` must be in range: `0 <= pos < size`
@note this function does not set a null terminator at offset `pos`.
*/
bp->buf = buf;
bp->size = size;
bp->len = bp->pos = pos;
@ -409,11 +429,22 @@ static inline buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos) {
}
static inline int buf_avail(buf_t *bp) {
return bp->size - bp->pos - 1;
/*@API buf
Compute the number of bytes available in the destination array
@argument `bp` a valid pointer to fixed length buffer
@return the number of bytes, or `0` if the buffer is full.
*/
return (bp->pos < bp->size) ? bp->size - bp->pos - 1 : 0;
}
static inline int buf_put_byte(buf_t *bp, unsigned char ch) {
if (bp->len < bp->size - 1) {
/*@API buf
Append a byte to a fixed length buffer.
@argument `bp` a valid pointer to fixed length buffer
@argument `ch` a byte
@return the number of bytes actually written.
*/
if (bp->pos + 1 < bp->size) {
bp->buf[bp->len++] = ch;
bp->buf[bp->len] = '\0';
}
@ -423,6 +454,12 @@ static inline int buf_put_byte(buf_t *bp, unsigned char ch) {
int buf_write(buf_t *bp, const void *src, int size);
static inline int buf_puts(buf_t *bp, const char *str) {
/*@API buf
Append a string to a fixed length buffer.
@argument `bp` a valid pointer to fixed length buffer
@argument `str` a valid pointer to a C string
@return the number of bytes actually written.
*/
return buf_write(bp, str, strlen(str));
}
@ -460,7 +497,7 @@ int strtokey(const char **pp);
int strtokeys(const char *keystr, unsigned int *keys, int max_keys, const char **endp);
int buf_put_key(buf_t *out, int key);
int buf_put_keys(buf_t *out, unsigned int *keys, int nb_keys);
int buf_encode_byte(buf_t *out, unsigned char ch);
int buf_quote_byte(buf_t *out, unsigned char ch);
/* XXX: should use a more regular key mapping scheme:
- 0000..001F: standard control keys: KEY_CTRL('@') to KEY_CTRL('@') to KEY_CTRL('_')