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:
parent
d60df466d3
commit
65e1bfcea7
4 changed files with 254 additions and 25 deletions
141
qe-manual.md
141
qe-manual.md
|
|
@ -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
2
qe.c
|
|
@ -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
87
util.c
|
|
@ -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
49
util.h
|
|
@ -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('_')
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue