Struct jlrs::value::Value

#[repr(transparent)]pub struct Value<'frame, 'data>(_, _, _);

Except modules, all Julia data is represented as a Value in jlrs.

A Value wraps around the raw value from the Julia C API and applies some restrictions through lifetimes to ensure it can only be used while it's protected from garbage collection and its contents are valid.

The methods that create a new Value come in two varieties: method and method_output. The first will use a slot in the current frame to protect the value from garbage collection, while the latter uses a slot in an earlier frame.

Methods

impl<'frame, 'data> Value<'frame, 'data>

pub fn new<'base, V, F>(
    frame: &mut F,
    value: V
) -> JlrsResult<Value<'frame, 'static>> where
    'base: 'frame,
    V: IntoJulia,
    F: Frame<'base, 'frame>, 

Create a new Julia value, any type that implements IntoJulia can be converted using this function. The value will be protected from garbage collection inside the frame used to create it. One free slot on the garbage collection stack is required for this function to succeed, returns an error if no slot is available.

pub fn new_output<'output, 'base, V, F>(
    frame: &mut F,
    output: Output<'output>,
    value: V
) -> Value<'output, 'static> where
    'base: 'frame,
    V: IntoJulia,
    F: Frame<'base, 'frame>, 

Create a new Julia value, any type that implements IntoJulia can be converted using this function. The value will be protected from garbage collection inside the frame used to create it. One free slot on the garbage collection stack is required for this function to succeed, returns an error if no slot is available.

pub fn is<T: JuliaType>(&self) -> bool

Returns true if the value is of type T.

pub fn is_array(&self) -> bool

Returns true if the value is an array.

pub fn is_array_of<T: JuliaType>(&self) -> bool

Returns true if the value is an array with elements of type T.

pub unsafe fn assume_owned(self) -> Value<'frame, 'static>

If you call a function with one or more borrowed arrays as arguments, its result can only be used when all the borrows are active. If this result doesn't reference any borrowed data this function can be used to relax its second lifetime to 'static.

Safety: The value must not contain a reference any borrowed data.

