Struct starlark::values::Value

pub struct Value<'v>(_);

A Starlark value. The lifetime argument 'v corresponds to the Heap it is stored on.

Many of the methods simply forward to the underlying StarlarkValue. The Display trait is equivalent to the repr() function in Starlark.

Implementations

impl<'v> Value<'v>

pub fn new_none() -> Self

Create a new None value.

pub fn new_bool(x: bool) -> Self

Create a new boolean.

pub fn new_int(x: i32) -> Self

Create a new integer.

pub fn new_frozen(x: FrozenValue) -> Self

Turn a FrozenValue into a Value. See the safety warnings on OwnedFrozenValue.

pub fn unpack_frozen(self) -> Option<FrozenValue>

Obtain the underlying FrozenValue from inside the Value, if it is one.

pub fn is_none(self) -> bool

Is this value None.

pub fn unpack_num(self) -> Option<Num>

Obtain the underlying numerical value, if it is one.

pub fn unpack_bool(self) -> Option<bool>

Obtain the underlying bool if it is a boolean.

pub fn unpack_int(self) -> Option<i32>

Obtain the underlying int if it is an integer.

pub fn unpack_starlark_str(self) -> Option<&'v StarlarkStr>

Like unpack_str, but gives a pointer to a boxed string. Mostly useful for when you want to convert the string to a dyn trait, but can’t form a dyn of an unsized type.

Unstable and likely to be removed in future, as the presence of the Box is not a guaranteed part of the API.

pub fn unpack_str(self) -> Option<&'v str>

Obtain the underlying str if it is a string.

pub fn ptr_eq(self, other: Self) -> bool

Are two Values equal, looking at only their underlying pointer. This function is low-level and provides two guarantees.

1. It is reflexive, the same Value passed as both arguments will result in true.
2. If this function is true, then Value::equals will also consider them equal.

Note that other properties are not guaranteed, and the result is not considered part of the API. The result can be impacted by optimisations such as hash-consing, copy-on-write, partial evaluation etc.

pub fn identity(self) -> ValueIdentity<'v>

Returns an identity for this Value, derived from its pointer. This function is low-level and provides two guarantees. Those are valid until the next GC:

1. Calling it mulitple times on the same Value will return ValueIdentity that compare equal.
2. If two [Value] have ValueIdentity that compare equal, then Value::ptr_eq and Value::equals will also consider them to be equal.

pub fn get_type(self) -> &'static str

type(x).

pub fn to_bool(self) -> bool

bool(x).

pub fn to_int(self) -> Result<i32>

int(x).

