Struct Record

pub struct Record { /* private fields */ }

Implementations

impl Record

pub fn new() -> Self

pub fn with_capacity(capacity: usize) -> Self

pub fn from_raw_cols_vals( cols: Vec<String>, vals: Vec<Value>, input_span: Span, creation_site_span: Span, ) -> Result<Self, ShellError>

Create a Record from a Vec of columns and a Vec of Values

Returns an error if cols and vals have different lengths.

For perf reasons, this will not validate the rest of the record assumptions:

• unique keys

pub fn iter(&self) -> Iter<'_>

pub fn iter_mut(&mut self) -> IterMut<'_>

pub fn is_empty(&self) -> bool

pub fn len(&self) -> usize

pub fn push(&mut self, col: impl Into<String>, val: Value)

Naive push to the end of the datastructure.

May duplicate data!

Consider to use Record::insert instead

pub fn insert<K>(&mut self, col: K, val: Value) -> Option<Value>

where K: AsRef<str> + Into<String>,

Insert into the record, replacing preexisting value if found.

Returns Some(previous_value) if found. Else None

pub fn contains(&self, col: impl AsRef<str>) -> bool

pub fn index_of(&self, col: impl AsRef<str>) -> Option<usize>

pub fn get(&self, col: impl AsRef<str>) -> Option<&Value>

pub fn get_mut(&mut self, col: impl AsRef<str>) -> Option<&mut Value>

pub fn get_index(&self, idx: usize) -> Option<(&String, &Value)>

pub fn remove(&mut self, col: impl AsRef<str>) -> Option<Value>

Remove single value by key

Returns None if key not found

Note: makes strong assumption that keys are unique

pub fn retain<F>(&mut self, keep: F)

where F: FnMut(&str, &Value) -> bool,

Remove elements in-place that do not satisfy keep

use nu_protocol::{record, Value};

let mut rec = record!(
    "a" => Value::test_nothing(),
    "b" => Value::test_int(42),
    "c" => Value::test_nothing(),
    "d" => Value::test_int(42),
);
rec.retain(|_k, val| !val.is_nothing());
let mut iter_rec = rec.columns();
assert_eq!(iter_rec.next().map(String::as_str), Some("b"));
assert_eq!(iter_rec.next().map(String::as_str), Some("d"));
assert_eq!(iter_rec.next(), None);

pub fn retain_mut<F>(&mut self, keep: F)

where F: FnMut(&str, &mut Value) -> bool,

Remove elements in-place that do not satisfy keep while allowing mutation of the value.

This can for example be used to recursively prune nested records.

use nu_protocol::{record, Record, Value};

fn remove_foo_recursively(val: &mut Value) {
    if let Value::Record {val, ..} = val {
        val.to_mut().retain_mut(keep_non_foo);
    }
}

fn keep_non_foo(k: &str, v: &mut Value) -> bool {
    if k == "foo" {
        return false;
    }
    remove_foo_recursively(v);
    true
}

let mut test = Value::test_record(record!(
    "foo" => Value::test_nothing(),
    "bar" => Value::test_record(record!(
        "foo" => Value::test_nothing(),
        "baz" => Value::test_nothing(),
        ))
    ));

remove_foo_recursively(&mut test);
let expected = Value::test_record(record!(
    "bar" => Value::test_record(record!(
        "baz" => Value::test_nothing(),
        ))
    ));
assert_eq!(test, expected);

pub fn truncate(&mut self, len: usize)

Truncate record to the first len elements.

len > self.len() will be ignored

use nu_protocol::{record, Value};

let mut rec = record!(
    "a" => Value::test_nothing(),
    "b" => Value::test_int(42),
    "c" => Value::test_nothing(),
    "d" => Value::test_int(42),
);
rec.truncate(42); // this is fine
assert_eq!(rec.columns().map(String::as_str).collect::<String>(), "abcd");
rec.truncate(2); // truncate
assert_eq!(rec.columns().map(String::as_str).collect::<String>(), "ab");
rec.truncate(0); // clear the record
assert_eq!(rec.len(), 0);

pub fn columns(&self) -> Columns<'_>

pub fn into_columns(self) -> IntoColumns

pub fn values(&self) -> Values<'_>

pub fn into_values(self) -> IntoValues

pub fn drain<R>(&mut self, range: R) -> Drain<'_>

where R: RangeBounds<usize> + Clone,

Obtain an iterator to remove elements in range

Elements not consumed from the iterator will be dropped

use nu_protocol::{record, Value};

let mut rec = record!(
    "a" => Value::test_nothing(),
    "b" => Value::test_int(42),
    "c" => Value::test_string("foo"),
);
{
    let mut drainer = rec.drain(1..);
    assert_eq!(drainer.next(), Some(("b".into(), Value::test_int(42))));
    // Dropping the `Drain`
}
let mut rec_iter = rec.into_iter();
assert_eq!(rec_iter.next(), Some(("a".into(), Value::test_nothing())));
assert_eq!(rec_iter.next(), None);

pub fn sort_cols(&mut self)

Sort the record by its columns.

use nu_protocol::{record, Value};

let mut rec = record!(
    "c" => Value::test_string("foo"),
    "b" => Value::test_int(42),
    "a" => Value::test_nothing(),
);

rec.sort_cols();

assert_eq!(
    Value::test_record(rec),
    Value::test_record(record!(
        "a" => Value::test_nothing(),
        "b" => Value::test_int(42),
        "c" => Value::test_string("foo"),
    ))
);

Trait Implementations

impl Clone for Record

fn clone(&self) -> Record

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Record

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

Formats the value using the given formatter.

impl Default for Record

fn default() -> Record

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Record

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Special deserialization implementation that turns a map-pattern into a Record

Denies duplicate keys

use serde_json::{from_str, Result};
use nu_protocol::{Record, Value, record};

// A `Record` in json is a Record with a packed `Value`
// The `Value` record has a single key indicating its type and the inner record describing
// its representation of value and the associated `Span`
let ok = r#"{"a": {"Int": {"val": 42, "span": {"start": 0, "end": 0}}},
             "b": {"Int": {"val": 37, "span": {"start": 0, "end": 0}}}}"#;
let ok_rec: Record = from_str(ok).unwrap();
assert_eq!(Value::test_record(ok_rec),
           Value::test_record(record!{"a" => Value::test_int(42),
                                      "b" => Value::test_int(37)}));
// A repeated key will lead to a deserialization error
let bad = r#"{"a": {"Int": {"val": 42, "span": {"start": 0, "end": 0}}},
              "a": {"Int": {"val": 37, "span": {"start": 0, "end": 0}}}}"#;
let bad_rec: Result<Record> = from_str(bad);
assert!(bad_rec.is_err());

impl Extend<(String, Value)> for Record

fn extend<T: IntoIterator<Item = (String, Value)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromIterator<(String, Value)> for Record

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

Creates a value from an iterator.

impl FromValue for Record

fn from_value(v: Value) -> Result<Self, ShellError>

Loads a value from a Value.

fn expected_type() -> Type

Expected Value type.

impl<'a> IntoIterator for &'a Record

type Item = (&'a String, &'a Value)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Record

type Item = (&'a String, &'a mut Value)

The type of the elements being iterated over.

type IntoIter = IterMut<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Record

type Item = (String, Value)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoValue for Record

fn into_value(self, span: Span) -> Value

Converts the given value to a Value.

impl Serialize for Record

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.