Base64, hex and URLs

Bytes that are not text — a token, a hash, a key — have to be spelled in characters before they can go into JSON, an e-mail or a URL. std/codec has the usual spellings, and percent-encoding for text inside URLs.

#import "std/codec"

'' Base64 and hex carry bytes through places that only take text.
dim token as ustring = "user:secret"
print "base64: "; codec.Base64Encode( token )
print "hex:    "; codec.HexEncode( token )
print "back:   "; codec.Base64DecodeText( "dXNlcjpzZWNyZXQ=" ).Value( )

'' Percent-encoding makes text safe inside a URL.
dim search as ustring = "rock & roll/live"
print "query:  ?q="; codec.PercentEncode( search, codec.PCT_QUERY )
print "path:   /"; codec.PercentEncode( search )

'' Decoding is strict: it says what is wrong, and where.
var bad = codec.Base64DecodeText( "dXNl!jpz" )
if bad.IsOk( ) = false then print "error:  "; bad.Failure( ).Message( )

Output

base64: dXNlcjpzZWNyZXQ=
hex:    757365723a736563726574
back:   user:secret
query:  ?q=rock+%26+roll%2Flive
path:   /rock%20%26%20roll%2Flive
error:  Base64DecodeText: invalid character at 5

x can be a ustring (encoded as its UTF-8 bytes) or a containers.Array( of ubyte ). Each encoding has a …Decode that fills an array of bytes and a …DecodeText that gives back a ustring; both return a Result.

Decoding is strict: a character outside the alphabet, missing or misplaced = padding, or whitespace is refused, and the error says where. Pass codec.DECODE_IGNORE_WHITESPACE or codec.DECODE_ALLOW_MISSING_PAD when the input is known to be loose.

PercentEncode keeps letters, digits and - . _ ~. PCT_PATH also keeps /; PCT_QUERY is what an HTML form sends, with a space as +.

Activities

1. Encode the same token with codec.B64_URL and no padding, as a JSON Web Token does, and decode it back with codec.DECODE_ALLOW_MISSING_PAD.
2. Decode "dXNlcjpzZWNyZXQ" without the option and read the error.