Struct PropertyOptions 

pub struct PropertyOptions(/* private fields */);

Options controlling how a property lookup or mutation behaves (PropOption_*).

A bitmask, not an enumeration: the engine combines flags. Passing PropertyOptions::NONE requests the default behavior.

Several names share a bit because the engine reuses it per context (for example Self::INSERT_IF_MISSING and Self::INSERT_ELEMENT); the name documents intent at the call site.

use rs_teststand::PropertyOptions;

let options = PropertyOptions::INSERT_IF_MISSING | PropertyOptions::COERCE_TO_STRING;
assert!(options.contains(PropertyOptions::INSERT_IF_MISSING));
assert!(PropertyOptions::NONE.is_empty());

Implementations

impl PropertyOptions

pub const NONE: Self

Default behavior (PropOption_NoOptions).

pub const INSERT_IF_MISSING: Self

Create the property if it does not exist (PropOption_InsertIfMissing).

pub const INSERT_ELEMENT: Self

Insert an array element (PropOption_InsertElement).

pub const DELETE_IF_EXISTS: Self

Delete the property if it exists (PropOption_DeleteIfExists).

pub const REMOVE_ELEMENT: Self

Remove an array element (PropOption_RemoveElement).

pub const DO_NOTHING_IF_EXISTS: Self

Leave an existing property untouched (PropOption_DoNothingIfExists).

pub const SET_ONLY_IF_DOES_NOT_EXIST: Self

Set only when the property does not already exist (PropOption_SetOnlyIfDoesNotExist).

pub const COERCE_FROM_NUMBER: Self

Convert from a number (PropOption_CoerceFromNumber).

pub const COERCE_FROM_STRING: Self

Convert from a string (PropOption_CoerceFromString).

pub const COERCE_TO_ENUM: Self

Convert to an enum (PropOption_CoerceToEnum).

pub const COERCE_FROM_BOOLEAN: Self

Convert from a boolean (PropOption_CoerceFromBoolean).

pub const COERCE_TO_NUMBER: Self

Convert to a number (PropOption_CoerceToNumber).

pub const COERCE_TO_STRING: Self

Convert to a string (PropOption_CoerceToString).

pub const COERCE_FROM_ENUM: Self

Convert from an enum (PropOption_CoerceFromEnum).

pub const COERCE_TO_BOOLEAN: Self

Convert to a boolean (PropOption_CoerceToBoolean).

pub const NOT_OWNING: Self

Do not take ownership (PropOption_NotOwning).

pub const REFER_TO_ALIAS: Self

Resolve to the alias rather than its target (PropOption_ReferToAlias).

pub const DO_NOT_ADOPT_CURRENT_NAME: Self

Keep the existing name when copying (PropOption_DoNotAdoptCurrentName).

pub const CASE_INSENSITIVE: Self

Match names case-insensitively (PropOption_CaseInsensitive).

pub const REQUIRE_IDENTICAL_STRUCTURE: Self

Require an identical structure (PropOption_RequireIdenticalStructure).

pub const DO_NOT_RECURSE: Self

Do not recurse into subproperties (PropOption_DoNotRecurse).

pub const COERCE_FROM_REFERENCE: Self

Convert from a reference (PropOption_CoerceFromReference).

pub const COERCE_TO_REFERENCE: Self

Convert to a reference (PropOption_CoerceToReference).

pub const COERCE: Self

Every conversion flag (PropOption_Coerce).

pub const COERCE_BAD_NUMBERS_TO_ZERO: Self

Treat unusable numbers as zero (PropOption_CoerceBadNumbersToZero).

pub const OVERRIDE_NOT_DELETABLE: Self

Allow deleting an otherwise protected property (PropOption_OverrideNotDeletable).

pub const DO_NOT_SHARE_PROPERTIES: Self

Copy rather than share subproperties (PropOption_DoNotShareProperties).

pub const COPY_ALL_FLAGS: Self

Copy every flag (PropOption_CopyAllFlags).

impl PropertyOptions

pub const fn empty() -> Self

Get a flags value with all bits unset.

pub const fn all() -> Self

Get a flags value with all known bits set.

pub const fn bits(&self) -> i32

Get the underlying bits value.

The returned value is exactly the bits set in this flags value.

Examples found in repository

examples/execution_run_subsequence.rs (line 36)

const fn none() -> i32 {
    PropertyOptions::NONE.bits()
}

