Extraction

Functions
bool	strscToken (strscan *sc, string *out, strref delims)
bool	strscUntil (strscan *sc, string *out, strref text)
bool	strscWhile (strscan *sc, string *out, strref chars)
bool	strscQuoted (strscan *sc, string *out)
bool	strscLine (strscan *sc, string *out)
bool	strscRest (strscan *sc, string *out)
void	strscSpan (strscan *sc, int32 *off, int32 *len)

Detailed Description

Every extraction function takes an output string handle that may be NULL, which consumes the text without building a string for it. The span that was consumed is always recorded and can be read back with strscSpan(), which is how a token is compared against something without materializing it at all.

Function Documentation

strscLine()

bool strscLine	(	strscan *	sc,
		string *	out
	)

Reads one line and consumes its terminator.

Accepts CRLF or a bare LF. The last line of a string needs no terminator. The result never includes the terminator, and an empty line is a valid result.

Parameters

sc	Scanner to read from
out	Receives the line, or NULL to consume it

Returns

true if there was a line left to read

strscQuoted()

bool strscQuoted	(	strscan *	sc,
		string *	out
	)

Reads a double-quoted string and removes its escapes.

Requires a " at the cursor and reads to the closing one, turning \x into x along the way. The quotes themselves are consumed but are not part of the result.

The recorded span covers the text between the quotes as it appeared in the input, so it still contains any backslashes.

Parameters

sc	Scanner to read from
out	Receives the unescaped contents, or NULL to consume them

Returns

true if a complete quoted string was read

strscRest()

bool strscRest	(	strscan *	sc,
		string *	out
	)

Reads everything left and moves the cursor to the end.

An empty remainder is a valid result.

Parameters

sc	Scanner to read from
out	Receives the remaining text, or NULL to consume it

Returns

true unless the scan had already failed

strscSpan()

void strscSpan	(	strscan *	sc,
		int32 *	off,
		int32 *	len
	)

Reports the span of the most recent extraction.

The offset and length index into the scanner's own string, so the text can be compared with strRangeEq() or copied out with strSubStr() without having built a string for it in the first place.

Parameters

sc	Scanner to inspect
off	Receives the byte offset of the span
len	Receives the length of the span

Example:

int32 off, len;
strscToken(&sc, NULL, _SL(" "));
strscSpan(&sc, &off, &len);
if (strRangeEqi(sc.s, _SL("GET"), off, len)) { ... }

strscToken()

bool strscToken	(	strscan *	sc,
		string *	out,
		strref	delims
	)

Reads a run of bytes up to the next delimiter.

Stops before the delimiter without consuming it. An empty token is a failure - use strscUntil() where an empty result is meaningful.

Parameters

sc	Scanner to read from
out	Receives the token, or NULL to consume it without building a string
delims	Set of bytes that end the token

Returns

true if at least one byte was read

strscUntil()

bool strscUntil	(	strscan *	sc,
		string *	out,
		strref	text
	)

Reads everything up to the next occurrence of some text.

Stops before the text without consuming it, and fails if the text does not appear at all. An empty result is fine - it just means the text is at the cursor already.

Parameters

sc	Scanner to read from
out	Receives the text read, or NULL to consume it without building a string
text	Text to stop before

Returns

true if the text was found

strscWhile()

bool strscWhile	(	strscan *	sc,
		string *	out,
		strref	chars
	)

Reads a run of bytes drawn from a set.

The mirror of strscToken(): it stops at the first byte that is not in the set. An empty run is a failure.

Parameters

sc	Scanner to read from
out	Receives the run, or NULL to consume it without building a string
chars	Set of bytes the run may contain

Returns

true if at least one byte was read