README.md in accept_headers-0.0.5 vs README.md in accept_headers-0.0.6

@@ -13,11 +13,11 @@
     and [Accept-Language][rfc-sec14-4] HTTP request headers
   * `Accept-Charset` is not supported because it's [obsolete](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Charset.3A_header)
   * Parser tested against all IANA registered [media types][iana-media-types]
   * A comprehensive [spec suite][spec] that covers many edge cases
 
-This library is optimistic when parsing headers. If a specific media type, encoding, charset, or language can't be parsed, is in an invalid format, or contains invalid characters, it will skip that specific entry when constructing the sorted list. If a `q` value can't be read or is in the wrong format (more than 3 decimal places), it will default it to `0.001` so it still has a chance to match. Lack of an explicit `q` value of course defaults to 1.
+This library is optimistic when parsing headers. If a specific media type, encoding, or language can't be parsed, is in an invalid format, or contains invalid characters, it will skip that specific entry when constructing the sorted list. If a `q` value can't be read or is in the wrong format (more than 3 decimal places), it will default it to `0.001` so it still has a chance to match. Lack of an explicit `q` value of course defaults to 1.
 
 [rfc]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
 [rfc-sec14]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
 [rfc-sec14-1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
 [rfc-sec14-3]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
@@ -61,29 +61,35 @@
   AcceptHeaders::MediaType.new('text', 'html', q: 0.4, params: { 'level' => '2' }),
   AcceptHeaders::MediaType.new('text', '*', q: 0.3)
 ]
 ```
 
-`#negotiate` takes a string of media types supported (by your API or route/controller) and returns the best match as a `MediaType`. This will first check the available list for any matching media types with a `q` of 0 and return `nil` if there is a match. Then it'll look to the highest `q` values and look for matches in descending `q` value order and return the first match (accounting for wildcards). Finally, if there are no matches, it returns `nil`.
+`#negotiate` takes an array of media range strings supported (by your API or route/controller) and returns a hash where the `supported` key contains the array element matched and the `matched` key containing a `MediaType` that was matched in the `Negotiator`s internal list.
 
+This will first check the available list for any matching media types with a `q` of 0 and skip any matches. It does this because the RFC specifies that if the `q` value is 0, then content with this parameter is `not acceptable`. Then it'll look to the highest `q` values and look for matches in descending `q` value order and return the first match (accounting for wildcards). Finally, if there are no matches, it returns `nil`.
+
 ```ruby
-media_types.negotiate('text/html')
+# The same media_types variable as above
+media_types.negotiate(['text/html', 'text/plain'])
 
 # Returns:
 
-AcceptHeaders::MediaType.new('text', 'html', params: { 'level' => '1' })
+{
+  supported: 'text/html',
+  matched:    AcceptHeaders::MediaType.new('text', 'html', q: 1, params: { 'level' => '1' })
+}
 ```
 
 `#accept?`:
 
 ```ruby
 media_types.accept?('text/html') # true
 ```
 
 ### Accept-Encoding
 
-`AcceptHeader::Charset::Encoding`:
+`AcceptHeader::Encoding::Encoding`:
 
 ```ruby
 encodings = AcceptHeaders::Encoding::Negotiator.new("deflate; q=0.5, gzip, compress; q=0.8, identity")
 
 encodings.list
@@ -98,15 +104,18 @@
 ```
 
 `#negotiate`:
 
 ```ruby
-encodings.negotiate('gzip')
+encodings.negotiate(['gzip', 'compress'])
 
 # Returns:
 
-AcceptHeaders::Encoding.new('gzip')
+{
+  supported: 'gzip',
+  matched:    AcceptHeaders::Encoding.new('gzip'))
+}
 ```
 
 `#accept?`:
 
 ```ruby
@@ -136,14 +145,17 @@
 ```
 
 `#negotiate`:
 
 ```ruby
-languages.negotiate('en-us')
+languages.negotiate(['en-us', 'zh-Hant'])
 
 # Returns:
 
-AcceptHeaders::Language.new('en', 'us')
+{
+  supported: 'en-us',
+  matched:    AcceptHeaders::Language.new('en', 'us'))
+}
 ```
 
 `#accept?`:
 
 ```ruby