fluencelabs/aquavm
1
0
Fork 0
mirror of https://github.com/fluencelabs/aquavm synced 2025-04-25 07:12:16 +00:00
Code Issues Projects Releases Wiki Activity

Reconsider docstrings

Browse Source
This commit is contained in:
Ivan Boldyrev 2024-02-05 18:47:25 +01:00
parent d1c6dd50bd
commit 3da2da1046
3 changed files with 107 additions and 557 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
crates/air-lib/interpreter-value/src/value/from.rs
View File

@ -46,16 +46,16 @@ from_integer! {
} }
impl From<f32> for JValue { impl From<f32> for JValue {
/// Convert 32-bit floating point number to `Value::Number`, or /// Convert 32-bit floating point number to `JValue::Number`, or
/// `Value::Null` if infinite or NaN. /// `JValue::Null` if infinite or NaN.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let f: f32 = 13.37; /// let f: f32 = 13.37;
/// let x: Value = f.into(); /// let x: JValue = f.into();
/// ``` /// ```
fn from(f: f32) -> Self { fn from(f: f32) -> Self {
Number::from_f64(f as _).map_or(JValue::Null, JValue::Number) Number::from_f64(f as _).map_or(JValue::Null, JValue::Number)
@ -63,16 +63,16 @@ impl From<f32> for JValue {
} }
impl From<f64> for JValue { impl From<f64> for JValue {
/// Convert 64-bit floating point number to `Value::Number`, or /// Convert 64-bit floating point number to `JValue::Number`, or
/// `Value::Null` if infinite or NaN. /// `JValue::Null` if infinite or NaN.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let f: f64 = 13.37; /// let f: f64 = 13.37;
/// let x: Value = f.into(); /// let x: JValue = f.into();
/// ``` /// ```
fn from(f: f64) -> Self { fn from(f: f64) -> Self {
Number::from_f64(f).map_or(JValue::Null, JValue::Number) Number::from_f64(f).map_or(JValue::Null, JValue::Number)
@ -80,15 +80,15 @@ impl From<f64> for JValue {
} }
impl From<bool> for JValue { impl From<bool> for JValue {
/// Convert boolean to `Value::Bool`. /// Convert boolean to `JValue::Bool`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let b = false; /// let b = false;
/// let x: Value = b.into(); /// let x: JValue = b.into();
/// ``` /// ```
fn from(f: bool) -> Self { fn from(f: bool) -> Self {
JValue::Bool(f) JValue::Bool(f)
@ -96,15 +96,15 @@ impl From<bool> for JValue {
} }
impl From<String> for JValue { impl From<String> for JValue {
/// Convert `String` to `Value::String`. /// Convert `String` to `JValue::String`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let s: String = "lorem".to_string(); /// let s: String = "lorem".to_string();
/// let x: Value = s.into(); /// let x: JValue = s.into();
/// ``` /// ```
fn from(f: String) -> Self { fn from(f: String) -> Self {
JValue::String(f.into()) JValue::String(f.into())
@ -112,15 +112,15 @@ impl From<String> for JValue {
} }
impl From<JsonString> for JValue { impl From<JsonString> for JValue {
/// Convert `String` to `Value::String`. /// Convert `JsonString` to `JValue::String`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let s: String = "lorem".to_string(); /// let s: String = "lorem".to_string();
/// let x: Value = s.into(); /// let x: JValue = s.into();
/// ``` /// ```
fn from(f: JsonString) -> Self { fn from(f: JsonString) -> Self {
JValue::String(f) JValue::String(f)
@ -128,15 +128,15 @@ impl From<JsonString> for JValue {
} }
impl From<&str> for JValue { impl From<&str> for JValue {
/// Convert string slice to `Value::String`. /// Convert string slice to `JValue::String`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let s: &str = "lorem"; /// let s: &str = "lorem";
/// let x: Value = s.into(); /// let x: JValue = s.into();
/// ``` /// ```
fn from(f: &str) -> Self { fn from(f: &str) -> Self {
JValue::String(f.into()) JValue::String(f.into())
@ -144,24 +144,24 @@ impl From<&str> for JValue {
} }
impl<'a> From<Cow<'a, str>> for JValue { impl<'a> From<Cow<'a, str>> for JValue {
/// Convert copy-on-write string to `Value::String`. /// Convert copy-on-write string to `JValue::String`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// use std::borrow::Cow; /// use std::borrow::Cow;
/// ///
/// let s: Cow<str> = Cow::Borrowed("lorem"); /// let s: Cow<str> = Cow::Borrowed("lorem");
/// let x: Value = s.into(); /// let x: JValue = s.into();
/// ``` /// ```
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// use std::borrow::Cow; /// use std::borrow::Cow;
/// ///
/// let s: Cow<str> = Cow::Owned("lorem".to_string()); /// let s: Cow<str> = Cow::Owned("lorem".to_string());
/// let x: Value = s.into(); /// let x: JValue = s.into();
/// ``` /// ```
fn from(f: Cow<'a, str>) -> Self { fn from(f: Cow<'a, str>) -> Self {
JValue::String(f.into()) JValue::String(f.into())
@ -169,15 +169,16 @@ impl<'a> From<Cow<'a, str>> for JValue {
} }
impl From<Number> for JValue { impl From<Number> for JValue {
/// Convert `Number` to `Value::Number`. /// Convert `serde_json::Number` to `JValue::Number`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::{Number, Value}; /// use serde_json::Number;
/// use air_interpreter_value::JValue;
/// ///
/// let n = Number::from(7); /// let n = Number::from(7);
/// let x: Value = n.into(); /// let x: JValue = n.into();
/// ``` /// ```
fn from(f: Number) -> Self { fn from(f: Number) -> Self {
JValue::Number(f) JValue::Number(f)
@ -185,16 +186,16 @@ impl From<Number> for JValue {
} }
impl From<Map<JsonString, JValue>> for JValue { impl From<Map<JsonString, JValue>> for JValue {
/// Convert map (with string keys) to `Value::Object`. /// Convert map (with string keys) to `JValue::Object`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::{Map, Value}; /// use air_interpreter_value::{Map, JValue, JsonString};
/// ///
/// let mut m = Map::new(); /// let mut m = Map::<JsonString, JValue>::new();
/// m.insert("Lorem".to_string(), "ipsum".into()); /// m.insert("Lorem".into(), "ipsum".into());
/// let x: Value = m.into(); /// let x: JValue = m.into();
/// ``` /// ```
fn from(f: Map<JsonString, JValue>) -> Self { fn from(f: Map<JsonString, JValue>) -> Self {
JValue::Object(f.into()) JValue::Object(f.into())
@ -202,7 +203,7 @@ impl From<Map<JsonString, JValue>> for JValue {
} }
impl<K: Into<JsonString>, V: Into<JValue>> From<HashMap<K, V>> for JValue { impl<K: Into<JsonString>, V: Into<JValue>> From<HashMap<K, V>> for JValue {
/// Convert map (with string keys) to `Value::Object`. /// Convert map (with string keys) to `JValue::Object`.
/// ///
/// # Examples /// # Examples
/// ///
@ -220,15 +221,15 @@ impl<K: Into<JsonString>, V: Into<JValue>> From<HashMap<K, V>> for JValue {
} }
impl<T: Into<JValue>> From<Vec<T>> for JValue { impl<T: Into<JValue>> From<Vec<T>> for JValue {
/// Convert a `Vec` to `Value::Array`. /// Convert a `Vec` to `JValue::Array`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let v = vec!["lorem", "ipsum", "dolor"]; /// let v = vec!["lorem", "ipsum", "dolor"];
/// let x: Value = v.into(); /// let x: JValue = v.into();
/// ``` /// ```
fn from(f: Vec<T>) -> Self { fn from(f: Vec<T>) -> Self {
JValue::Array(f.into_iter().map(Into::into).collect()) JValue::Array(f.into_iter().map(Into::into).collect())
@ -236,15 +237,15 @@ impl<T: Into<JValue>> From<Vec<T>> for JValue {
} }
impl<T: Clone + Into<JValue>> From<&[T]> for JValue { impl<T: Clone + Into<JValue>> From<&[T]> for JValue {
/// Convert a slice to `Value::Array`. /// Convert a slice to `JValue::Array`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let v: &[&str] = &["lorem", "ipsum", "dolor"]; /// let v: &[&str] = &["lorem", "ipsum", "dolor"];
/// let x: Value = v.into(); /// let x: JValue = v.into();
/// ``` /// ```
fn from(f: &[T]) -> Self { fn from(f: &[T]) -> Self {
JValue::Array(f.iter().cloned().map(Into::into).collect()) JValue::Array(f.iter().cloned().map(Into::into).collect())
@ -252,29 +253,29 @@ impl<T: Clone + Into<JValue>> From<&[T]> for JValue {
} }
impl<T: Into<JValue>> FromIterator<T> for JValue { impl<T: Into<JValue>> FromIterator<T> for JValue {
/// Create a `Value::Array` by collecting an iterator of array elements. /// Create a `JValue::Array` by collecting an iterator of array elements.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let v = std::iter::repeat(42).take(5); /// let v = std::iter::repeat(42).take(5);
/// let x: Value = v.collect(); /// let x: JValue = v.collect();
/// ``` /// ```
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let v: Vec<_> = vec!["lorem", "ipsum", "dolor"]; /// let v: Vec<_> = vec!["lorem", "ipsum", "dolor"];
/// let x: Value = v.into_iter().collect(); /// let x: JValue = v.into_iter().collect();
/// ``` /// ```
/// ///
/// ``` /// ```
/// use std::iter::FromIterator; /// use std::iter::FromIterator;
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let x: Value = Value::from_iter(vec!["lorem", "ipsum", "dolor"]); /// let x: JValue = JValue::from_iter(vec!["lorem", "ipsum", "dolor"]);
/// ``` /// ```
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self { fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
JValue::Array(iter.into_iter().map(Into::into).collect()) JValue::Array(iter.into_iter().map(Into::into).collect())
@ -282,15 +283,15 @@ impl<T: Into<JValue>> FromIterator<T> for JValue {
} }
impl<K: Into<JsonString>, V: Into<JValue>> FromIterator<(K, V)> for JValue { impl<K: Into<JsonString>, V: Into<JValue>> FromIterator<(K, V)> for JValue {
/// Create a `Value::Object` by collecting an iterator of key-value pairs. /// Create a `JValue::Object` by collecting an iterator of key-value pairs.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let v: Vec<_> = vec![("lorem", 40), ("ipsum", 2)]; /// let v: Vec<_> = vec![("lorem", 40), ("ipsum", 2)];
/// let x: Value = v.into_iter().collect(); /// let x: JValue = v.into_iter().collect();
/// ``` /// ```
fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self { fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
JValue::Object(Rc::new( JValue::Object(Rc::new(
@ -302,15 +303,15 @@ impl<K: Into<JsonString>, V: Into<JValue>> FromIterator<(K, V)> for JValue {
} }
impl From<()> for JValue { impl From<()> for JValue {
/// Convert `()` to `Value::Null`. /// Convert `()` to `JValue::Null`.
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use serde_json::Value; /// use air_interpreter_value::JValue;
/// ///
/// let u = (); /// let u = ();
/// let x: Value = u.into(); /// let x: JValue = u.into();
/// ``` /// ```
#[inline] #[inline]
fn from((): ()) -> Self { fn from((): ()) -> Self {

64
crates/air-lib/interpreter-value/src/value/index.rs
View File

@ -24,35 +24,19 @@ use core::fmt::{self, Display};
use core::ops; use core::ops;
use std::string::String; use std::string::String;
/// A type that can be used to index into a `serde_json::Value`. /// A type that can be used to index into a `air_interpreter_value::JValue`.
/// ///
/// The [`get`] and [`get_mut`] methods of `Value` accept any type that /// The [`get`] and [`get_mut`] methods of `JValue` accept any type that
/// implements `Index`, as does the [square-bracket indexing operator]. This /// implements `Index`, as does the [square-bracket indexing operator]. This
/// trait is implemented for strings which are used as the index into a JSON /// trait is implemented for strings which are used as the index into a JSON
/// map, and for `usize` which is used as the index into a JSON array. /// map, and for `usize` which is used as the index into a JSON array.
/// ///
/// [`get`]: ../enum.Value.html#method.get /// [`get`]: ../enum.JValue.html#method.get
/// [`get_mut`]: ../enum.Value.html#method.get_mut /// [`get_mut`]: ../enum.JValue.html#method.get_mut
/// [square-bracket indexing operator]: ../enum.Value.html#impl-Index%3CI%3E /// [square-bracket indexing operator]: ../enum.JValue.html#impl-Index%3CI%3E
/// ///
/// This trait is sealed and cannot be implemented for types outside of /// This trait is sealed and cannot be implemented for types outside of
/// `serde_json`. /// `air_interpreter_value`.
///
/// # Examples
///
/// ```
/// # use serde_json::json;
/// #
/// let data = json!({ "inner": [1, 2, 3] });
///
/// // Data is a JSON map so it can be indexed with a string.
/// let inner = &data["inner"];
///
/// // Inner is a JSON array so it can be indexed with an integer.
/// let first = &inner[0];
///
/// assert_eq!(first, 1);
/// ```
pub trait Index: private::Sealed { pub trait Index: private::Sealed {
/// Return None if the key is not already in the array or object. /// Return None if the key is not already in the array or object.
#[doc(hidden)] #[doc(hidden)]
@ -120,21 +104,21 @@ impl<'a> Display for Type<'a> {
// The usual semantics of Index is to panic on invalid indexing. // The usual semantics of Index is to panic on invalid indexing.
// //
// That said, the usual semantics are for things like Vec and BTreeMap which // That said, the usual semantics are for things like Vec and BTreeMap which
// have different use cases than Value. If you are working with a Vec, you know // have different use cases than JValue. If you are working with a Vec, you know
// that you are working with a Vec and you can get the len of the Vec and make // that you are working with a Vec and you can get the len of the Vec and make
// sure your indices are within bounds. The Value use cases are more // sure your indices are within bounds. The JValue use cases are more
// loosey-goosey. You got some JSON from an endpoint and you want to pull values // loosey-goosey. You got some JSON from an endpoint and you want to pull values
// out of it. Outside of this Index impl, you already have the option of using // out of it. Outside of this Index impl, you already have the option of using
// value.as_array() and working with the Vec directly, or matching on // value.as_array() and working with the Vec directly, or matching on
// Value::Array and getting the Vec directly. The Index impl means you can skip // JValue::Array and getting the Vec directly. The Index impl means you can skip
// that and index directly into the thing using a concise syntax. You don't have // that and index directly into the thing using a concise syntax. You don't have
// to check the type, you don't have to check the len, it is all about what you // to check the type, you don't have to check the len, it is all about what you
// expect the Value to look like. // expect the JValue to look like.
// //
// Basically the use cases that would be well served by panicking here are // Basically the use cases that would be well served by panicking here are
// better served by using one of the other approaches: get and get_mut, // better served by using one of the other approaches: get and get_mut,
// as_array, or match. The value of this impl is that it adds a way of working // as_array, or match. The value of this impl is that it adds a way of working
// with Value that is not well served by the existing approaches: concise and // with JValue that is not well served by the existing approaches: concise and
// careless and sometimes that is exactly what you want. // careless and sometimes that is exactly what you want.
impl<I> ops::Index<I> for JValue impl<I> ops::Index<I> for JValue
where where
@ -142,34 +126,16 @@ where
{ {
type Output = JValue; type Output = JValue;
/// Index into a `serde_json::Value` using the syntax `value[0]` or /// Index into a `air_interpreter_value::JValue` using the syntax `value[0]` or
/// `value["k"]`. /// `value["k"]`.
/// ///
/// Returns `Value::Null` if the type of `self` does not match the type of /// Returns `JValue::Null` if the type of `self` does not match the type of
/// the index, for example if the index is a string and `self` is an array /// the index, for example if the index is a string and `self` is an array
/// or a number. Also returns `Value::Null` if the given key does not exist /// or a number. Also returns `JValue::Null` if the given key does not exist
/// in the map or the given index is not within the bounds of the array. /// in the map or the given index is not within the bounds of the array.
/// ///
/// For retrieving deeply nested values, you should have a look at the /// For retrieving deeply nested values, you should have a look at the
/// `Value::pointer` method. /// `JValue::pointer` method.
///
/// # Examples
///
/// ```
/// # use serde_json::json;
/// #
/// let data = json!({
/// "x": {
/// "y": ["z", "zz"]
/// }
/// });
///
/// assert_eq!(data["x"]["y"], json!(["z", "zz"]));
/// assert_eq!(data["x"]["y"][0], json!("z"));
///
/// assert_eq!(data["a"], json!(null)); // returns null for undefined values
/// assert_eq!(data["a"]["b"], json!(null)); // does not panic
/// ```
fn index(&self, index: I) -> &JValue { fn index(&self, index: I) -> &JValue {
const NULL: JValue = JValue::Null; const NULL: JValue = JValue::Null;
index.index_into(self).unwrap_or(&NULL) index.index_into(self).unwrap_or(&NULL)

493
crates/air-lib/interpreter-value/src/value/mod.rs
View File

@ -19,95 +19,14 @@
* licensed under conditions of MIT License and Apache License, Version 2.0. * licensed under conditions of MIT License and Apache License, Version 2.0.
*/ */
//! The Value enum, a loosely typed way of representing any valid JSON value. //! The JValue enum, a loosely typed way of representing any valid JSON value.
//! //!
//! # Constructing JSON
//! mod de;
//! Serde JSON provides a [`json!` macro][macro] to build `serde_json::Value` mod from;
//! objects with very natural JSON syntax. mod index;
//! mod partial_eq;
//! ``` mod ser;
//! use serde_json::json;
//!
//! // The type of `john` is `serde_json::Value`
//! let john = json!({
//! "name": "John Doe",
//! "age": 43,
//! "phones": [
//! "+44 1234567",
//! "+44 2345678"
//! ]
//! });
//!
//! println!("first phone number: {}", john["phones"][0]);
//!
//! // Convert to a string of JSON and print it out
//! println!("{}", john.to_string());
//! ```
//!
//! The `Value::to_string()` function converts a `serde_json::Value` into a
//! `String` of JSON text.
//!
//! One neat thing about the `json!` macro is that variables and expressions can
//! be interpolated directly into the JSON value as you are building it. Serde
//! will check at compile time that the value you are interpolating is able to
//! be represented as JSON.
//!
//! ```
//! # use serde_json::json;
//! #
//! # fn random_phone() -> u16 { 0 }
//! #
//! let full_name = "John Doe";
//! let age_last_year = 42;
//!
//! // The type of `john` is `serde_json::Value`
//! let john = json!({
//! "name": full_name,
//! "age": age_last_year + 1,
//! "phones": [
//! format!("+44 {}", random_phone())
//! ]
//! });
//! ```
//!
//! A string of JSON data can be parsed into a `serde_json::Value` by the
//! [`serde_json::from_str`][from_str] function. There is also
//! [`from_slice`][from_slice] for parsing from a byte slice `&[u8]` and
//! [`from_reader`][from_reader] for parsing from any `io::Read` like a File or
//! a TCP stream.
//!
//! ```
//! use serde_json::{json, Value, Error};
//!
//! fn untyped_example() -> Result<(), Error> {
//! // Some JSON input data as a &str. Maybe this comes from the user.
//! let data = r#"
//! {
//! "name": "John Doe",
//! "age": 43,
//! "phones": [
//! "+44 1234567",
//! "+44 2345678"
//! ]
//! }"#;
//!
//! // Parse the string of data into serde_json::Value.
//! let v: Value = serde_json::from_str(data)?;
//!
//! // Access parts of the data by indexing with square brackets.
//! println!("Please call {} at the number {}", v["name"], v["phones"][0]);
//!
//! Ok(())
//! }
//! #
//! # untyped_example().unwrap();
//! ```
//!
//! [macro]: crate::json
//! [from_str]: crate::de::from_str
//! [from_slice]: crate::de::from_slice
//! [from_reader]: crate::de::from_reader
use core::fmt::{self, Debug, Display}; use core::fmt::{self, Debug, Display};
use core::mem; use core::mem;
@ -121,55 +40,22 @@ pub use crate::Map;
pub use serde::ser::Serializer; pub use serde::ser::Serializer;
pub use serde_json::Number; pub use serde_json::Number;
/// Represents any valid JSON value. /// Represents any valid JSON value with a cheap to clone Rc-based representation.
///
/// See the [`serde_json::value` module documentation](self) for usage examples.
#[derive(Clone, Eq, PartialEq)] #[derive(Clone, Eq, PartialEq)]
pub enum JValue { pub enum JValue {
/// Represents a JSON null value. /// Represents a JSON null value.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!(null);
/// ```
Null, Null,
/// Represents a JSON boolean. /// Represents a JSON boolean.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!(true);
/// ```
Bool(bool), Bool(bool),
/// Represents a JSON number, whether integer or floating point. /// Represents a JSON number, whether integer or floating point.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!(12.5);
/// ```
Number(Number), Number(Number),
/// Represents a JSON string. /// Represents a JSON string.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!("a string");
/// ```
String(JsonString), String(JsonString),
/// Represents a JSON array. /// Represents a JSON array.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!(["an", "array"]);
/// ```
// Rc<[JValue]> is little slower, but Rc<Vec<JValue>> consumes little more memory
Array(Rc<[JValue]>), Array(Rc<[JValue]>),
/// Represents a JSON object. /// Represents a JSON object.
@ -177,14 +63,8 @@ pub enum JValue {
/// By default the map is backed by a BTreeMap. Enable the `preserve_order` /// By default the map is backed by a BTreeMap. Enable the `preserve_order`
/// feature of serde_json to use IndexMap instead, which preserves /// feature of serde_json to use IndexMap instead, which preserves
/// entries in the order they are inserted into the map. In particular, this /// entries in the order they are inserted into the map. In particular, this
/// allows JSON data to be deserialized into a Value and serialized to a /// allows JSON data to be deserialized into a JValue and serialized to a
/// string while retaining the order of map keys in the input. /// string while retaining the order of map keys in the input.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "an": "object" });
/// ```
Object(Rc<Map<JsonString, JValue>>), Object(Rc<Map<JsonString, JValue>>),
} }
@ -209,29 +89,6 @@ impl Debug for JValue {
impl Display for JValue { impl Display for JValue {
/// Display a JSON value as a string. /// Display a JSON value as a string.
///
/// ```
/// # use serde_json::json;
/// #
/// let json = json!({ "city": "London", "street": "10 Downing Street" });
///
/// // Compact format:
/// //
/// // {"city":"London","street":"10 Downing Street"}
/// let compact = format!("{}", json);
/// assert_eq!(compact,
/// "{\"city\":\"London\",\"street\":\"10 Downing Street\"}");
///
/// // Pretty format:
/// //
/// // {
/// // "city": "London",
/// // "street": "10 Downing Street"
/// // }
/// let pretty = format!("{:#}", json);
/// assert_eq!(pretty,
/// "{\n \"city\": \"London\",\n \"street\": \"10 Downing Street\"\n}");
/// ```
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
struct WriterFormatter<'a, 'b: 'a> { struct WriterFormatter<'a, 'b: 'a> {
inner: &'a mut fmt::Formatter<'b>, inner: &'a mut fmt::Formatter<'b>,
@ -315,75 +172,25 @@ impl JValue {
/// number. Also returns `None` if the given key does not exist in the map /// number. Also returns `None` if the given key does not exist in the map
/// or the given index is not within the bounds of the array. /// or the given index is not within the bounds of the array.
/// ///
/// ```
/// # use serde_json::json;
/// #
/// let object = json!({ "A": 65, "B": 66, "C": 67 });
/// assert_eq!(*object.get("A").unwrap(), json!(65));
///
/// let array = json!([ "A", "B", "C" ]);
/// assert_eq!(*array.get(2).unwrap(), json!("C"));
///
/// assert_eq!(array.get("A"), None);
/// ```
///
/// Square brackets can also be used to index into a value in a more concise /// Square brackets can also be used to index into a value in a more concise
/// way. This returns `Value::Null` in cases where `get` would have returned /// way. This returns `JValue::Null` in cases where `get` would have returned
/// `None`. /// `None`.
///
/// ```
/// # use serde_json::json;
/// #
/// let object = json!({
/// "A": ["a", "á", "à"],
/// "B": ["b", "b́"],
/// "C": ["c", "ć", "ć̣", "ḉ"],
/// });
/// assert_eq!(object["B"][0], json!("b"));
///
/// assert_eq!(object["D"], json!(null));
/// assert_eq!(object[0]["x"]["y"]["z"], json!(null));
/// ```
pub fn get<I: Index>(&self, index: I) -> Option<&JValue> { pub fn get<I: Index>(&self, index: I) -> Option<&JValue> {
index.index_into(self) index.index_into(self)
} }
/// Returns true if the `Value` is an Object. Returns false otherwise. /// Returns true if the `JValue` is an Object. Returns false otherwise.
/// ///
/// For any Value on which `is_object` returns true, `as_object` and /// For any JValue on which `is_object` returns true, `as_object` and
/// `as_object_mut` are guaranteed to return the map representation of the /// `as_object_mut` are guaranteed to return the map representation of the
/// object. /// object.
///
/// ```
/// # use serde_json::json;
/// #
/// let obj = json!({ "a": { "nested": true }, "b": ["an", "array"] });
///
/// assert!(obj.is_object());
/// assert!(obj["a"].is_object());
///
/// // array, not an object
/// assert!(!obj["b"].is_object());
/// ```
#[inline] #[inline]
pub fn is_object(&self) -> bool { pub fn is_object(&self) -> bool {
self.as_object().is_some() self.as_object().is_some()
} }
/// If the `Value` is an Object, returns the associated Map. Returns None /// If the `JValue` is an Object, returns the associated Map. Returns None
/// otherwise. /// otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": { "nested": true }, "b": ["an", "array"] });
///
/// // The length of `{"nested": true}` is 1 entry.
/// assert_eq!(v["a"].as_object().unwrap().len(), 1);
///
/// // The array `["an", "array"]` is not an object.
/// assert_eq!(v["b"].as_object(), None);
/// ```
#[inline] #[inline]
pub fn as_object(&self) -> Option<&Map<JsonString, JValue>> { pub fn as_object(&self) -> Option<&Map<JsonString, JValue>> {
match self { match self {
@ -392,41 +199,18 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is an Array. Returns false otherwise. /// Returns true if the `JValue` is an Array. Returns false otherwise.
/// ///
/// For any Value on which `is_array` returns true, `as_array` and /// For any JValue on which `is_array` returns true, `as_array` and
/// `as_array_mut` are guaranteed to return the vector representing the /// `as_array_mut` are guaranteed to return the vector representing the
/// array. /// array.
///
/// ```
/// # use serde_json::json;
/// #
/// let obj = json!({ "a": ["an", "array"], "b": { "an": "object" } });
///
/// assert!(obj["a"].is_array());
///
/// // an object, not an array
/// assert!(!obj["b"].is_array());
/// ```
#[inline] #[inline]
pub fn is_array(&self) -> bool { pub fn is_array(&self) -> bool {
self.as_array().is_some() self.as_array().is_some()
} }
/// If the `Value` is an Array, returns the associated vector. Returns None /// If the `JValue` is an Array, returns the associated vector. Returns None
/// otherwise. /// otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": ["an", "array"], "b": { "an": "object" } });
///
/// // The length of `["an", "array"]` is 2 elements.
/// assert_eq!(v["a"].as_array().unwrap().len(), 2);
///
/// // The object `{"an": "object"}` is not an array.
/// assert_eq!(v["b"].as_array(), None);
/// ```
#[inline] #[inline]
pub fn as_array(&self) -> Option<&[JValue]> { pub fn as_array(&self) -> Option<&[JValue]> {
match self { match self {
@ -435,49 +219,17 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is a String. Returns false otherwise. /// Returns true if the `JValue` is a String. Returns false otherwise.
/// ///
/// For any Value on which `is_string` returns true, `as_str` is guaranteed /// For any JValue on which `is_string` returns true, `as_str` is guaranteed
/// to return the string slice. /// to return the string slice.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": "some string", "b": false });
///
/// assert!(v["a"].is_string());
///
/// // The boolean `false` is not a string.
/// assert!(!v["b"].is_string());
/// ```
#[inline] #[inline]
pub fn is_string(&self) -> bool { pub fn is_string(&self) -> bool {
self.as_str().is_some() self.as_str().is_some()
} }
/// If the `Value` is a String, returns the associated str. Returns None /// If the `JValue` is a string, returns the associated str. Returns None
/// otherwise. /// otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": "some string", "b": false });
///
/// assert_eq!(v["a"].as_str(), Some("some string"));
///
/// // The boolean `false` is not a string.
/// assert_eq!(v["b"].as_str(), None);
///
/// // JSON values are printed in JSON representation, so strings are in quotes.
/// //
/// // The value is: "some string"
/// println!("The value is: {}", v["a"]);
///
/// // Rust strings are printed without quotes.
/// //
/// // The value is: some string
/// println!("The value is: {}", v["a"].as_str().unwrap());
/// ```
#[inline] #[inline]
pub fn as_str(&self) -> Option<&JsonString> { pub fn as_str(&self) -> Option<&JsonString> {
match self { match self {
@ -486,38 +238,14 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is a Number. Returns false otherwise. /// Returns true if the `JValue` is a Number. Returns false otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": 1, "b": "2" });
///
/// assert!(v["a"].is_number());
///
/// // The string `"2"` is a string, not a number.
/// assert!(!v["b"].is_number());
/// ```
#[inline] #[inline]
pub fn is_number(&self) -> bool { pub fn is_number(&self) -> bool {
matches!(self, JValue::Number(_)) matches!(self, JValue::Number(_))
} }
/// If the `Value` is a Number, returns the associated [`Number`]. Returns /// If the `JValue` is a Number, returns the associated [`Number`]. Returns
/// None otherwise. /// None otherwise.
///
/// ```
/// # use serde_json::{json, Number};
/// #
/// let v = json!({ "a": 1, "b": 2.2, "c": -3, "d": "4" });
///
/// assert_eq!(v["a"].as_number(), Some(&Number::from(1u64)));
/// assert_eq!(v["b"].as_number(), Some(&Number::from_f64(2.2).unwrap()));
/// assert_eq!(v["c"].as_number(), Some(&Number::from(-3i64)));
///
/// // The string `"4"` is not a number.
/// assert_eq!(v["d"].as_number(), None);
/// ```
#[inline] #[inline]
pub fn as_number(&self) -> Option<&Number> { pub fn as_number(&self) -> Option<&Number> {
match self { match self {
@ -526,26 +254,11 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is an integer between `i64::MIN` and /// Returns true if the `JValue` is an integer between `i64::MIN` and
/// `i64::MAX`. /// `i64::MAX`.
/// ///
/// For any Value on which `is_i64` returns true, `as_i64` is guaranteed to /// For any JValue on which `is_i64` returns true, `as_i64` is guaranteed to
/// return the integer value. /// return the integer value.
///
/// ```
/// # use serde_json::json;
/// #
/// let big = i64::max_value() as u64 + 10;
/// let v = json!({ "a": 64, "b": big, "c": 256.0 });
///
/// assert!(v["a"].is_i64());
///
/// // Greater than i64::MAX.
/// assert!(!v["b"].is_i64());
///
/// // Numbers with a decimal point are not considered integers.
/// assert!(!v["c"].is_i64());
/// ```
#[inline] #[inline]
pub fn is_i64(&self) -> bool { pub fn is_i64(&self) -> bool {
match self { match self {
@ -554,24 +267,10 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is an integer between zero and `u64::MAX`. /// Returns true if the `JValue` is an integer between zero and `u64::MAX`.
/// ///
/// For any Value on which `is_u64` returns true, `as_u64` is guaranteed to /// For any JValue on which `is_u64` returns true, `as_u64` is guaranteed to
/// return the integer value. /// return the integer value.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": 64, "b": -64, "c": 256.0 });
///
/// assert!(v["a"].is_u64());
///
/// // Negative integer.
/// assert!(!v["b"].is_u64());
///
/// // Numbers with a decimal point are not considered integers.
/// assert!(!v["c"].is_u64());
/// ```
#[inline] #[inline]
pub fn is_u64(&self) -> bool { pub fn is_u64(&self) -> bool {
match self { match self {
@ -580,25 +279,13 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is a number that can be represented by f64. /// Returns true if the `JValue` is a number that can be represented by f64.
/// ///
/// For any Value on which `is_f64` returns true, `as_f64` is guaranteed to /// For any JValue on which `is_f64` returns true, `as_f64` is guaranteed to
/// return the floating point value. /// return the floating point value.
/// ///
/// Currently this function returns true if and only if both `is_i64` and /// Currently this function returns true if and only if both `is_i64` and
/// `is_u64` return false but this is not a guarantee in the future. /// `is_u64` return false but this is not a guarantee in the future.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": 256.0, "b": 64, "c": -64 });
///
/// assert!(v["a"].is_f64());
///
/// // Integers.
/// assert!(!v["b"].is_f64());
/// assert!(!v["c"].is_f64());
/// ```
#[inline] #[inline]
pub fn is_f64(&self) -> bool { pub fn is_f64(&self) -> bool {
match self { match self {
@ -607,19 +294,8 @@ impl JValue {
} }
} }
/// If the `Value` is an integer, represent it as i64 if possible. Returns /// If the `JValue` is an integer, represent it as i64 if possible. Returns
/// None otherwise. /// None otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let big = i64::max_value() as u64 + 10;
/// let v = json!({ "a": 64, "b": big, "c": 256.0 });
///
/// assert_eq!(v["a"].as_i64(), Some(64));
/// assert_eq!(v["b"].as_i64(), None);
/// assert_eq!(v["c"].as_i64(), None);
/// ```
#[inline] #[inline]
pub fn as_i64(&self) -> Option<i64> { pub fn as_i64(&self) -> Option<i64> {
match self { match self {
@ -628,18 +304,8 @@ impl JValue {
} }
} }
/// If the `Value` is an integer, represent it as u64 if possible. Returns /// If the `JValue` is an integer, represent it as u64 if possible. Returns
/// None otherwise. /// None otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": 64, "b": -64, "c": 256.0 });
///
/// assert_eq!(v["a"].as_u64(), Some(64));
/// assert_eq!(v["b"].as_u64(), None);
/// assert_eq!(v["c"].as_u64(), None);
/// ```
#[inline] #[inline]
pub fn as_u64(&self) -> Option<u64> { pub fn as_u64(&self) -> Option<u64> {
match self { match self {
@ -648,18 +314,8 @@ impl JValue {
} }
} }
/// If the `Value` is a number, represent it as f64 if possible. Returns /// If the `JValue` is a number, represent it as f64 if possible. Returns
/// None otherwise. /// None otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": 256.0, "b": 64, "c": -64 });
///
/// assert_eq!(v["a"].as_f64(), Some(256.0));
/// assert_eq!(v["b"].as_f64(), Some(64.0));
/// assert_eq!(v["c"].as_f64(), Some(-64.0));
/// ```
#[inline] #[inline]
pub fn as_f64(&self) -> Option<f64> { pub fn as_f64(&self) -> Option<f64> {
match self { match self {
@ -668,39 +324,17 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is a Boolean. Returns false otherwise. /// Returns true if the `JValue` is a Boolean. Returns false otherwise.
/// ///
/// For any Value on which `is_boolean` returns true, `as_bool` is /// For any JValue on which `is_boolean` returns true, `as_bool` is
/// guaranteed to return the boolean value. /// guaranteed to return the boolean value.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": false, "b": "false" });
///
/// assert!(v["a"].is_boolean());
///
/// // The string `"false"` is a string, not a boolean.
/// assert!(!v["b"].is_boolean());
/// ```
#[inline] #[inline]
pub fn is_boolean(&self) -> bool { pub fn is_boolean(&self) -> bool {
self.as_bool().is_some() self.as_bool().is_some()
} }
/// If the `Value` is a Boolean, returns the associated bool. Returns None /// If the `JValue` is a Boolean, returns the associated bool. Returns None
/// otherwise. /// otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": false, "b": "false" });
///
/// assert_eq!(v["a"].as_bool(), Some(false));
///
/// // The string `"false"` is a string, not a boolean.
/// assert_eq!(v["b"].as_bool(), None);
/// ```
#[inline] #[inline]
pub fn as_bool(&self) -> Option<bool> { pub fn as_bool(&self) -> Option<bool> {
match *self { match *self {
@ -709,38 +343,16 @@ impl JValue {
} }
} }
/// Returns true if the `Value` is a Null. Returns false otherwise. /// Returns true if the `JValue` is a Null. Returns false otherwise.
/// ///
/// For any Value on which `is_null` returns true, `as_null` is guaranteed /// For any JValue on which `is_null` returns true, `as_null` is guaranteed
/// to return `Some(())`. /// to return `Some(())`.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": null, "b": false });
///
/// assert!(v["a"].is_null());
///
/// // The boolean `false` is not null.
/// assert!(!v["b"].is_null());
/// ```
#[inline] #[inline]
pub fn is_null(&self) -> bool { pub fn is_null(&self) -> bool {
self.as_null().is_some() self.as_null().is_some()
} }
/// If the `Value` is a Null, returns (). Returns None otherwise. /// If the `JValue` is a Null, returns (). Returns None otherwise.
///
/// ```
/// # use serde_json::json;
/// #
/// let v = json!({ "a": null, "b": false });
///
/// assert_eq!(v["a"].as_null(), Some(()));
///
/// // The boolean `false` is not null.
/// assert_eq!(v["b"].as_null(), None);
/// ```
#[inline] #[inline]
pub fn as_null(&self) -> Option<()> { pub fn as_null(&self) -> Option<()> {
match *self { match *self {
@ -760,21 +372,6 @@ impl JValue {
/// returned. /// returned.
/// ///
/// For more information read [RFC6901](https://tools.ietf.org/html/rfc6901). /// For more information read [RFC6901](https://tools.ietf.org/html/rfc6901).
///
/// # Examples
///
/// ```
/// # use serde_json::json;
/// #
/// let data = json!({
/// "x": {
/// "y": ["z", "zz"]
/// }
/// });
///
/// assert_eq!(data.pointer("/x/y/1").unwrap(), &json!("zz"));
/// assert_eq!(data.pointer("/a/b/c"), None);
/// ```
pub fn pointer(&self, pointer: &str) -> Option<&JValue> { pub fn pointer(&self, pointer: &str) -> Option<&JValue> {
if pointer.is_empty() { if pointer.is_empty() {
return Some(self); return Some(self);
@ -793,31 +390,17 @@ impl JValue {
}) })
} }
/// Takes the value out of the `Value`, leaving a `Null` in its place. /// Takes the value out of the `JValue`, leaving a `Null` in its place.
///
/// ```
/// # use serde_json::json;
/// #
/// let mut v = json!({ "x": "y" });
/// assert_eq!(v["x"].take(), json!("y"));
/// assert_eq!(v, json!({ "x": null }));
/// ```
#[inline] #[inline]
pub fn take(&mut self) -> JValue { pub fn take(&mut self) -> JValue {
mem::replace(self, JValue::Null) mem::replace(self, JValue::Null)
} }
} }
/// The default value is `Value::Null`. /// The default value is `JValue::Null`.
impl Default for JValue { impl Default for JValue {
#[inline] #[inline]
fn default() -> JValue { fn default() -> JValue {
JValue::Null JValue::Null
} }
} }
mod de;
mod from;
mod index;
mod partial_eq;
mod ser;