Enum sj::Json

source ·

pub enum Json {
    String(String),
    Number(Number),
    Boolean(bool),
    Null,
    Object(Object),
    Array(Array),
}

Expand description

§Json

§Formatting

§Formatting as JSON string

To format as compacted JSON string, you can use format() or format_as_bytes().
To format as a nice JSON string, you can use format_nicely().
Currently the order of keys in input objects will not be preserved. See Object for more details.

§Writing as JSON string to `Write`

Can be done via write() or write_nicely().

§Converting Rust types to `Json` and vice versa

There are some implementations:

impl From<...> for Json;
impl TryFrom<&Json> for ...;
impl TryFrom<Json> for ...;

About TryFrom implementations:

For primitives, since they’re cheap, they have implementations on either a borrowed or an owned value.
For collections such as String, Object, Array…, they only have implementations on an owned value. So data is moved, not copied.

§Shortcuts

A root JSON value can be either an object or an array. For your convenience, there are some shortcuts, like below examples.

Object:


let mut object = sj::object();
object.insert("first", true)?;
object.insert("second", <Option<u8>>::None)?;
object.insert(String::from("third"), "...")?;

assert!(bool::try_from(object.by("first")?)?);
assert!(object.take_by("second")?.map_or(true)?);
assert!(
    [r#"{"first":true,"third":"..."}"#, r#"{"third":"...","first":true}"#]
        .contains(&object.format()?.as_str())
);

Array:


let mut array = sj::array();
array.push(false)?;
array.push("a string")?;
array.push(Some(sj::object()))?;

assert!(bool::try_from(array.at(0)?)? == false);
assert_eq!(array.format()?, r#"[false,"a string",{}]"#);

Variants§

§

String(String)

Shortcuts

§

Number(Number)

§Shortcuts

TryFrom

§

Boolean(bool)

Implementations§

source §

impl Json

§Shortcuts for `Array`

source

pub fn push<T>(&mut self, value: T) -> Result<()>
where T: Into<Self>,

§If the value is an array, pushes new item into it

Returns an error if the value is not an array.

source

pub fn at<'a, I, const N: usize>(&self, indexes: I) -> Result<&Self>
where I: Into<ArrayIndexes<'a, N>>,

§Gets an immutable item from this array and its sub arrays

The function returns an error on one of these conditions:

Indexes are empty or invalid.
The value or any of its sub items is not an array.

§Examples

let mut array = sj::array();
array.push("first")?;
array.push(vec![false.into(), "second".into()])?;

assert_eq!(array.at(0)?.as_str()?, "first");
assert_eq!(array.at([1, 1])?.as_str()?, "second");

assert!(array.at(&[][..]).is_err());
assert!(array.at([0, 1]).is_err());
assert!(array.at([1, 2]).is_err());
assert!(array.at([1, 0, 0]).is_err());
assert!(array.at([1, 1, 2]).is_err());

source

pub fn mut_at<'a, I, const N: usize>(&mut self, indexes: I) -> Result<&mut Self>
where I: Into<ArrayIndexes<'a, N>>,

§Gets a mutable item from this array and its sub arrays

The function returns an error on one of these conditions:

Indexes are empty or invalid.
The value or any of its sub items is not an array.

source

pub fn take_at<'a, I, const N: usize>(&mut self, indexes: I) -> Result<Self>
where I: Into<ArrayIndexes<'a, N>>,

§Takes an item from this array and its sub arrays

The function returns an error on one of these conditions:

Indexes are empty or invalid.
The value or any of its sub items is not an array.

§Examples

let mut array = sj::array();
array.push("earth")?;
array.push(vec![false.into(), "moon".into()])?;

assert_eq!(array.take_at(0)?.as_str()?, "earth");
assert_eq!(array.take_at([0, 1])?.as_str()?, "moon");

assert!(array.take_at(&[][..]).is_err());
assert!(array.take_at([0, 1]).is_err());

source

pub fn as_array(&self) -> Result<&Array>

§If the value is an array, returns an immutable reference of it

Returns an error if the value is not an array.

source

pub fn as_mut_array(&mut self) -> Result<&mut Array>

§If the value is an array, returns a mutable reference of it

Returns an error if the value is not an array.

source §

impl Json

§Shortcuts for `Null`

source

pub fn is_null(&self) -> bool

§Checks to see if this value is `Null`

source

pub fn map<T, E>(self) -> Result<Option<T>, E>
where T: TryFrom<Self, Error = E>,

§Maps this value into something

If this is Null, returns None.

source

pub fn map_ref<'a, T, E>(&'a self) -> Result<Option<T>, E>
where T: TryFrom<&'a Self, Error = E>,

§Maps this value into something

If this is Null, returns None.

source

pub fn map_or<T, E>(self, default: T) -> Result<T, E>
where T: TryFrom<Self, Error = E>,

§Tries to convert this value into something

If this is Null, returns default.

If your default value would be a result of a function call, you should use map_or_else().

§Examples

let mut value = sj::parse_bytes("[null]")?;
assert!(value.take_at(0)?.map_or(true)?);

source

pub fn map_or_else<T, E, F>(self, default: F) -> Result<T, E>
where T: TryFrom<Self, Error = E>, F: FnOnce() -> T,

§Tries to convert this value into something

If this is Null, calls default() and returns its result.

source

pub fn map_ref_or<'a, T, E>(&'a self, default: T) -> Result<T, E>
where T: TryFrom<&'a Self, Error = E>,