const fn insert_if_missing() -> i32 {
    PropertyOptions::INSERT_IF_MISSING.bits()
}

examples/execution_run_test_headless.rs (line 54)

const fn none() -> i32 {
    PropertyOptions::NONE.bits()
}

const fn insert_if_missing() -> i32 {
    PropertyOptions::INSERT_IF_MISSING.bits()
}

examples/result_list_parse.rs (line 28)

const fn none() -> i32 {
    PropertyOptions::NONE.bits()
}

const fn insert_if_missing() -> i32 {
    PropertyOptions::INSERT_IF_MISSING.bits()
}

examples/step_insert.rs (line 29)

const fn none() -> i32 {
    PropertyOptions::NONE.bits()
}

const fn insert_if_missing() -> i32 {
    PropertyOptions::INSERT_IF_MISSING.bits()
}

examples/step_insert_from_template.rs (line 37)

fn describe_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        if category.name()? == "Steps" {
            println!(
                "Step templates defined on this station: {}",
                category.get_num_elements()?
            );
        }
    }
    Ok(())
}

/// One configured VI-call step, to act as the prototype.
fn build_prototype(engine: &Engine) -> Result<Step, Error> {
    // The maintained LabVIEW adapter. The standard-prototype key still exists
    // but the documentation marks it obsolete in favour of this one.
    let step = engine.new_step(AdapterKeyName::LabView.as_str(), "Action")?;
    step.set_name("Measure (VI)")?;
    step.set_run_mode(RunMode::Normal)?;
    step.as_property_object()?.set_val_string(
        VI_PATH,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        r"example.lvlibp\measure.vi",
    )?;
    Ok(step)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_templates(&engine)?;

    let prototype = build_prototype(&engine)?;
    println!(
        "Prototype: {} via {:?}, run mode {:?}",
        prototype.name()?,
        prototype.adapter_key_name()?,
        prototype.run_mode()?
    );

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    let template = prototype.as_property_object()?;

    for copy_number in 1..=COPIES {
        let index = main_sequence.get_num_steps(StepGroup::Main)?;
        let inserted =
            main_sequence.insert_step_from_template(&template, index, StepGroup::Main)?;
        inserted.set_name(&format!("Measure {copy_number} (from template)"))?;
        // Each copy needs an identity of its own; the clone brought the
        // prototype's.
        inserted.create_new_unique_step_id()?;
    }

    println!(
        "\nMainSequence now holds {} step(s):",
        main_sequence.get_num_steps(StepGroup::Main)?
    );
    for index in 0..main_sequence.get_num_steps(StepGroup::Main)? {
        let step = main_sequence.get_step(index, StepGroup::Main)?;
        println!(
            "  [{index}] {} -> {}",
            step.name()?,
            step.as_property_object()?
                .get_val_string(VI_PATH, PropertyOptions::NONE.bits())?
        );
    }

    // The prototype is untouched and can go on producing copies.
    println!("\nPrototype still named: {}", prototype.name()?);

    let path = std::env::temp_dir().join("rs_teststand_from_template.seq");
    let path = path.to_string_lossy().into_owned();
    sequence_file.save(&path)?;
    println!("Saved to {path}");
    Ok(())
}

examples/template_manage_complex.rs (line 44)

fn describe_station_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;

    println!("Station templates file: {}", templates_file.path()?);
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        println!(
            "  {}: {} template(s)",
            category.name()?,
            category.get_num_elements()?
        );
    }
    Ok(())
}

/// An empty array container to keep prototypes in.
fn new_template_group(engine: &Engine) -> Result<PropertyObject, Error> {
    engine.new_property_object(
        PropValType::Container,
        true,
        "",
        PropertyOptions::NONE.bits(),
    )
}

/// Appends a detached copy of a prototype to the group.
///
/// The copy matters: the group must not share the object the caller keeps
/// editing, or adding a second template would change the first.
fn append_template(group: &PropertyObject, template: &PropertyObject) -> Result<(), Error> {
    let index = group.get_num_elements()?;
    group.set_num_elements(index + 1, PropertyOptions::NONE.bits())?;
    group.set_property_object(
        &format!("[{index}]"),
        PropertyOptions::NONE.bits(),
        &template.clone_property("", PropertyOptions::NONE.bits())?,
    )
}

