UrlDecodeUnicode and FormUrlDecodeUnicode (String functions)
Decode URL encoded characters to unicode (String class)
[Introduced in Sirius Mods 7.9]
UrlDecodeUnicode and FormUrlDecodeUnicode decode data that's been URL encoded or percent-encoded to a unicode string.
Syntax
%unicode = string:UrlDecodeUnicode[( [AllowUntranslatable= boolean])] Throws CharacterTranslationException
%unicode = string:FormUrlDecodeUnicode[( [AllowUntranslatable= boolean])] Throws CharacterTranslationException
Syntax terms
| %unicode | The Unicode variable that results when string is decoded. |
|---|---|
| string | The UTF-8 encoded string that contains a URL encoded representation of a unicode string. |
| boolean | Indicates whether unicode characters that cannot be translated back to EBCDIC are to be allowed. If boolean is set to False a unicode character that cannot be translated back to EBCDIC results in request cancellation. |
Exceptions
UrlDecodeUnicode and FormUrlDecodeUnicode can throw the following exception:
- CharacterTranslationException
- If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
Usage notes
- If an EBCDIC version of URL encoded data needs to be converted to unicode, the EBCDIC string must first be assigned to a unicode variable using either implicit EBCDIC to Unicode translation or doing it explicitly with EbcdicToUnicode, converted to UTF-8 using UnicodeToUtf8, and finally translated to unicode using UrlDecodeUnicode. And example below illustrates this process.
- The difference between FormUrlDecodeUnicode and UrlDecodeUnicode is thatFormUrlDecodeUnicode converts pluses (
+) to spaces while UrlDecodeUnicode expects spaces to be percent encoded as%20. UrlDecodeUnicode will throw a CharacterTranslationException exception if it encounters a plus (+). Typically form URL encoding is only used in HTML form posts when the form is posted using the x-www-form-urlencoded content type. - URL encoding is mostly used in web applications or for encoding a URI, possibly in an XML namespace declaration.
- The inverse of UrlDecodeUnicode and FormUrlDecodeUnicode are UnicodeUrlEncode and UnicodeUrlEncode, respectively.
Examples
URL decoding an EBCDIC string
The following example URL decodes a URL encoded EBCDIC string to unicode:
b %ebcdic is longstring %unicode is unicode %ebcdic = 'I%20like%20apple%20%CF%80%20and%20eat%20it%204%20%C3%97%20a%20day.' %unicode = %ebcdic:ebcdicToUnicode:unicodeToUtf8:urlDecodeUnicode printText {~} = {%unicode} end
and outputs
%unicode = I like apple π and eat it 4 × a day.