§Tries to convert a reference of this value into something

If this is Null, returns default.

If your default value would be a result of a function call, you should use map_ref_or_else().

§Examples

let value = sj::parse_bytes("[null]")?;
assert_eq!(value.at(0)?.map_ref_or(0)?, 0);

source

pub fn map_ref_or_else<'a, T, E, F>(&'a self, default: F) -> Result<T, E>
where T: TryFrom<&'a Self, Error = E>, F: FnOnce() -> T,

§Tries to convert a reference of this value into something

If this is Null, calls default() and returns its result.

source

pub fn unwrap_or_null(json: Option<Self>) -> Self

§Unwraps an option of a `Json`

If this is None, returns Null.

source

pub fn unwrap_ref_or_null<'a>(json: Option<&'a Self>) -> &'a Self

§Unwraps an option of a `Json`

If this is None, returns Null.

source §

impl Json

§Shortcuts for `Object`

source

pub fn insert<K, V>(&mut self, key: K, value: V) -> Result<Option<Self>>
where K: Into<ObjectKey>, V: Into<Self>,

§If the value is an object, inserts new item into it

On success, returns previous value (if it existed).

Returns an error if the value is not an object.

source

pub fn by<'a, K, const N: usize>(&self, keys: K) -> Result<&Self>
where K: Into<ObjectIndexes<'a, N>>,

§Gets an immutable item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

§Examples

let mut object = sj::object();
object.insert("first", true)?;
object.insert("second", {
    let mut map = sj::Object::new();
    sj::insert(&mut map, "zero", 0);
    map
})?;

assert_eq!(bool::try_from(object.by("first")?)?, true);
assert_eq!(u8::try_from(object.by(["second", "zero"])?)?, 0);

assert!(object.by("something").is_err());
assert!(object.maybe_by("something")?.is_none());

assert!(object.by(&[][..]).is_err());
assert!(object.by(["first", "last"]).is_err());
assert!(object.by(["second", "third", "fourth"]).is_err());

source

pub fn by_or_null<'a, K, const N: usize>(&self, keys: K) -> Result<&Self>
where K: Into<ObjectIndexes<'a, N>>,

§Gets an immutable item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

If there is no value, Null is returned.

source

pub fn maybe_by<'a, K, const N: usize>(&self, keys: K) -> Result<Option<&Self>>
where K: Into<ObjectIndexes<'a, N>>,

§Gets an optional immutable item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

source

pub fn mut_by<'a, K, const N: usize>(&mut self, keys: K) -> Result<&mut Self>
where K: Into<ObjectIndexes<'a, N>>,