/// Finds a prototype in the group by name.
fn find_template(group: &PropertyObject, name: &str) -> Result<Option<PropertyObject>, Error> {
    for index in 0..group.get_num_elements()? {
        let candidate = group.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        if candidate.name()? == name {
            return Ok(Some(candidate));
        }
    }
    Ok(None)
}

/// Turns "not found" into an error naming the template that is missing.
fn require(found: Option<PropertyObject>, name: &'static str) -> Result<PropertyObject, Error> {
    found.ok_or(Error::UnexpectedType {
        expected: name,
        actual: "no template of that name in the group",
    })
}

/// A configured Statement step, taken as a property tree so it can be cloned.
fn step_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name(STEP_TEMPLATE)?;
    step.set_post_expression(r#"Locals.Result = "Hello from step template!""#)?;
    step.as_property_object()
}

/// A whole sequence, one step included, as a single prototype.
fn sequence_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let sequence = engine.new_sequence()?;
    sequence.set_name(SEQUENCE_TEMPLATE)?;

    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name("Inside_Sequence_Template")?;
    sequence.insert_step(&step, 0, StepGroup::Main)?;

    sequence.as_property_object()
}

/// A string variable carrying its default value.
fn variable_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let variable =
        engine.new_property_object(PropValType::String, false, "", PropertyOptions::NONE.bits())?;
    variable.set_name(VARIABLE_TEMPLATE)?;
    variable.set_val_string("", PropertyOptions::NONE.bits(), "Template Variable Value")?;
    Ok(variable)
}

/// Stamps one copy of each template into a file that is already on disk.
fn apply_templates(
    sequence_file: &SequenceFile,
    step: &PropertyObject,
    sequence: &PropertyObject,
    variable: &PropertyObject,
) -> Result<(), Error> {
    let main_sequence = sequence_file.get_sequence_by_name(MAIN_SEQUENCE)?;

    // Inserting returns the copy on the Step interface, so it can be renamed
    // and re-identified straight away. Without a new step ID the copy would go
    // on claiming the prototype's identity.
    let inserted_step = main_sequence.insert_step_from_template(step, 0, StepGroup::Main)?;
    inserted_step.set_name("Step From Template")?;
    inserted_step.create_new_unique_step_id()?;
    println!("  step:     {}", inserted_step.name()?);

    let inserted_sequence = sequence_file.insert_sequence_from_template(sequence)?;
    inserted_sequence.create_new_unique_step_ids()?;
    println!(
        "  sequence: {} ({} step(s))",
        inserted_sequence.name()?,
        inserted_sequence.get_num_steps(StepGroup::Main)?
    );

    // A variable is the easy case: Locals is a property tree, so a clone drops
    // straight in under the template's own name.
    let locals = main_sequence.locals()?;
    locals.set_property_object(
        &variable.name()?,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        &variable.clone_property("", PropertyOptions::NONE.bits())?,
    )?;
    println!(
        "  variable: {} = {:?}",
        variable.name()?,
        locals.get_val_string(&variable.name()?, PropertyOptions::NONE.bits())?
    );

    // A file that does not believe it changed will not write anything.
    sequence_file
        .as_property_object_file()?
        .inc_change_count()?;
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_station_templates(&engine)?;

    println!("\nBuilding an in-memory template group...");
    let group = new_template_group(&engine)?;
    append_template(&group, &step_template(&engine)?)?;
    append_template(&group, &sequence_template(&engine)?)?;
    append_template(&group, &variable_template(&engine)?)?;
    println!("  {} template(s) stored", group.get_num_elements()?);

    let step = require(find_template(&group, STEP_TEMPLATE)?, STEP_TEMPLATE)?;
    let sequence = require(find_template(&group, SEQUENCE_TEMPLATE)?, SEQUENCE_TEMPLATE)?;
    let variable = require(find_template(&group, VARIABLE_TEMPLATE)?, VARIABLE_TEMPLATE)?;

    // Saving first, then reopening, is deliberate: templates are worth having
    // because they are applied to files a program did not build in this run.
    let path = std::env::temp_dir().join("rs_teststand_from_templates.seq");
    let path = path.to_string_lossy().into_owned();
    engine.new_sequence_file()?.save(&path)?;

    println!("\nApplying templates to the saved file...");
    let target = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        rs_teststand::ConflictHandler::Error,
    )?;
    apply_templates(&target, &step, &sequence, &variable)?;
    target.save(&path)?;
    println!("\nSaved to {path}");

    engine.release_sequence_file_ex(target, PropertyOptions::NONE.bits())?;
    Ok(())
}

