text.h File Reference

Small text helpers for application code: compare a byte view with a C string, copy a view out as a C string, and dump a view as hex or as text. More...

#include "common/bytes/span/span.h"
#include "common/bytes/util/bytes.h"
#include "common/platform/sys/syscall.h"

Go to the source code of this file.

Macros
#define	WIRED_SPAN_ARG(s)
	printf arguments for a "%.*s" conversion of the view s, e.g.

Functions
static wired_span	wired_span_cstr (const char *s)
	View of a NUL-terminated string's bytes (the NUL excluded).
int	wired_span_eq_cstr (wired_span s, const char *lit)
	Whether s holds exactly the bytes of the NUL-terminated lit.
int	wired_span_eq (wired_span a, wired_span b)
	Whether a and b hold the same bytes (same length, same content).
ssz	wired_span_find (wired_span s, u8 c)
	Index of the first byte c in s.
usz	wired_span_to_cstr (char *out, usz cap, wired_span s)
	Copy s into out as a NUL-terminated string, truncated to cap - 1 bytes.
usz	wired_hex_encode (char *out, usz cap, wired_span s)
	Lowercase hex of s into out, NUL-terminated; stops at the last whole byte that fits in cap - 1 characters.
void	wired_dump_hex (i64 fd, wired_span s)
	Write s to fd as lowercase hex, no separators and no newline.
void	wired_dump_text (i64 fd, wired_span s)
	Write the bytes of s to fd as they are (a text view needs no NUL).
int	wired_cstr_eq (const char *a, const char *b)
	Whether two NUL-terminated strings are equal.
usz	wired_cstr_append (char *dst, usz cap, usz at, wired_span s)
	Append s to the C string in dst at offset at, keeping dst NUL-terminated and cutting at cap - 1 bytes.
wired_span	wired_span_strip_lead (wired_span s, u8 c)
	s without one leading byte c, or s itself when it does not start with c (e.g.
usz	wired_obuf_put (wired_obuf *b, wired_span s)
	Append the bytes of s to b at b->len, cut at b->cap (no NUL is written).

Detailed Description

Small text helpers for application code: compare a byte view with a C string, copy a view out as a C string, and dump a view as hex or as text.

They replace the per-program span_is / log_hex / log_span helpers samples used to carry.

Macro Definition Documentation

WIRED_SPAN_ARG

#define WIRED_SPAN_ARG

(

s

)

Value:

(int)(s).n, (const char*)(s).p

printf arguments for a "%.*s" conversion of the view s, e.g.

wired_dprintf(2, "path %.*s\n", WIRED_SPAN_ARG(path)).

Function Documentation

wired_cstr_append()

usz wired_cstr_append	(	char *	dst,
		usz	cap,
		usz	at,
		wired_span	s )

Append s to the C string in dst at offset at, keeping dst NUL-terminated and cutting at cap - 1 bytes.

Parameters

dst	destination buffer (cap bytes; untouched when cap is 0)
cap	capacity of dst including the NUL
at	current length of the string in dst; at >= cap appends nothing and returns at
s	bytes to append (wired_span_cstr for a C string)

Returns

the new length

wired_cstr_eq()

int wired_cstr_eq	(	const char *	a,
		const char *	b )

Whether two NUL-terminated strings are equal.

Parameters

a	first string
b	second string

Returns

1 if equal, 0 otherwise

wired_dump_hex()

void wired_dump_hex	(	i64	fd,
		wired_span	s )

Write s to fd as lowercase hex, no separators and no newline.

Parameters

fd	file descriptor (2 = stderr)
s	bytes to dump

wired_dump_text()

void wired_dump_text	(	i64	fd,
		wired_span	s )

Write the bytes of s to fd as they are (a text view needs no NUL).

Parameters

fd	file descriptor (2 = stderr)
s	bytes to write

wired_hex_encode()

usz wired_hex_encode	(	char *	out,
		usz	cap,
		wired_span	s )

Lowercase hex of s into out, NUL-terminated; stops at the last whole byte that fits in cap - 1 characters.

Parameters

out	destination (untouched when cap is 0)
cap	capacity of out including the NUL
s	bytes to encode

Returns

characters written, excluding the NUL

wired_obuf_put()

usz wired_obuf_put	(	wired_obuf *	b,
		wired_span	s )

Append the bytes of s to b at b->len, cut at b->cap (no NUL is written).

Parameters

b	buffer to append to
s	bytes to append

Returns

bytes appended

wired_span_cstr()

wired_span wired_span_cstr ( const char * s )

inlinestatic

View of a NUL-terminated string's bytes (the NUL excluded).

Parameters

s	NUL-terminated string; must outlive the view

Returns

view of s

wired_span_eq()

int wired_span_eq	(	wired_span	a,
		wired_span	b )

Whether a and b hold the same bytes (same length, same content).

Not constant-time; use the ct helpers for secrets.

Parameters

a	first view
b	second view

Returns

1 if equal, 0 otherwise

wired_span_eq_cstr()

int wired_span_eq_cstr	(	wired_span	s,
		const char *	lit )

Whether s holds exactly the bytes of the NUL-terminated lit.

Parameters

s	byte view (e.g. a request path or a track name)
lit	NUL-terminated string

Returns

1 if equal, 0 otherwise

wired_span_find()

ssz wired_span_find	(	wired_span	s,
		u8	c )

Index of the first byte c in s.

Parameters

s	view to search
c	byte to find

Returns

its index, or -1 if s does not contain c

wired_span_strip_lead()

wired_span wired_span_strip_lead	(	wired_span	s,
		u8	c )

s without one leading byte c, or s itself when it does not start with c (e.g.

a request path without its leading '/').

Parameters

s	view
c	byte to drop

Returns

the possibly shortened view

wired_span_to_cstr()

usz wired_span_to_cstr	(	char *	out,
		usz	cap,
		wired_span	s )

Copy s into out as a NUL-terminated string, truncated to cap - 1 bytes.

Parameters

out	destination (untouched when cap is 0)
cap	capacity of out including the NUL
s	bytes to copy

Returns

bytes copied, excluding the NUL