Skip to content

Commit ce379e6

Browse files
[DOC] Enhanced RDoc for URI.decode_www_form (#53)
1 parent be80470 commit ce379e6

File tree

1 file changed

+31
-14
lines changed

1 file changed

+31
-14
lines changed

lib/uri/common.rb

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -422,8 +422,8 @@ def self._decode_uri_component(regexp, str, enc)
422422
# The returned string is formed using method URI.encode_www_form_component,
423423
# which converts certain characters:
424424
#
425-
# URI.encode_www_form('f#o': '/', 'b-r': '$')
426-
# # => "f%23o=%2F&b-r=%24"
425+
# URI.encode_www_form('f#o': '/', 'b-r': '$', 'b z': '@')
426+
# # => "f%23o=%2F&b-r=%24&b+z=%40"
427427
#
428428
# When +enum+ is Array-like, each element +ele+ is converted to a field:
429429
#
@@ -518,22 +518,39 @@ def self.encode_www_form(enum, enc=nil)
518518
end.join('&')
519519
end
520520

521-
# Decodes URL-encoded form data from given +str+.
521+
# Returns name/value pairs derived from the given string +str+,
522+
# which must be an ASCII string.
522523
#
523-
# This decodes application/x-www-form-urlencoded data
524-
# and returns an array of key-value arrays.
524+
# The method may be used to decode the body of Net::HTTPResponse object +res+
525+
# for which <tt>res['Content-Type']</tt> is <tt>'application/x-www-form-urlencoded'</tt>.
525526
#
526-
# This refers http://url.spec.whatwg.org/#concept-urlencoded-parser,
527-
# so this supports only &-separator, and doesn't support ;-separator.
527+
# The returned data is an array of 2-element subarrays;
528+
# each subarray is a name/value pair (both are strings).
529+
# Each returned string has encoding +enc+,
530+
# and has had invalid characters removed via
531+
# {String#scrub}[https://docs.ruby-lang.org/en/master/String.html#method-i-scrub].
528532
#
529-
# ary = URI.decode_www_form("a=1&a=2&b=3")
530-
# ary #=> [['a', '1'], ['a', '2'], ['b', '3']]
531-
# ary.assoc('a').last #=> '1'
532-
# ary.assoc('b').last #=> '3'
533-
# ary.rassoc('a').last #=> '2'
534-
# Hash[ary] #=> {"a"=>"2", "b"=>"3"}
533+
# A simple example:
534+
#
535+
# URI.decode_www_form('foo=0&bar=1&baz')
536+
# # => [["foo", "0"], ["bar", "1"], ["baz", ""]]
537+
#
538+
# The returned strings have certain conversions,
539+
# similar to those performed in URI.decode_www_form_component:
540+
#
541+
# URI.decode_www_form('f%23o=%2F&b-r=%24&b+z=%40')
542+
# # => [["f#o", "/"], ["b-r", "$"], ["b z", "@"]]
543+
#
544+
# The given string may contain consecutive separators:
545+
#
546+
# URI.decode_www_form('foo=0&&bar=1&&baz=2')
547+
# # => [["foo", "0"], ["", ""], ["bar", "1"], ["", ""], ["baz", "2"]]
548+
#
549+
# A different separator may be specified:
550+
#
551+
# URI.decode_www_form('foo=0--bar=1--baz', separator: '--')
552+
# # => [["foo", "0"], ["bar", "1"], ["baz", ""]]
535553
#
536-
# See URI.decode_www_form_component, URI.encode_www_form.
537554
def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)
538555
raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only?
539556
ary = []

0 commit comments

Comments
 (0)