URL functions

26 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

url_cut_fragment

Removes the hash delimiter and fragment from a complete URL string.

url_cut_fragment(url:string) -> string

Preserves the scheme, authority, path and query while cutting at the fragment delimiter. A URL without a fragment is returned unchanged, including an otherwise empty input. NULL returns NULL and nonstring input raises TYPE_MISMATCH; percent-encoded hash bytes are not treated as delimiters.

Example

url_cut_fragment('https://example.com/products?a=1#details')
-- → 'https://example.com/products?a=1'

url_cut_parameter

Deletes every query field whose raw name exactly matches the supplied key.

url_cut_parameter(url:string,name:string) -> string

Removes all occurrences of the named query parameter and repairs the remaining query separators. A missing name leaves the URL unchanged, with path and fragment preserved; comparison does not implicitly decode escapes. NULL arguments yield NULL, and arguments outside the string overload raise TYPE_MISMATCH.

Example

url_cut_parameter('https://example.com/products?a=1&b=2&a=3', 'a')
-- → 'https://example.com/products?b=2'

url_cut_query_string

Deletes URL query parameters while keeping any fragment suffix.

url_cut_query_string(url:string) -> string

Removes the question-mark delimiter and query content, preserving the rest of the URL including its fragment. Input without a query remains unchanged, and NULL remains NULL. No parameter decoding is performed; invalid argument types raise TYPE_MISMATCH rather than triggering a resource request.

Example

url_cut_query_string('https://example.com/products?a=1#details')
-- → 'https://example.com/products#details'

url_cut_query_string_and_fragment

Keeps only a URL’s portion before its query or fragment suffix.

url_cut_query_string_and_fragment(url:string) -> string

Removes query content and fragment content together, including their delimiters. If neither suffix exists, the original string is returned; NULL input yields NULL. Escaped delimiter characters remain part of the retained data, and a nonstring argument raises TYPE_MISMATCH.

Example

url_cut_query_string_and_fragment('https://example.com/products?a=1#details')
-- → 'https://example.com/products'

url_cut_to_first_significant_subdomain

Returns the registrable domain and public suffix from a deeper URL host.

url_cut_to_first_significant_subdomain(url:string) -> string

Cuts away labels preceding the significant domain while retaining that label and its recognized public suffix. The suffix table is version-pinned, and a host without a usable domain yields empty text. SQL NULL remains NULL; nonstring input raises TYPE_MISMATCH, with no network lookup involved.

Example

url_cut_to_first_significant_subdomain('https://shop.example.co.uk/products')
-- → 'example.co.uk'

url_cut_www

Rewrites a URL after dropping a leading www authority label.

url_cut_www(url:string) -> string

Removes the initial www label from the host while preserving scheme, port, path, query and fragment. Hosts without that label are left as supplied, and NULL remains NULL. The operation is a pure string transformation; nonstring values raise TYPE_MISMATCH.

Example

url_cut_www('https://www.example.com/products')
-- → 'https://example.com/products'

url_decode_component

Restores percent-escaped URL bytes while preserving literal plus characters.

url_decode_component(text:string) -> string

Decodes percent triplets within one component and returns the resulting UTF-8 text. Unlike form decoding, a plus sign is retained as a plus. NULL produces NULL, and malformed escapes or invalid decoded text raise INVALID_ENCODING instead of being silently replaced.

Example

url_decode_component('red%20blue+')
-- → 'red blue+'

url_decode_form_component

Decodes form escapes and translates plus separators back to spaces.

url_decode_form_component(text:string) -> string

First interprets literal plus characters as spaces and decodes valid percent triplets into text bytes. An escaped %2B remains a literal plus, preserving the distinction from an unescaped separator. NULL propagates; malformed escapes or invalid UTF-8 output raise INVALID_ENCODING.

Example

url_decode_form_component('red+blue%2B')
-- → 'red blue+'

url_domain

Extracts a URL’s host name while excluding scheme, credentials and port.

url_domain(url:string) -> string