§Gets a mutable item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

source

pub fn maybe_mut_by<'a, K, const N: usize>( &mut self, keys: K ) -> Result<Option<&mut Self>>
where K: Into<ObjectIndexes<'a, N>>,

§Gets an optional mutable item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

source

pub fn take_by<'a, K, const N: usize>(&mut self, keys: K) -> Result<Self>
where K: Into<ObjectIndexes<'a, N>>,

§Takes an item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

§Examples

let mut object = sj::object();
object.insert("earth", "moon")?;
object.insert("solar-system", {
    let mut map = sj::Object::new();
    sj::insert(&mut map, "sun", "earth");
    map
})?;

assert_eq!(object.take_by("earth")?.as_str()?, "moon");
assert_eq!(object.take_by(["solar-system", "sun"])?.as_str()?, "earth");

assert!(object.take_by("milky-way").is_err());
assert!(object.maybe_take_by("milky-way")?.is_none());
assert!(object.maybe_take_by(["solar-system", "mars"])?.is_none());

assert!(object.take_by(&[][..]).is_err());
assert!(object.take_by(["jupiter", "venus"]).is_err());

source

pub fn take_by_or_null<'a, K, const N: usize>( &mut self, keys: K ) -> Result<Self>
where K: Into<ObjectIndexes<'a, N>>,

§Takes an item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

If there is no value, Null is returned.

source

pub fn maybe_take_by<'a, K, const N: usize>( &mut self, keys: K ) -> Result<Option<Self>>
where K: Into<ObjectIndexes<'a, N>>,

§Takes an optional item from this object and its sub objects

The function returns an error on one of these conditions:

Keys are empty.
The value or any of its sub items is not an object.

source

pub fn as_object(&self) -> Result<&Object>

§If the value is an object, returns an immutable reference of it

Returns an error if the value is not an object.

source

pub fn as_mut_object(&mut self) -> Result<&mut Object>

§If the value is an object, returns a mutable reference of it

Returns an error if the value is not an object.

source §

impl Json

§Shortcuts for `String`

source

pub fn as_str(&self) -> Result<&str>

§If the value is a string, returns an immutable reference of it

Returns an error if the value is not a string.

source

pub fn as_mut_str(&mut self) -> Result<&mut String>

§If the value is a string, returns a mutable reference of it

Returns an error if the value is not a string.

source §

impl Json

source

pub fn format_as_bytes(&self) -> IoResult<Vec<u8>>

Available on crate feature std only.

§Formats this value as a compacted JSON string

source

pub fn format_nicely_as_bytes(&self, tab: Option<u8>) -> IoResult<Vec<u8>>

Available on crate feature std only.

§Nicely formats this value as JSON string

If you don’t provide tab size, default (4) will be used.

source

pub fn format(&self) -> IoResult<String>

Available on crate feature std only.

§Formats this value as a compacted JSON string

source

pub fn format_nicely(&self, tab: Option<u8>) -> IoResult<String>

Available on crate feature std only.

§Nicely formats this value as JSON string

If you don’t provide tab size, default (4) will be used.

source

pub fn write<W>(&self, stream: &mut W) -> IoResult<()>
where W: Write,

Available on crate feature std only.

§Writes this value as compacted JSON string to a stream

§Notes

The stream is used as-is. You might want to consider using BufWriter.
This function does not flush the stream when done.

source

pub fn write_nicely<W>(&self, tab: Option<u8>, stream: &mut W) -> IoResult<()>
where W: Write,

Available on crate feature std only.

§Writes this value as nicely formatted JSON string to a stream

§Notes

If you don’t provide tab size, default (4) will be used.
The stream is used as-is. You might want to consider using BufWriter.
This function does not flush the stream when done.

Trait Implementations§

source §

impl Clone for Json

source §

fn clone(&self) -> Json

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

source §

impl Debug for Json

source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

source §

impl Default for Json

source §

fn default() -> Self

Returns the “default value” for a type. Read more

source §