pub fn extend<'output, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>
) -> Value<'output, 'data> where
    'output: 'data,
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Extend the Value's lifetime to the Output's lifetime. The original value will still be valid after calling this method, the data will be protected from garbage collection until the Output`'s frame goes out of scope.

pub fn array<'base, T, D, F>(
    frame: &mut F,
    dimensions: D
) -> JlrsResult<Value<'frame, 'static>> where
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    F: Frame<'base, 'frame>, 

Allocates a new n-dimensional array in Julia.

Allocating an array with one, two, or three dimensions requires one slot on the GC stack. If you allocate an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when allocating arrays with four or more dimensions.

pub fn array_output<'output, 'base, T, D, F>(
    frame: &mut F,
    output: Output<'output>,
    dimensions: D
) -> JlrsResult<Value<'output, 'static>> where
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    F: Frame<'base, 'frame>, 

Allocates a new n-dimensional array in Julia using an Output.

Because an Output is used, no additional slot in the current frame is used. If you allocate an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when allocating arrays with four or more dimensions.

pub fn borrow_array<'base, T, D, V, F>(
    frame: &mut F,
    data: &'data mut V,
    dimensions: D
) -> JlrsResult<Value<'frame, 'data>> where
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    V: AsMut<[T]>,
    F: Frame<'base, 'frame>, 

Borrows an n-dimensional array from Rust for use in Julia.

Borrowing an array with one dimension requires one slot on the GC stack. If you borrow an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when borrowing arrays with two or more dimensions.

This function is unsafe to call because you must ensure that the lifetime of this value is never extended through an Output by returning it from a Julia function, is never assigned to a global in Julia, and is never referenced from a value with a longer lifetime in Julia.

pub fn borrow_array_output<'output, 'borrow, 'base, T, D, V, F>(
    frame: &mut F,
    output: Output<'output>,
    data: &'borrow mut V,
    dimensions: D
) -> JlrsResult<Value<'output, 'borrow>> where
    'borrow: 'output,
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    V: AsMut<[T]>,
    F: Frame<'base, 'frame>, 

Borrows an n-dimensional array from Rust for use in Julia using an Output.

Because an Output is used, no additional slot in the current frame is used. If you borrow an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when borrowing arrays with two or more dimensions.

This function is unsafe to call because you must ensure that the lifetime of this value is never extended through an Output by returning it from a Julia function, is never assigned to a global in Julia, and is never referenced from a value with a longer lifetime in Julia.

pub fn move_array<'base, T, D, F>(
    frame: &mut F,
    data: Vec<T>,
    dimensions: D
) -> JlrsResult<Value<'frame, 'static>> where
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    F: Frame<'base, 'frame>, 

Moves an n-dimensional array from Rust to Julia using an Output.

Because an Output is used, no additional slot in the current frame is used. If you move an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when moving arrays with two or more dimensions.

pub fn move_array_output<'output, 'base, T, D, F>(
    frame: &mut F,
    output: Output<'output>,
    data: Vec<T>,
    dimensions: D
) -> JlrsResult<Value<'output, 'static>> where
    'base: 'frame,
    T: JuliaType,
    D: Into<Dimensions>,
    F: Frame<'base, 'frame>, 

Moves an n-dimensional array from Rust to Julia.

Moving an array with one dimension requires one slot on the GC stack. If you move an array with more dimensions, an extra frame is created with n + 1 slots, temporarily taking n + 3 additional slots. This latter case requires that jlrs.jl has been included.

This function returns an error if there are not enough slots available, or if jlrs.jl has not been included when moving arrays with two or more dimensions.

pub fn try_unbox<'base, T>(self) -> JlrsResult<T> where
    'base: 'frame,
    T: TryUnbox, 

Try to copy data from Julia to Rust. You can only copy data if the output type implements TryUnbox; this trait is implemented by all types that implement IntoJulia and arrays whose contents implement ArrayData through Array. Returns an error if the requested type does not match the actual type of the data.

pub fn call0<'base, F>(
    self,
    frame: &mut F
) -> JlrsResult<Value<'frame, 'static>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes zero arguments, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call0_output<'output, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>
) -> JlrsResult<Value<'output, 'static>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes zero arguments and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

pub fn call1<'borrow, 'base, F>(
    self,
    frame: &mut F,
    arg: Value<'_, 'borrow>
) -> JlrsResult<Value<'frame, 'borrow>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes one argument, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call1_output<'output, 'borrow, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>,
    arg: Value<'_, 'borrow>
) -> JlrsResult<Value<'output, 'borrow>> where
    'borrow: 'output,
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes one argument and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

pub fn call2<'borrow, 'base, F>(
    self,
    frame: &mut F,
    arg0: Value<'_, 'borrow>,
    arg1: Value<'_, 'borrow>
) -> JlrsResult<Value<'frame, 'borrow>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes two arguments, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call2_output<'output, 'borrow, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>,
    arg0: Value<'_, 'borrow>,
    arg1: Value<'_, 'borrow>
) -> JlrsResult<Value<'output, 'borrow>> where
    'borrow: 'output,
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes two arguments and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

pub fn call3<'borrow, 'base, F>(
    self,
    frame: &mut F,
    arg0: Value<'_, 'borrow>,
    arg1: Value<'_, 'borrow>,
    arg2: Value<'_, 'borrow>
) -> JlrsResult<Value<'frame, 'borrow>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes three arguments, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call3_output<'output, 'borrow, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>,
    arg0: Value<'_, 'borrow>,
    arg1: Value<'_, 'borrow>,
    arg2: Value<'_, 'borrow>
) -> JlrsResult<Value<'output, 'borrow>> where
    'borrow: 'output,
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes three arguments and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

pub fn call<'value, 'borrow, 'base, V, F>(
    self,
    frame: &mut F,
    args: V
) -> JlrsResult<Value<'frame, 'borrow>> where
    'base: 'frame,
    V: AsRef<[Value<'value, 'borrow>]>,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes several arguments, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call_output<'output, 'value, 'borrow, 'base, V, F>(
    self,
    frame: &mut F,
    output: Output<'output>,
    args: V
) -> JlrsResult<Value<'output, 'static>> where
    'borrow: 'output,
    'base: 'frame,
    V: AsRef<[Value<'value, 'borrow>]>,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes several arguments and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

pub fn call_values<'base, F>(
    self,
    frame: &mut F,
    args: Values
) -> JlrsResult<Value<'frame, 'static>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes several arguments in a single Values, this takes one slot on the GC stack. Returns the result of this function call if no exception is thrown, the exception if one is, or an error if no space is left on the stack.

pub fn call_values_output<'output, 'base, F>(
    self,
    frame: &mut F,
    output: Output<'output>,
    args: Values
) -> JlrsResult<Value<'output, 'static>> where
    'base: 'frame,
    F: Frame<'base, 'frame>, 

Call this value as a function that takes several arguments in a single Values and use the Output to extend the result's lifetime. This takes no space on the GC stack. Returns the result of this function call if no exception is thrown or the exception if one is.

Trait Implementations

impl<'frame, 'data> Clone for Value<'frame, 'data>

fn clone(&self) -> Value<'frame, 'data>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'frame, 'data> Copy for Value<'frame, 'data>