Returns the textual authority host without performing DNS resolution or percent-decoding unrelated components. A missing host produces an empty string and a NULL URL produces NULL. Input outside the string overload raises TYPE_MISMATCH; an explicit port is not part of the returned domain.

Example

url_domain('https://shop.example.com:8443/products')
-- → 'shop.example.com'

url_domain_without_www

Obtains a host name after removing its leading www label.

url_domain_without_www(url:string) -> string

Extracts the authority host and removes a leading www label when present, leaving other subdomains intact. A URL without a host returns empty text; SQL NULL remains NULL. This is lexical decomposition rather than a DNS lookup, and nonstring input raises TYPE_MISMATCH.

Example

url_domain_without_www('https://www.example.com/products')
-- → 'example.com'

url_encode_component

Escapes a UTF-8 component for placement inside a URL.

url_encode_component(text:string) -> string

Percent-encodes bytes requiring escaping while leaving unreserved characters literal. A space becomes %20 and a literal plus is escaped rather than treated as a form separator. NULL returns NULL, incompatible input types raise TYPE_MISMATCH and expansion beyond the value budget raises RESOURCE_LIMIT.

Example

url_encode_component('red blue')
-- → 'red%20blue'

url_encode_form_component

Prepares form text with plus signs for spaces and percent escapes for reserved bytes.

url_encode_form_component(text:string) -> string

Encodes a single application-form component from its UTF-8 bytes. Spaces become plus signs, while literal plus characters become %2B so that decoding is unambiguous. NULL remains NULL; TYPE_MISMATCH rejects incompatible values and RESOURCE_LIMIT bounds the expanded string.

Example

url_encode_form_component('red blue+')
-- → 'red+blue%2B'

url_extract_parameter

Returns the first raw query value associated with a requested URL field.

url_extract_parameter(url:string,name:string) -> string

Scans parameters in source order and chooses the first exactly matching name. An absent name or an explicitly empty value yields an empty string; decoding percent escapes requires a separate operation. SQL NULL propagates and nonstring arguments raise TYPE_MISMATCH.

Example

url_extract_parameter('https://example.com/products?id=7&id=9', 'id')
-- → '7'

url_extract_parameter_names

Lists query field names in their original order, retaining repetitions.

url_extract_parameter_names(url:string) -> array(string)

Returns an array of raw names from the query component, excluding the fragment. Names are not deduplicated or percent-decoded, and a URL without parameters returns an empty array. NULL gives NULL; incompatible arguments raise TYPE_MISMATCH and excessive expansion raises RESOURCE_LIMIT.

Example

url_extract_parameter_names('https://example.com/products?a=1&b=2&a=3')
-- → ['a', 'b', 'a']

url_extract_parameters

Splits the raw query into ordered key-and-value segments.

url_extract_parameters(url:string) -> array(string)

Produces one array element per query segment, preserving the equals sign and any percent escapes. The fragment is excluded, duplicate fields remain distinct, and an absent query produces an empty array. NULL propagates; TYPE_MISMATCH rejects nonstrings and RESOURCE_LIMIT bounds the materialized output.

Example

url_extract_parameters('https://example.com/products?a=1&b=2#details')
-- → ['a=1', 'b=2']

url_first_significant_subdomain

Finds the registrable host label immediately before a recognized public suffix.

url_first_significant_subdomain(url:string) -> string

Uses the version-pinned public-suffix rules to select the first significant domain label. Additional host labels to its left are ignored, and a missing eligible domain produces empty text. NULL propagates and nonstring input raises TYPE_MISMATCH; results do not depend on live DNS or network-fetched suffix data.

Example

url_first_significant_subdomain('https://shop.example.co.uk/products')
-- → 'example'

url_fragment

Retrieves the text following a URL’s hash delimiter.

url_fragment(url:string) -> string

Returns fragment content without the leading hash character and preserves any percent escapes. When the fragment is absent or empty, the result is an empty string rather than NULL. SQL NULL propagates; wrong argument types raise TYPE_MISMATCH, and no client-side navigation occurs.

Example

url_fragment('https://example.com/products#details')
-- → 'details'

url_hierarchy

