libraryDocs / percent

percent

librarysharedsource

Percent (URL/URI) encoding/decoding library.

Percent-encoding is a mechanism to encode 8-bit characters that have specific meaning in the context of URLs.

It is sometimes called URL encoding.

The encoding consists of substitution: A '%' followed by the hexadecimal representation of the ASCII value of the replace character.

Functions

`percent.decode`	Decodes the specified string from percent encoding.
`percent.encode`	Encodes the specified string to percent encoding.
`percent.validate`	Validates the specified percent string.
`percent.whitelist`	Creates a character whitelist for the given pattern.

sharednodiscardsource

function percent.decode(percent_str: string, ignore_spaces?: boolean): string

Decodes the specified string from percent encoding.

Invalid or incomplete "%" sequences are kept as is.

lua

percent.decode( "a+b%26c" ) -- "a b&c"
percent.decode( "a+b%26c", true ) -- "a+b&c"

Parameters

Name	Type	Description
`percent_str`	`string`	The string to decode.
`ignore_spaces`optional	`boolean`	If `true`, `"+"` is kept as is instead of being decoded as a space, optional.

Returns

Type	Name	Description
`string`	`raw_str`	The decoded string.

sharednodiscardsource

function percent.encode(raw_str: string, whitelist?: table<integer, boolean>, ignore_spaces?: boolean): string

Encodes the specified string to percent encoding.

Bytes not in the whitelist are encoded as "%XX" (upper-case hex), spaces are encoded as "+" unless ignore_spaces is true.

lua

percent.encode( "a b&c" ) -- "a+b%26c"
percent.encode( "a b&c", nil, true ) -- "a%20b%26c"

Parameters

Name	Type	Description
`raw_str`	`string`	The string to encode.
`whitelist`optional	`table<integer, boolean>`	The character whitelist, bytes in it are left as is, optional.
`ignore_spaces`optional	`boolean`	If `true`, spaces are encoded as `"%20"` instead of `"+"`, optional.

Returns

Type	Name	Description
`string`	`percent_str`	The encoded string.

sharednodiscardsource

function percent.validate(percent_str: string, whitelist?: table<integer, boolean>, ignore_spaces?: boolean): boolean, nil | string

Validates the specified percent string.

A valid string contains only whitelisted bytes, complete "%XX" sequences and, unless ignore_spaces is true, "+".

Parameters

Name	Type	Description
`percent_str`	`string`	The percent string to validate.
`whitelist`optional	`table<integer, boolean>`	The character whitelist, optional.
`ignore_spaces`optional	`boolean`	If `true`, `"+"` is not allowed unless whitelisted, optional.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if the percent string is valid, otherwise `false`.
`nil \| string`	`err_msg`	The error message.

sharednodiscardsource

function percent.whitelist(pattern_str: string, base?: table): table<integer, boolean>

Creates a character whitelist for the given pattern.

Parameters

Name	Type	Description
`pattern_str`	`string`	The pattern.
`base`optional	`table`	The base table, optional.

Returns

Type	Name	Description
`table<integer, boolean>`	`whitelist`	The character whitelist.