toURL

Syntax

string = stringclassobject.toURL([SpacePlus])

Description

Returns the contents of the StringClass instance as an RFC 3986 percent-encoded URL component, suitable for use as a query-string value, a path segment, or any other context where reserved or non-ASCII characters must be escaped before transmission.

Prior to encoding, the buffer is converted to UTF-8 by an internal call to toUTF8, after which each byte that is not in the unreserved character set defined by RFC 3986 — that is, A–Z, a–z, 0–9, hyphen (-), underscore (_), period (.) and tilde (~) — is replaced by a percent sign followed by the two-digit upper-case hexadecimal representation of that byte. This UTF-8 percent-encoding is the encoding that all modern web browsers, REST APIs, and HTTP servers expect when they receive a URL containing characters outside the basic ASCII range, including accented Latin characters such as é, è, ü, ñ, ç and the euro sign (€), and is consistent with the encoding produced by the JavaScript encodeURIComponent function.

The contents of the StringClass instance itself are not modified; toURL only returns the encoded result. Plain ASCII strings without reserved characters are returned unchanged. For the inverse operation — decoding a percent-encoded value received from an external source — use the Web2Text function in CCL to convert a URL parameter back into readable text. The legacy URLEncode function is retained for backwards compatibility and produces percent-encoding without the intermediate UTF-8 conversion step; for new development that interacts with modern web platforms, the toURL method of the StringClass should be preferred. The Text2Web function provides equivalent behaviour to URLEncode for the forward direction in CCL contexts.

Parameter	Description
SpacePlus	Optional. If True, converts the '+' to an hexcode and replaces spaces to '+'. Default value is True.

See Also

fromUTF8, toUTF8, isUTF8, toString, URLEncode, Text2Web, Web2Text.

Example

Sub Main
    Dim oS As StringClass
    Dim sParam$
    Dim sURL$
 
    Set oS = New StringClass
    oS.Value = "Café Brûlé"
 
    sParam$ = oS.toURL
    sURL$ = "https://api.example.com/search?q=" & sParam$
 
    Debug.Print "Encoded parameter: "; sParam$
    Debug.Print "Complete URL:      "; sURL$
 
    Set oS = Nothing
End Sub