Builds successive absolute resource prefixes from a URL’s ordered path segments.

url_hierarchy(url:string) -> array(string)

Returns the authority-root URL followed by progressively longer path prefixes in source order. It does not fetch resources or resolve a hierarchy through the network, and NULL input returns NULL. Query and fragment are not path levels; incompatible input raises TYPE_MISMATCH and oversized output raises RESOURCE_LIMIT.

Example

url_hierarchy('https://example.com/products/7')
-- → ['https://example.com/', 'https://example.com/products/',
--   'https://example.com/products/7']

url_path

Isolates the slash-led resource path without query parameters or fragment text.

url_path(url:string) -> string

Returns the path component exactly as represented, retaining percent escapes for explicit later decoding. Missing path content produces an empty string and SQL NULL produces NULL. The function does not normalize dot segments or request the resource; nonstring input raises TYPE_MISMATCH.

Example

url_path('https://example.com/products/7?view=short#details')
-- → '/products/7'

url_path_full

Returns the resource suffix including its path, query and fragment.

url_path_full(url:string) -> string

Removes the scheme and authority while preserving the remaining path-oriented URL suffix with its delimiters. If no such suffix exists the result is empty; NULL remains NULL. It performs no percent decoding or navigation, and a nonstring argument raises TYPE_MISMATCH.

Example

url_path_full('https://example.com/products?id=7#details')
-- → '/products?id=7#details'

url_path_hierarchy

Expands a resource path into cumulative prefixes without scheme or authority.

url_path_hierarchy(url:string) -> array(string)

Lists successive slash-led path levels while excluding URL authority, query and fragment components. The output preserves source order and percent escapes, and a missing path produces an empty array. NULL returns NULL; TYPE_MISMATCH rejects other logical types and RESOURCE_LIMIT bounds prefix expansion.

Example

url_path_hierarchy('https://example.com/products/7')
-- → ['/products/', '/products/7']

url_port

Reads an explicit numeric URL port, with zero or a supplied default when absent.

url_port(url:string) -> uint16
url_port(url:string,default_port:uint16) -> uint16

Returns the authority port as uint16 and uses the optional default only when no port is specified. Without a default, an absent port gives zero rather than an inferred protocol port. NULL propagates and malformed or out-of-range explicit port text raises INVALID_ARGUMENT.

Example

url_port('https://example.com/products', 443)
-- → 443

url_protocol

Returns the scheme label preceding a URL’s authority or path.

url_protocol(url:string) -> string

Extracts the scheme without its colon or slash delimiters. A URL with no scheme yields an empty string, while a NULL argument yields NULL. It does not infer https from a hostname or contact the resource; incompatible argument types raise TYPE_MISMATCH.

Example

url_protocol('https://example.com/products')
-- → 'https'

url_query_string

Extracts raw URL parameter text between the question mark and fragment delimiter.

url_query_string(url:string) -> string

Returns the complete query component without its leading question mark or a following fragment. Names and values remain escaped and are not interpreted as a map. An absent query yields empty text, SQL NULL yields NULL, and incompatible argument types raise TYPE_MISMATCH.

Example

url_query_string('https://example.com/products?a=1&b=2#details')
-- → 'a=1&b=2'

url_query_string_and_fragment

Reads a URL’s query suffix together with any following fragment.

url_query_string_and_fragment(url:string) -> string

Starts after the query delimiter and preserves the subsequent hash and fragment when present. With no query component the query-oriented extraction returns empty text; a NULL input stays NULL. Percent escapes are left untouched, and nonstring arguments raise TYPE_MISMATCH.

Example

url_query_string_and_fragment('https://example.com/products?a=1#details')
-- → 'a=1#details'

url_top_level_domain

Identifies the final domain label in a URL host.

url_top_level_domain(url:string) -> string

Extracts the rightmost host label as the top-level domain without including its preceding dot. A missing domain yields empty text, and NULL produces NULL. It does not return an entire multi-label public suffix or perform DNS validation; incompatible input types raise TYPE_MISMATCH.

Example

url_top_level_domain('https://shop.example.com/products')
-- → 'com'