jak-project/third-party/curl/docs/internals/STRPARSE.md

String parsing with strparse

The functions take input via a pointer to a pointer, which allows the functions to advance the pointer on success which then by extension allows "chaining" of functions like this example that gets a word, a space and then a second word:

if(curlx_str_word(&line, &word1, MAX) ||
   curlx_str_singlespace(&line) ||
   curlx_str_word(&line, &word2, MAX))
  fprintf(stderr, "ERROR\n");

The input pointer must point to a null-terminated buffer area or these functions risk continuing "off the edge".

Strings

The functions that return string information does so by populating a struct Curl_str:

struct Curl_str {
  char *str;
  size_t len;
};

Access the struct fields with curlx_str() for the pointer and curlx_strlen() for the length rather than using the struct fields directly.

curlx_str_init

void curlx_str_init(struct Curl_str *out)

This initiates a string struct. The parser functions that store info in strings always init the string themselves, so this stand-alone use is often not necessary.

curlx_str_assign

void curlx_str_assign(struct Curl_str *out, const char *str, size_t len)

Set a pointer and associated length in the string struct.

curlx_str_word

int curlx_str_word(char **linep, struct Curl_str *out, const size_t max);

Get a sequence of bytes until the first space or the end of the string. Return non-zero on error. There is no way to include a space in the word, no sort of escaping. The word must be at least one byte, otherwise it is considered an error.

max is the longest accepted word, or it returns error.

On a successful return, linep is updated to point to the byte immediately following the parsed word.

curlx_str_until

int curlx_str_until(char **linep, struct Curl_str *out, const size_t max,
                   char delim);

Like curlx_str_word but instead of parsing to space, it parses to a given custom delimiter non-zero byte delim.

max is the longest accepted word, or it returns error.

The parsed word must be at least one byte, otherwise it is considered an error.

curlx_str_untilnl

int curlx_str_untilnl(char **linep, struct Curl_str *out, const size_t max);

Like curlx_str_untilnl but instead parses until it finds a "newline byte". That means either a CR (ASCII 13) or an LF (ASCII 10) octet.

max is the longest accepted word, or it returns error.

The parsed word must be at least one byte, otherwise it is considered an error.

curlx_str_cspn

int curlx_str_cspn(const char **linep, struct Curl_str *out, const char *cspn);

Get a sequence of characters until one of the bytes in the cspn string matches. Similar to the strcspn function.

curlx_str_quotedword

int curlx_str_quotedword(char **linep, struct Curl_str *out, const size_t max);

Get a "quoted" word. This means everything that is provided within a leading and an ending double quote character. No escaping possible.

max is the longest accepted word, or it returns error.

The parsed word must be at least one byte, otherwise it is considered an error.

curlx_str_single

int curlx_str_single(char **linep, char byte);

Advance over a single character provided in byte. Return non-zero on error.

curlx_str_singlespace

int curlx_str_singlespace(char **linep);

Advance over a single ASCII space. Return non-zero on error.

curlx_str_passblanks

void curlx_str_passblanks(char **linep);

Advance over all spaces and tabs.

curlx_str_trimblanks

void curlx_str_trimblanks(struct Curl_str *out);

Trim off blanks (spaces and tabs) from the start and the end of the given string.

curlx_str_number

int curlx_str_number(char **linep, curl_size_t *nump, size_t max);

Get an unsigned decimal number not larger than max. Leading zeroes are swallowed. Return non-zero on error. Returns error if there was not a single digit.

curlx_str_numblanks

int curlx_str_numblanks(char **linep, curl_size_t *nump);

Get an unsigned 63-bit decimal number. Leading blanks and zeroes are skipped. Returns non-zero on error. Returns error if there was not a single digit.

curlx_str_hex

int curlx_str_hex(char **linep, curl_size_t *nump, size_t max);

Get an unsigned hexadecimal number not larger than max. Leading zeroes are swallowed. Return non-zero on error. Returns error if there was not a single digit. Does not handled 0x prefix.

curlx_str_octal

int curlx_str_octal(char **linep, curl_size_t *nump, size_t max);

Get an unsigned octal number not larger than max. Leading zeroes are swallowed. Return non-zero on error. Returns error if there was not a single digit.

curlx_str_newline

int curlx_str_newline(char **linep);

Check for a single CR or LF. Return non-zero on error */

curlx_str_casecompare

int curlx_str_casecompare(struct Curl_str *str, const char *check);

Returns true if the provided string in the str argument matches the check string case insensitively.

curlx_str_cmp

int curlx_str_cmp(struct Curl_str *str, const char *check);

Returns true if the provided string in the str argument matches the check string case sensitively. This is not the same return code as strcmp.

curlx_str_nudge

int curlx_str_nudge(struct Curl_str *str, size_t num);

Removes num bytes from the beginning (left) of the string kept in str. If num is larger than the string, it instead returns an error.