pub const fn from_bits(bits: i32) -> Option<Self>

Convert from a bits value.

This method will return None if any unknown bits are set.

pub const fn from_bits_truncate(bits: i32) -> Self

Convert from a bits value, unsetting any unknown bits.

pub const fn from_bits_retain(bits: i32) -> Self

Convert from a bits value exactly.

pub fn from_name(name: &str) -> Option<Self>

Get a flags value with the bits of a flag with the given name set.

This method will return None if name is empty or doesn’t correspond to any named flag.

pub const fn is_empty(&self) -> bool

Whether all bits in self are unset.

pub const fn is_all(&self) -> bool

Whether all known bits in this flags value are set.

pub const fn intersects(&self, other: Self) -> bool

Whether any set bits in other are also set in self.

pub const fn contains(&self, other: Self) -> bool

Whether all set bits in other are also set in self.

pub fn insert(&mut self, other: Self)

The bitwise or (|) of the bits in self and other.

pub fn remove(&mut self, other: Self)

The intersection of self with the complement of other (&!).

This method is not equivalent to self & !other when other has unknown bits set. remove won’t truncate other, but the ! operator will.

pub fn toggle(&mut self, other: Self)

The bitwise exclusive-or (^) of the bits in self and other.

pub fn set(&mut self, other: Self, value: bool)

Call insert when value is true or remove when value is false.

pub const fn intersection(self, other: Self) -> Self

The bitwise and (&) of the bits in self and other.

pub const fn union(self, other: Self) -> Self

The bitwise or (|) of the bits in self and other.

pub const fn difference(self, other: Self) -> Self

The intersection of self with the complement of other (&!).

This method is not equivalent to self & !other when other has unknown bits set. difference won’t truncate other, but the ! operator will.

pub const fn symmetric_difference(self, other: Self) -> Self

The bitwise exclusive-or (^) of the bits in self and other.

pub const fn complement(self) -> Self

The bitwise negation (!) of the bits in self, truncating the result.

impl PropertyOptions

pub const fn iter(&self) -> Iter<PropertyOptions>

Yield a set of contained flags values.

Each yielded flags value will correspond to a defined named flag. Any unknown bits will be yielded together as a final flags value.

pub const fn iter_names(&self) -> IterNames<PropertyOptions>

Yield a set of contained named flags values.

This method is like iter, except only yields bits in contained named flags. Any unknown bits, or bits not corresponding to a contained flag will not be yielded.

Trait Implementations

impl Binary for PropertyOptions

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

Formats the value using the given formatter.

impl BitAnd for PropertyOptions

fn bitand(self, other: Self) -> Self

The bitwise and (&) of the bits in self and other.

type Output = PropertyOptions

The resulting type after applying the & operator.

impl BitAndAssign for PropertyOptions

fn bitand_assign(&mut self, other: Self)

The bitwise and (&) of the bits in self and other.

impl BitOr for PropertyOptions

fn bitor(self, other: PropertyOptions) -> Self

The bitwise or (|) of the bits in self and other.

type Output = PropertyOptions

The resulting type after applying the | operator.

impl BitOrAssign for PropertyOptions

fn bitor_assign(&mut self, other: Self)

The bitwise or (|) of the bits in self and other.

impl BitXor for PropertyOptions

fn bitxor(self, other: Self) -> Self

The bitwise exclusive-or (^) of the bits in self and other.

type Output = PropertyOptions

The resulting type after applying the ^ operator.

impl BitXorAssign for PropertyOptions

fn bitxor_assign(&mut self, other: Self)

The bitwise exclusive-or (^) of the bits in self and other.

impl Clone for PropertyOptions

fn clone(&self) -> PropertyOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for PropertyOptions

impl Debug for PropertyOptions

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

Formats the value using the given formatter.

impl Default for PropertyOptions

fn default() -> PropertyOptions

Returns the “default value” for a type.

impl Eq for PropertyOptions

impl Extend<PropertyOptions> for PropertyOptions

fn extend<T: IntoIterator<Item = Self>>(&mut self, iterator: T)

The bitwise or (|) of the bits in each flags value.

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 Flags for PropertyOptions

const FLAGS: &'static [Flag<PropertyOptions>]

The set of defined flags.

type Bits = i32

The underlying bits type.

fn bits(&self) -> i32

Get the underlying bits value.

fn from_bits_retain(bits: i32) -> PropertyOptions

