Utilities

Modules
	Assertions and type checking

Macros
#define	STRLEN_LTRL(s)   (sizeof(s) - 1)
	Length of a literal string. More...

Functions
err_t	format_decimal (char *s, size_t *len, int32_t n)
	Format a decimal number. More...
err_t	format_hex (char *s, size_t *len, uint32_t n, bool upper)
	Format a hexadecimal number. More...
err_t	hex_decode (const char *const buf, ssize_t len, uint64_t *n)
	Decode a hexadecimal string. More...

Variables
static const char *	wday_name []
	Weekday name abbreviations. More...
static const char *	month_name []
	Month name abbreviations. More...

Detailed Description

Helper functions and structures that are used by the server core code and may also be useful for application code.

Macro Definition Documentation

STRLEN_LTRL

#define STRLEN_LTRL

(

s

)

(sizeof(s) - 1)

Return the length of a C literal string – a compile-time constant string, such as "foo". This is useful where a string length is required and it would be redundant to call strlen() on every invocation.

Example:

#include "picow_http/http.h"
 
#define SHORT_BODY "Very short response body"
 
if (http_resp_send_body(http, SHORT_BODY, STRLEN_LTRL(SHORT_BODY), true)
    != ERR_OK) {
        // Error handling
}

Parameters

[in]

s

MUST be a literal string

Returns

length of s

Function Documentation

format_decimal()

err_t format_decimal	(	char *	s,
		size_t *	len,
		int32_t	n
	)

Format n as an ASCII decimal number in the buffer s. This is usually faster than a call such as sprintf(s, "%d", n).

Attention

The resulting string is not nul-terminated; but a terminating nul character may be added as shown in the example.

Example:

#include "picow_http/http.h"
 
#define MAX_DIGITS (4)
char buf[MAX_DIGITS];
size_t buflen = sizeof(buf);
 
if (format_decimal(buf, &buflen, 100) != ERR_OK) {
        // Error handling
}
 
// Append a terminating nul, if there is space for it after formatting.
if (buflen < MAX_DIGITS)
        buf[len] = '\0';

Parameters

[out]	s	buffer in which the number is formatted
[in,out]	len	before the call, *len is the size of s after successful return, *len is the length of the string formatted in s
[in]	n	the number to be formatted

Returns

ERR_OK on success
ERR_ARG if either of s or len is NULL
ERR_BUF if s is too small for the formatted number

See also

lwIP err_t

format_hex()

err_t format_hex	(	char *	s,
		size_t *	len,
		uint32_t	n,
		bool	upper
	)

Format n as an ASCII hexadecimal number in the buffer s. This is usually faster than a call such as snprintf(s, *len, "%x", n).

If upper is true, the digits A-F are formatted in upper case; otherwise they are rendered as a-f.

The string is not formatted with leading zeroes, nor with a prefix such as 0x.

Attention

The resulting string is not nul-terminated; but a terminating nul character may be added as shown in the example.

Example:

#include "picow_http/http.h"
 
#define MAX_LEN (9)
char buf[MAX_LEN];
size_t buflen = sizeof(buf);
 
// Rendered as "ca771e".
if (format_hex(buf, &buflen, 13268766, false) != ERR_OK) {
        // Error handling
}
 
// Append a terminating nul, if there is space for it after formatting.
if (buflen < MAX_DIGITS)
        buf[len] = '\0';

Parameters

[out]	s	buffer in which the number is formatted
[in,out]	len	before the call, *len is the size of s after successful return, *len is the length of the string formatted in s
[in]	n	the number to be formatted
[in]	upper	if true, hex digits are formatted as upper case, otherwise as lower case

Returns

ERR_OK on success
ERR_ARG if either of s or len is NULL
ERR_BUF if s is too small for the formatted number

See also

lwIP err_t

hex_decode()

err_t hex_decode	(	const char *const	buf,
		ssize_t	len,
		uint64_t *	n
	)

Set *n to the value of the ASCII hexadecimal string in buf.

The decoding stops at any nul byte (value 0) in the buffer. If len >= 0, then at most len bytes are decoded. If len < 0, then the input buffer must contain a nul byte.

The input string must contain only hex digits. A prefix such as 0x is invalid.

Example:

#include "picow_http/http.h"
 
uint64_t n;
 
if (hex_decode("ca771e", -1, &n) != ERR_OK) {
        // Error handling ...
}
// n now has the value 13268766.

Parameters

[in]	buf	the string to be decoded
[in]	len	if >= 0, decode at most len bytes in buf otherwise decode up to the first nul byte
[out]	n	on success, *n is the decoded numeric value

Returns

ERR_OK on success
ERR_ARG if either of buf or n is NULL, or if the result would be too large for uint64_t
ERR_VAL if any character in buf is not a hex digit

See also

lwIP err_t

Variable Documentation

month_name

const char* month_name[]

static

Initial value:

= {
    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
}

Month name abbreviations as used in the preferred HTTP date format.

"Jan" (for January) is at index 0; so the indices correspond to the numbering of the tm_mon member of struct tm from C's time.h.

Subtract 1 from the month field of the Pico SDK's datetime_t to get the index for this array – January is 1 in datetime_t's month.

wday_name

const char* wday_name[]

static

Initial value:

= {
    "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat",
}

Weekday name abbreviations as used in the preferred HTTP date format.

"Sun" (for Sunday) is at index 0; so the indices correspond to the numbering of the wday field of the Pico SDK's datetime_t, and of the tm_wday member of struct tm from C's time.h.