New upstream version 1.31.0~beta.4+dfsg1

[rustc.git] / src / vendor / serde_json / README.md

diff --git a/src/vendor/serde_json/README.md b/src/vendor/serde_json/README.md
index 6828915a6b6023c2a391a7ee66f223a44d007ecb..6d445108d5b8b11fcfdbf6b0293d955584b12d06 100644 (file)
--- a/src/vendor/serde_json/README.md
+++ b/src/vendor/serde_json/README.md
@@ -1,9 +1,11 @@
-# Serde JSON   [![Build Status]][travis] [![Latest Version]][crates.io]
+# Serde JSON   [![Build Status]][travis] [![Latest Version]][crates.io] [![Rustc Version 1.15+]][rustc]
 
 [Build Status]: https://api.travis-ci.org/serde-rs/json.svg?branch=master
 [travis]: https://travis-ci.org/serde-rs/json
 [Latest Version]: https://img.shields.io/crates/v/serde_json.svg
 [crates.io]: https://crates.io/crates/serde\_json
+[Rustc Version 1.15+]: https://img.shields.io/badge/rustc-1.15+-lightgray.svg
+[rustc]: https://blog.rust-lang.org/2017/02/02/Rust-1.15.html
 
 **Serde is a framework for *ser*ializing and *de*serializing Rust data structures efficiently and generically.**
 
@@ -109,6 +111,23 @@ fn untyped_example() -> Result<(), Error> {
 }
 ```
 
+The result of square bracket indexing like `v["name"]` is a borrow of the data
+at that index, so the type is `&Value`. A JSON map can be indexed with string
+keys, while a JSON array can be indexed with integer keys. If the type of the
+data is not right for the type with which it is being indexed, or if a map does
+not contain the key being indexed, or if the index into a vector is out of
+bounds, the returned element is `Value::Null`.
+
+When a `Value` is printed, it is printed as a JSON string. So in the code above,
+the output looks like `Please call "John Doe" at the number "+44 1234567"`. The
+quotation marks appear because `v["name"]` is a `&Value` containing a JSON
+string and its JSON representation is `"John Doe"`. Printing as a plain string
+without quotation marks involves converting from a JSON string to a Rust string
+with [`as_str()`] or avoiding the use of `Value` as described in the following
+section.
+
+[`as_str()`]: https://docs.serde.rs/serde_json/enum.Value.html#method.as_str
+
 The `Value` representation is sufficient for very basic tasks but can be tedious
 to work with for anything more significant. Error handling is verbose to
 implement correctly, for example imagine trying to detect the presence of
@@ -312,6 +331,13 @@ good resource with generally faster response time but less specific knowledge
 about Serde. If IRC is not your thing, we are happy to respond to [GitHub
 issues](https://github.com/serde-rs/json/issues/new) as well.
 
+## No-std support
+
+This crate currently requires the Rust standard library. For JSON support in
+Serde without a standard library, please see the [`serde-json-core`] crate.
+
+[`serde-json-core`]: https://japaric.github.io/serde-json-core/serde_json_core/
+
 ## License
 
 Serde JSON is licensed under either of