Convert from a bits value exactly.

fn all_named() -> PropertyOptions

Get a flags value with all bits from named flags set.

fn empty() -> Self

Get a flags value with all bits unset.

fn all() -> Self

Get a flags value with all known bits set.

fn known_bits(&self) -> Self::Bits

Get the known bits from a flags value.

fn unknown_bits(&self) -> Self::Bits

Get the unknown bits from a flags value.

fn contains_unknown_bits(&self) -> bool

This method will return true if any unknown bits are set.

fn from_bits(bits: Self::Bits) -> Option<Self>

Convert from a bits value.

fn from_bits_truncate(bits: Self::Bits) -> Self

Convert from a bits value, unsetting any unknown bits.

fn from_name(name: &str) -> Option<Self>

Get a flags value with the bits of a flag with the given name set.

fn iter(&self) -> Iter<Self>

Yield a set of contained flags values.

fn iter_names(&self) -> IterNames<Self>

Yield a set of contained named flags values.

fn iter_defined_names() -> IterDefinedNames<Self>

Yield a set of all named flags defined by Self::FLAGS.

fn iter_equal_names(&self) -> IterEqualNames<Self>

Get an iterator over all defined names for this flags value.

fn is_empty(&self) -> bool

Whether all bits in this flags value are unset.

fn is_all(&self) -> bool

Whether all known bits in this flags value are set.

fn intersects(&self, other: Self) -> bool

where Self: Sized,

Whether any set bits in other are also set in self.

fn contains(&self, other: Self) -> bool

where Self: Sized,

Whether all set bits in other are also set in self.

fn truncate(&mut self)

where Self: Sized,

Remove any unknown bits from the flags.

fn insert(&mut self, other: Self)

where Self: Sized,

The bitwise or (|) of the bits in self and other.

fn remove(&mut self, other: Self)

where Self: Sized,

The intersection of self with the complement of other (&!).

fn toggle(&mut self, other: Self)

where Self: Sized,

The bitwise exclusive-or (^) of the bits in self and other.

fn set(&mut self, other: Self, value: bool)

where Self: Sized,

Call Flags::insert when value is true or Flags::remove when value is false.

fn clear(&mut self)

where Self: Sized,

Unsets all bits in the flags.

fn intersection(self, other: Self) -> Self

The bitwise and (&) of the bits in self and other.

fn union(self, other: Self) -> Self

The bitwise or (|) of the bits in self and other.

fn difference(self, other: Self) -> Self

The intersection of self with the complement of other (&!).

fn symmetric_difference(self, other: Self) -> Self

The bitwise exclusive-or (^) of the bits in self and other.

fn complement(self) -> Self

The bitwise negation (!) of the bits in self, truncating the result.

impl FromIterator<PropertyOptions> for PropertyOptions

fn from_iter<T: IntoIterator<Item = Self>>(iterator: T) -> Self

The bitwise or (|) of the bits in each flags value.

impl Hash for PropertyOptions

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoIterator for PropertyOptions

type Item = PropertyOptions

The type of the elements being iterated over.

type IntoIter = Iter<PropertyOptions>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl LowerHex for PropertyOptions

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

Formats the value using the given formatter.

impl Not for PropertyOptions

fn not(self) -> Self

The bitwise negation (!) of the bits in self, truncating the result.

type Output = PropertyOptions

The resulting type after applying the ! operator.

impl Octal for PropertyOptions

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

Formats the value using the given formatter.

impl PartialEq for PropertyOptions

fn eq(&self, other: &PropertyOptions) -> bool

Equality operator ==.

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

Inequality operator !=.

impl PublicFlags for PropertyOptions

type Primitive = i32

The type of the underlying storage.

type Internal = InternalBitFlags

The type of the internal field on the generated flags type.

impl StructuralPartialEq for PropertyOptions

impl Sub for PropertyOptions

fn sub(self, other: Self) -> Self

The intersection of self with the complement of other (&!).

This method is not equivalent to self & !other when other has unknown bits set. difference won’t truncate other, but the ! operator will.

type Output = PropertyOptions

The resulting type after applying the - operator.

impl SubAssign for PropertyOptions

fn sub_assign(&mut self, other: Self)

The intersection of self with the complement of other (&!).

This method is not equivalent to self & !other when other has unknown bits set. difference won’t truncate other, but the ! operator will.

impl UpperHex for PropertyOptions

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

Formats the value using the given formatter.