classDocs / URL / SearchParams

URL.SearchParams

classsharedsource

Object → URL.SearchParams

A list of query parameters, stored as { name, value } pairs in order.

Names may repeat. Pairs are parsed as application/x-www-form-urlencoded: empty segments are skipped, a pair without = gets an empty value.

Serializing always writes name=value and encodes spaces as +, so "flag" becomes "flag=".

When taken from url.searchParams, every change is written back to the URL.

tostring( params ) returns the serialized query without the leading "?", #params is the number of pairs.

lua

local url = URL( "https://example.com/?a=1&b=2" )
local params = url.searchParams

params:get( "a" )      -- "1"
params:append( "c", "x y" )
url.search             -- "?a=1&b=2&c=x+y"

Constructor

URL.SearchParams(init: string | { [ 1 ]: string, [ 2 ]: string | nil }[] | nil, url: URL | nil): URL.SearchParams

Fields

Name	Type	Description
`url`	`URL \| nil`	The URL this list writes changes back to, `nil` for standalone lists.
`[ integer ]`	`{ [ 1 ]: string, [ 2 ]: string \| nil }`	The `{ name, value }` pairs, in order.

Operators

Operator	Operand	Result
`len`		`integer`

Methods

`append`	Appends a name-value pair to the end of the list.
`delete`	Removes every pair with the given name.
`get`	Returns the value of the first pair with the given name.
`getAll`	Returns the values of every pair with the given name, in order.
`has`	Checks if there is a pair with the given name.
`iterator`	Returns an iterator over the name-value pairs, in order.
`keys`	Returns an iterator over the names, a name that repeats is returned every time.
`set`	Sets the value of the first pair with the given name and removes the other pairs with that name.
`sort`	Sorts the pairs by name in byte order (stable), pairs with the same name keep their relative order.
`values`	Returns an iterator over the values, a nil value gives "".

#SearchParams:append

sharedsource

function URL.SearchParams:append(name: string, value?: string)

Appends a name-value pair to the end of the list.

Parameters

Name	Type	Description
`name`	`string`	The name of the parameter.
`value`optional	`string`	The value of the parameter, `nil` is serialized the same as `""`.

#SearchParams:delete

sharedsource

function URL.SearchParams:delete(name: string, value?: string)

Removes every pair with the given name.

If value is given, only pairs with both the given name and value are removed.

Parameters

Name	Type	Description
`name`	`string`	The name of the parameters to remove.
`value`optional	`string`	The value the removed pairs must have.

#SearchParams:get

sharednodiscardsource

function URL.SearchParams:get(name: string): string | nil

Returns the value of the first pair with the given name.

Parameters

Name	Type	Description
`name`	`string`	The name of the parameter.

Returns

Type	Name	Description
`string \| nil`	`value`	The value, `nil` if there is no such pair.

#SearchParams:getAll

sharednodiscardsource

function URL.SearchParams:getAll(name: string): string[]

Returns the values of every pair with the given name, in order.

lua

URL.SearchParams( "a=1&b=2&a=3" ):getAll( "a" ) -- { "1", "3" }

Parameters

Name	Type	Description
`name`	`string`	The name of the parameters.

Returns

Type	Name	Description
`string[]`	`values`	The values, empty if there are no such pairs.

#SearchParams:has

sharednodiscardsource

function URL.SearchParams:has(name: string, value?: string): boolean

Checks if there is a pair with the given name.

If value is given, the pair must also have the given value.

Parameters

Name	Type	Description
`name`	`string`	The name of the parameter.
`value`optional	`string`	The value the pair must have.

Returns

Type	Name	Description
`boolean`	`exists`	`true` if such a pair exists, otherwise `false`.

#SearchParams:iterator

sharednodiscardsource

function URL.SearchParams:iterator(): (fun(): string?), string?

Returns an iterator over the name-value pairs, in order.

lua

for name, value in url.searchParams:iterator() do
    print( name, value )
end

Returns

Type	Name	Description
`fun(): string?`
`string?`	`iterator`	The iterator function, returns `nil` when the list ends.

#SearchParams:keys

sharednodiscardsource

function URL.SearchParams:keys(): fun(): string?

Returns an iterator over the names, a name that repeats is returned every time.

Returns

Type	Name	Description
`fun(): string?`	`iterator`	The iterator function, returns `nil` when the list ends.

#SearchParams:set

sharedsource

function URL.SearchParams:set(name: string, value?: string)

Sets the value of the first pair with the given name and removes the other pairs with that name.

Appends a new pair if there is no pair with the given name.

lua

local params = URL.SearchParams( "a=1&b=2&a=3" )
params:set( "a", "9" )
tostring( params ) -- "a=9&b=2"

Parameters

Name	Type	Description
`name`	`string`	The name of the parameter.
`value`optional	`string`	The new value, `nil` is serialized the same as `""`.

#SearchParams:sort

sharedsource

function URL.SearchParams:sort()

Sorts the pairs by name in byte order (stable), pairs with the same name keep their relative order.

lua

local params = URL.SearchParams( "b=1&a=2&b=0" )
params:sort()
tostring( params ) -- "a=2&b=1&b=0"

#SearchParams:values

sharednodiscardsource

function URL.SearchParams:values(): fun(): string?

Returns an iterator over the values, a nil value gives "".

Returns

Type	Name	Description
`fun(): string?`	`iterator`	The iterator function, returns `nil` when the list ends.