Enum sj::Value

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

A value

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().

Writing as JSON string to Write

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

Converting Rust types to Value and vice versa

There are some implementations:

impl From<...> for Value;
impl TryFrom<&Value> for ...;
impl TryFrom<Value> 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:

  use core::convert::TryFrom;
  
  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"])?.try_into_or(true)?);
  assert_eq!(object.format()?, r#"{"first":true,"third":"..."}"#);

• Array:

  use core::convert::TryFrom;
  
  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

as_str()

Number(Number)

Shortcuts

TryFrom

Boolean(bool)

Shortcuts

TryFrom

Null

Shortcuts

is_null(), try_into_or(), try_into_or_else(), try_ref_into_or(), try_ref_into_or_else()...

Object(Object)

Shortcuts

insert(), by(), maybe_by(), mut_by(), maybe_mut_by(), take_by(), maybe_take_by(), as_object(), as_mut_object()...

Array(Array)

Shortcuts

push(), at(), mut_at(), take_at(), as_array(), as_mut_array()...

Methods

impl Value

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

Formats this value as a compacted JSON string

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

Nicely formats this value as JSON string

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

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

Formats this value as a compacted JSON string

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

Nicely formats this value as JSON string

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

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

Writes this value as compacted JSON string to a stream

Notes

• The stream is used as-is. For better performance, you should wrap your stream inside a BufWriter.
• This function does not flush the stream when done.

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

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. For better performance, you should wrap your stream inside a BufWriter.
• This function does not flush the stream when done.

pub fn is_null(&self) -> bool

Checks to see if this value is Null

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

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 try_into_or_else().

Examples

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

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

Tries to convert this value into something

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

See also

try_into_or()

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

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 try_ref_into_or_else().

Examples

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

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

Tries to convert a reference of this value into something

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

See also

try_ref_into_or()

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.

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.

pub fn at(&self, indexes: &[usize]) -> Result<&Self>

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());

pub fn mut_at(&mut self, indexes: &[usize]) -> Result<&mut Self>

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.

See also

at()

pub fn take_at(&mut self, indexes: &[usize]) -> Result<Self>

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());

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.

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.

pub fn insert<S, T>(&mut self, key: S, value: T) -> Result<Option<Self>> where
    S: Into<String>,
    T: 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.

pub fn by(&self, keys: &[&str]) -> Result<&Self>

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

use core::convert::TryFrom;

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());

pub fn maybe_by(&self, keys: &[&str]) -> Result<Option<&Self>>

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.

pub fn mut_by(&mut self, keys: &[&str]) -> Result<&mut Self>

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.

pub fn maybe_mut_by(&mut self, keys: &[&str]) -> Result<Option<&mut Self>>

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.

pub fn take_by(&mut self, keys: &[&str]) -> Result<Self>

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());

pub fn maybe_take_by(&mut self, keys: &[&str]) -> Result<Option<Self>>

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.

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.

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.

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Value

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

Formats the value using the given formatter.

impl<'_> From<&'_ str> for Value

fn from(s: &str) -> Self

Performs the conversion.

impl From<BTreeMap<String, Value>> for Value

fn from(map: Object) -> Self

Performs the conversion.

impl From<Number> for Value

fn from(n: Number) -> Self

Performs the conversion.

impl<T> From<Option<T>> for Value where
    T: Into<Value>, 

fn from(t: Option<T>) -> Self

Performs the conversion.

impl From<String> for Value

fn from(s: String) -> Self

Performs the conversion.

impl From<Vec<Value>> for Value

fn from(values: Array) -> Self

Performs the conversion.

impl From<bool> for Value

fn from(b: bool) -> Self

Performs the conversion.

impl From<f32> for Value

fn from(n: f32) -> Self

Performs the conversion.

impl From<f64> for Value

fn from(n: f64) -> Self

Performs the conversion.

impl From<i128> for Value

fn from(n: i128) -> Self

Performs the conversion.

impl From<i16> for Value

fn from(n: i16) -> Self

Performs the conversion.

impl From<i32> for Value

fn from(n: i32) -> Self

Performs the conversion.

impl From<i64> for Value

fn from(n: i64) -> Self

Performs the conversion.

impl From<i8> for Value

fn from(n: i8) -> Self

Performs the conversion.

impl From<isize> for Value

fn from(n: isize) -> Self

Performs the conversion.

impl From<u128> for Value

fn from(n: u128) -> Self

Performs the conversion.

impl From<u16> for Value

fn from(n: u16) -> Self

Performs the conversion.

impl From<u32> for Value

fn from(n: u32) -> Self

Performs the conversion.

impl From<u64> for Value

fn from(n: u64) -> Self

Performs the conversion.

impl From<u8> for Value

fn from(n: u8) -> Self

Performs the conversion.

impl From<usize> for Value

fn from(n: usize) -> Self

Performs the conversion.

impl FromIterator<(String, Value)> for Value

fn from_iter<T>(iter: T) -> Self where
    T: IntoIterator<Item = (String, Value)>, 

Creates a value from an iterator.

impl FromIterator<Value> for Value

fn from_iter<T>(iter: T) -> Self where
    T: IntoIterator<Item = Value>, 

Creates a value from an iterator.

impl FromStr for Value

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<'_> TryFrom<&'_ Value> for bool

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for i8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for u64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for u128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for usize

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for f32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for f64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for i16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for i32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for i64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for i128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for isize

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for u8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for u16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_> TryFrom<&'_ Value> for u32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for String

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for bool

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for u8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for u16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for u32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for u64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for u128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for usize

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for f32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for f64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for Object

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for Array

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for i8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for i16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for i32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for i64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for i128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for isize

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Vec<u8>> for Value

type Error = Error

The type returned in the event of a conversion error.

fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.