Trait starlark::values::StarlarkValue

source · [−]
pub trait StarlarkValue<'v>: 'v + AnyLifetime<'v> + Debug + Display + Serialize {

Show 40 methods    fn get_type(&self) -> &'static str;
    fn get_type_value_static() -> FrozenStringValue
    where
        Self: Sized;

    fn matches_type(&self, ty: &str) -> bool { ... }
    fn get_methods(&self) -> Option<&'static Methods> { ... }
    fn documentation(&self) -> Option<DocItem> { ... }
    fn collect_repr(&self, collector: &mut String) { ... }
    fn collect_repr_cycle(&self, collector: &mut String) { ... }
    fn to_bool(&self) -> bool { ... }
    fn to_int(&self) -> Result<i32> { ... }
    fn write_hash(&self, hasher: &mut StarlarkHasher) -> Result<()> { ... }
    fn extra_memory(&self) -> usize { ... }
    fn equals(&self, _other: Value<'v>) -> Result<bool> { ... }
    fn compare(&self, other: Value<'v>) -> Result<Ordering> { ... }
    fn invoke(
        &self, 
        _me: Value<'v>, 
        _args: &Arguments<'v, '_>, 
        _eval: &mut Evaluator<'v, '_>
    ) -> Result<Value<'v>> { ... }
    fn at(&self, index: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn slice(
        &self, 
        _start: Option<Value<'v>>, 
        _stop: Option<Value<'v>>, 
        _stride: Option<Value<'v>>, 
        _heap: &'v Heap
    ) -> Result<Value<'v>> { ... }
    fn iterate<'a>(
        &'a self, 
        _heap: &'v Heap
    ) -> Result<Box<dyn Iterator<Item = Value<'v>> + 'a>>
    where
        'v: 'a,
    { ... }
    fn with_iterator(
        &self, 
        heap: &'v Heap, 
        f: &mut dyn FnMut(&mut dyn Iterator<Item = Value<'v>>) -> Result<()>
    ) -> Result<()> { ... }
    fn length(&self) -> Result<i32> { ... }
    fn get_attr(&self, _attribute: &str, _heap: &'v Heap) -> Option<Value<'v>> { ... }
    fn has_attr(&self, _attribute: &str) -> bool { ... }
    fn dir_attr(&self) -> Vec<String>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
    A: Allocator,  { ... }
    fn is_in(&self, other: Value<'v>) -> Result<bool> { ... }
    fn plus(&self, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn minus(&self, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn radd(
        &self, 
        _lhs: Value<'v>, 
        _heap: &'v Heap
    ) -> Option<Result<Value<'v>>> { ... }
    fn add(&self, rhs: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn sub(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn mul(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn div(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn percent(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn floor_div(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn bit_and(&self, other: Value<'v>) -> Result<Value<'v>> { ... }
    fn bit_or(&self, other: Value<'v>, _heap: &'v Heap) -> Result<Value<'v>> { ... }
    fn bit_xor(&self, other: Value<'v>) -> Result<Value<'v>> { ... }
    fn left_shift(&self, other: Value<'v>) -> Result<Value<'v>> { ... }
    fn right_shift(&self, other: Value<'v>) -> Result<Value<'v>> { ... }
    fn export_as(&self, _variable_name: &str, _eval: &mut Evaluator<'v, '_>) { ... }
    fn set_at(&self, _index: Value<'v>, _new_value: Value<'v>) -> Result<()> { ... }
    fn set_attr(&self, attribute: &str, _new_value: Value<'v>) -> Result<()> { ... }

}
Expand description

How to put a Rust values into Values.

Every Rust value stored in a Value must implement this trait. You must also implement ComplexValue if:

  • A type is mutable, if you ever need to get a &mut self reference to it.
  • A type contains nested Starlark Values.

There are only two required methods of StarlarkValue, namely get_type and get_type_value_static. Both these should be implemented with the starlark_type! macro:

use starlark::values::StarlarkValue;
use starlark::values::AnyLifetime;
use starlark::values::NoSerialize;
use starlark::starlark_type;
use derive_more::Display;

#[derive(Debug, Display, AnyLifetime, NoSerialize)]
#[display(fmt = "Foo")]
struct Foo;
impl<'v> StarlarkValue<'v> for Foo {
    starlark_type!("foo");
}

Every additional field enables further features in Starlark. In most cases the default implementation returns an “unimplemented” Err.

Note To Implementors

Any additional methods that are added to this trait also need to be added to the StarlarkValue implementation in crate::values::layout::avalue::Wrapper. Otherwise, any implementations other than the default implementation will not be run.

Required methods

Return a string describing the type of self, as returned by the type() function.

Usually implemented by the starlark_type! macro.

Like get_type, but returns a reusable FrozenStringValue pointer to it. This function deliberately doesn’t take a heap, as it would not be performant to allocate a new value each time.

Usually implemented by the starlark_type! macro.

Provided methods

Is this value a match for a named type. Usually returns true for values matching get_type, but might also work for subtypes it implements.

Get the members associated with this type, accessible via this_type.x. These members will have dir/getattr/hasattr properly implemented, so it is the preferred way to go if possible. See MethodsStatic for an example of how to define this method.

Return structured documentation for self, if available.

Return a string representation of self, as returned by the repr() function. Defaults to the Display instance - which should be fine for nearly all types. In many cases the repr() representation will also be a Starlark expression for creating the value.

Examples:
repr("test") == '"test"'
repr([1,2,3]) == '[1, 2, 3]'
repr([1,[2,3]]) == '[1, [2, 3]]'
repr([1]) == '[1]'
repr([]) == '[]'

Invoked to print repr when a cycle is the object stack is detected.

Convert self to a boolean, as returned by the bool() function. The default implementation returns true.

Convert self to a integer value, as returned by the int() function if the type is numeric (not for string). Works for int and bool (0 = false, 1 = true).

Return a hash data for self to be used when self is placed as a key in a Dict. Return an Err if there is no hash for this value (e.g. list). Must be stable between frozen and non-frozen values.

Return how much extra memory is consumed by this data type, in bytes, in addition to the direct size_of measurements. Used for profiling, so best effort rather than precise. Defaults to 0. Should not reported any memory held on to by a Value.

Compare self with other for equality. Should only return an error on excessive recursion.

This function can only be called when it is known that self pointer is not equal to the other pointer. Thus, an implementation may assume that the pointers are not equal. Implementation of equals for some builtin types and default implementation rely on this assumption.

Compare self with other. This method returns a result of type Ordering, or an Err if the two types differ.

Directly invoke a function. The number of named and names arguments are guaranteed to be equal.

Return the result of a[index] if a is indexable.

Extract a slice of the underlying object if the object is indexable. The result will be object between start and stop (both of them are added length() if negative and then clamped between 0 and length()). stride indicates the direction.

Parameters
  • start: the start of the slice.
  • stop: the end of the slice.
  • stride: the direction of slice,
Examples
'abc'[1:] == 'bc'         # Remove the first element
'abc'[:-1] == 'ab'        # Remove the last element
'abc'[1:-1] == 'b'        # Remove the first and the last element
'abc'[-1:] == 'c'         # Take the last letter
'abc'[:1] == 'a'          # Take the first letter
'banana'[1::2] == 'aaa'   # Select one element out of 2, skipping the first
'banana'[4::-2] == 'nnb'  # Select one element out of 2 in reverse order, starting at index 4

Returns an iterable over the value of this container if this value holds an iterable container.

Call a function with the same iterator as would be returned from iterate. The one advantage is that the iterator does not need to be allocated in a Box. If you implement this function you must also implement iterate, but the reverse is not true (this function has a sensible default).

Returns the length of the value, if this value is a sequence.

Get an attribute for the current value as would be returned by dotted expression (i.e. a.attribute).

The three methods get_attr, has_attr and dir_attr must be consistent - if you implement one, you should probably implement all three.

This operations must have no side effects, because it can be called speculatively.

Return true if an attribute of name attribute exists for the current value.

The three methods get_attr, has_attr and dir_attr must be consistent - if you implement one, you should probably implement all three.

Return a vector of string listing all attribute of the current value.

The three methods get_attr, has_attr and dir_attr must be consistent - if you implement one, you should probably implement all three.

Tell wether other is in the current value, if it is a container.

Examples
('a' in 'abc') == True
('b' in 'abc') == True
('z' in 'abc') == False

Apply the + unary operator to the current value.

Examples
+1 == 1

Apply the - unary operator to the current value.

Examples
-(1) == -1

Add with the arguments the other way around. Should return None to fall through to normal add.

Add other to the current value. Pass both self and the Value form of self as original.

Examples
1 + 2 == 3
[1, 2, 3] + [2, 3] == [1, 2, 3, 2, 3]
'abc' + 'def' == 'abcdef'
(1, 2, 3) + (2, 3) == (1, 2, 3, 2, 3)

Substract other from the current value.

Examples
1 - 2 == -1

Multiply the current value with other.

Examples
2 * 3 == 6
[1, 2, 3] * 3 == [1, 2, 3, 1, 2, 3, 1, 2, 3]
'abc' * 3 == 'abcabcabc'
(1, 2, 3) * 3 == (1, 2, 3, 1, 2, 3, 1, 2, 3)

Divide the current value by other. Always results in a float value.

Examples
4 / 2.0 == 2.0
7 / 2 == 3.5

Apply the percent operator between the current value and other. Usually used on strings, as per the Starlark spec.

Examples
5 % 3 == 2
-5 % -3 == -2
5 % -3 == -1
-5 % 3 == 1
5.5 % 3.0 == 2.5
-5.5 % 3.0 == 0.5
5.5 % -3.0 == -0.5
-5.5 % -3.0 == -2.5
"a %s c" % 3 == "a 3 c"
"Hello %s, your score is %d" % ("Bob", 75) == "Hello Bob, your score is 75"
"%d %o %x" % (65, 65, 65) == "65 101 41"
"Hello %s, welcome" % "Bob" == "Hello Bob, welcome"
"%s" % (1,) == "1"
"%s" % ((1,),) == "(1,)"
"%s" % [1] == "[1]"
"test" % () == "test"

Floor division between the current value and other.

Examples
7 // 2 == 3
-7 // -2 == 3
7 // -2 == -4
-7 // 2 == -4
7.0 // 2.0 == 3.0
-7.0 // -2.0 == 3.0
7.0 // -2.0 == -4.0
-7.0 // 2.0 == -4.0
3.0 // 2.0 == 1.0

Bitwise & operator.

Bitwise | operator.

Examples
0xb00f | 0x0ee0 == 0xbeef
4 | 7 == 7
{1: 2} | {3: 4} == {1: 2, 3: 4}
{1: 2} | {1: 3} == {1: 3}

Bitwise ^ operator.

Bitwise << operator.

Bitwise >> operator.

Called when exporting a value under a specific name,

Set the value at index with the new value.

v = [1, 2, 3]
v[1] = 1
v[2] = [2,3]
v == [1, 1, [2, 3]]

Set the attribute named attribute of the current value to value (e.g. a.attribute = value).

Trait Implementations

Serialize this value into the given Serde serializer. Read more

Serialize this value into the given Serde serializer. Read more

Serialize this value into the given Serde serializer. Read more

Serialize this value into the given Serde serializer. Read more

Implementations on Foreign Types

Implementors

Define the function type

Define the NoneType type