pub fn at(self, index: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x[index].

pub fn slice(
    self,
    start: Option<Value<'v>>,
    stop: Option<Value<'v>>,
    stride: Option<Value<'v>>,
    heap: &'v Heap
) -> Result<Value<'v>>

x[start:stop:stride].

pub fn length(self) -> Result<i32>

len(x).

pub fn is_in(self, other: Value<'v>) -> Result<bool>

other in x.

pub fn plus(self, heap: &'v Heap) -> Result<Value<'v>>

+x.

pub fn minus(self, heap: &'v Heap) -> Result<Value<'v>>

-x.

pub fn sub(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x - other.

pub fn mul(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x * other.

pub fn percent(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x % other.

pub fn div(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x / other.

pub fn floor_div(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x // other.

pub fn bit_and(self, other: Value<'v>) -> Result<Value<'v>>

x & other.

pub fn bit_or(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

x | other.

pub fn bit_xor(self, other: Value<'v>) -> Result<Value<'v>>

x ^ other.

pub fn left_shift(self, other: Value<'v>) -> Result<Value<'v>>

x << other.

pub fn right_shift(self, other: Value<'v>) -> Result<Value<'v>>

x >> other.

pub fn invoke(
    self,
    args: &Arguments<'v, '_>,
    eval: &mut Evaluator<'v, '_>
) -> Result<Value<'v>>

Invoke self with given arguments.

pub fn invoke_pos(
    self,
    pos: &[Value<'v>],
    eval: &mut Evaluator<'v, '_>
) -> Result<Value<'v>>

Invoke a function with only positional arguments.

pub fn get_type_value(self) -> FrozenStringValue

type(x).

pub fn add(self, other: Value<'v>, heap: &'v Heap) -> Result<Value<'v>>

Add two Values together. Will first try using radd, before falling back to add.

pub fn freeze(self, freezer: &Freezer) -> Result<FrozenValue>

Convert a value to a FrozenValue using a supplied Freezer.

pub fn to_str(self) -> String

Implement the str() function - converts a string value to itself, otherwise uses repr().

pub fn to_repr(self) -> String

Implement the repr() function.

pub fn to_json(self) -> Result<String>

Convert the value to JSON.

Return an error if the value or any contained value does not support conversion to JSON.

pub fn set_attr(self, attribute: &str, alloc_value: Value<'v>) -> Result<()>

Forwards to StarlarkValue::set_attr.

pub fn set_at(self, index: Value<'v>, alloc_value: Value<'v>) -> Result<()>

Forwards to StarlarkValue::set_at.

pub fn documentation(self) -> Option<DocItem>

Forwards to StarlarkValue::documentation.

pub fn iterate_collect(self, heap: &'v Heap) -> Result<Vec<Value<'v>>>

Return the contents of an iterable collection, as an owned vector.

pub fn with_iterator<T>(
    self,
    heap: &'v Heap,
    f: impl FnMut(&mut dyn Iterator<Item = Value<'v>>) -> T
) -> Result<T>

Operate over an iterable for a value.

pub fn iterate(
    self,
    heap: &'v Heap
) -> Result<Box<dyn Iterator<Item = Value<'v>> + 'v>>

Produce an iterable from a value.

pub fn get_hashed(self) -> Result<Hashed<Self>>

Get the Hashed version of this Value.

pub fn equals(self, other: Value<'v>) -> Result<bool>

Are two values equal. If the values are of different types it will return false. It will only error if there is excessive recursion.

pub fn compare(self, other: Value<'v>) -> Result<Ordering>

How are two values comparable. For values of different types will return Err.

pub fn describe(self, name: &str) -> String

Describe the value, in order to get its metadata in a way that could be used to generate prototypes, help information or whatever other descriptive text is required. Plan is to make this return a data type at some point in the future, possibly move on to StarlarkValue and include data from members.

pub fn export_as(self, variable_name: &str, eval: &mut Evaluator<'v, '_>)

Call export_as on the underlying value, but only if the type is mutable. Otherwise, does nothing.

pub fn get_attr(
    self,
    attribute: &str,
    heap: &'v Heap
) -> Result<Option<Value<'v>>>

Return the attribute with the given name.

pub fn get_attr_error(
    self,
    attribute: &str,
    heap: &'v Heap
) -> Result<Value<'v>>

Like get_attr but return an error if the attribute is not available.

pub fn has_attr(self, attribute: &str) -> bool

Query whether an attribute exists on a type. Should be equivalent to whether get_attr succeeds, but potentially more efficient.

pub fn dir_attr(self) -> Vec<String>

Get a list of all the attributes this function supports, used to implement the dir() function.

Trait Implementations

impl<'v> AllocValue<'v> for Value<'v>

fn alloc_value(self, _heap: &'v Heap) -> Value<'v>

Allocate the value on a heap and return a reference to the allocated value.

impl<'v> Clone for Value<'v>

fn clone(&self) -> Self

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 Default for Value<'_>

fn default() -> Self

Returns the “default value” for a type.

impl Display for Value<'_>

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

Formats the value using the given formatter.

impl<'v> Dupe for Value<'v>

fn dupe(&self) -> Self

impl Equivalent<FrozenValue> for Value<'_>

fn equivalent(&self, key: &FrozenValue) -> bool

Compare self to key and return true if they are equal.

impl Equivalent<Value<'_>> for FrozenValue

fn equivalent(&self, key: &Value<'_>) -> bool

Compare self to key and return true if they are equal.

impl<'v> Equivalent<Value<'v>> for ValueStr<'_>

fn equivalent(&self, key: &Value<'v>) -> bool

Compare self to key and return true if they are equal.

impl<'v> Freeze for Value<'v>

type Frozen = FrozenValue

When type is frozen, it is frozen into this type.

fn freeze(self, freezer: &Freezer) -> Result<FrozenValue>

Freeze a value. The frozen value must be equal to the original, and produce the same hash.

impl<'v> PartialEq<Value<'v>> for Value<'v>

fn eq(&self, other: &Value<'v>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'v> ProvidesStaticType for Value<'v>

type StaticType = Value<'static>

Same type as Self but with lifetimes dropped to 'static.

impl<'v> Serialize for Value<'v>

fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'v> Trace<'v> for Value<'v>

fn trace(&mut self, tracer: &Tracer<'v>)

Recursively “trace” the value.

impl<'v> UnpackValue<'v> for Value<'v>

fn expected() -> String

Description of values acceptable by unpack_value, e. g. list or str.

fn unpack_value(value: Value<'v>) -> Option<Self>

Given a Value, try and unpack it into the given type, which may involve some element of conversion. The heap argument is usually not required.

fn unpack_param(value: Value<'v>) -> Result<Self>

Unpack value, but instead of None return error about incorrect argument type.

fn unpack_named_param(value: Value<'v>, param_name: &str) -> Result<Self>

Unpack value, but instead of None return error about incorrect named argument type.

impl<'v> ValueLike<'v> for Value<'v>

type String = StringValue<'v>

StringValue or FrozenStringValue.

fn to_value(self) -> Value<'v>

Produce a Value regardless of the type you are starting with.

fn downcast_ref<T: StarlarkValue<'v>>(self) -> Option<&'v T>

Get a reference to underlying data or None if contained object has different type than requested.

fn collect_repr(self, collector: &mut String)

repr(x).

fn write_hash(self, hasher: &mut StarlarkHasher) -> Result<()>

Hash the value.

fn equals(self, other: Value<'v>) -> Result<bool>

x == other.

fn compare(self, other: Value<'v>) -> Result<Ordering>

x <=> other.

fn as_dyn_any(self) -> &'v dyn AnyLifetime<'v>

Get referenced StarlarkValue a value as AnyLifetime.

fn invoke(
    self,
    args: &Arguments<'v, '_>,
    eval: &mut Evaluator<'v, '_>
) -> Result<Value<'v>>

Call this value as a function with given arguments.

fn get_hashed(self) -> Result<Hashed<Self>>

Get hash value.

fn collect_str(self, collector: &mut String)

str(x).

impl<'v> Coerce<Value<'v>> for StringValue<'v>

impl<'v> Coerce<Value<'v>> for Value<'v>

impl<'v> Coerce<Value<'v>> for FrozenValue

impl<'v> CoerceKey<Value<'v>> for StringValue<'v>

impl<'v> CoerceKey<Value<'v>> for Value<'v>

impl<'v> CoerceKey<Value<'v>> for FrozenValue

impl<'v> Copy for Value<'v>

impl Eq for Value<'_>