Struct AttributeSelector

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

An attribute selector.

This type defines the path to an element in a DICOM data set, even at an arbitrary depth of nested data sets. A selector may be perceived as a series of navigation steps to reach a certain data element, where all steps but the last one refer to data set sequences.

Attribute selectors can be created through one of the various From conversions, the dynamic constructor function new, or through parsing.

Syntax

A syntax is defined for the unambiguous conversion between a string and an AttributeSelector value, in both directions. Attribute selectors are defined by the syntax ( «key»([«item»])? . )* «key» where:

• «key» is either a DICOM tag in a supported textual form, or a tag keyword as accepted by the data dictionary in use;
• «item» is an unsigned integer representing the item index, which is always surrounded by square brackets in the input;
• [, ], and . are literally their own characters as part of the input.

The first part in parentheses may appear zero or more times. The [«item»] part can be omitted, in which case it is assumed that the first item is selected. Whitespace is not admitted in any position. Displaying a selector through the Display trait produces a string that is compliant with this syntax.

Examples of attribute selectors in text:

• (0002,00010): selects Transfer Syntax UID
• 00101010: selects Patient Age
• 0040A168[0].CodeValue: selects Code Value within the first item of Concept Code Sequence
• 0040,A730[1].ContentSequence: selects Content Sequence in second item of Content Sequence
• SequenceOfUltrasoundRegions.RegionSpatialFormat: Region Spatial Format in first item of Sequence of Ultrasound Regions

Example

In most cases, you might only wish to select an attribute that is sitting at the root of the data set. This can be done by converting a DICOM tag via From<Tag>:

// select Patient Name
let selector = AttributeSelector::from(Tag(0x0010, 0x0010));

For working with nested data sets, From also supports converting an interleaved sequence of tags and item indices in a tuple. For instance, this is how we can select the second frame’s acquisition date time from the per-frame functional groups sequence.

let selector: AttributeSelector = (
    // Per-frame functional groups sequence
    Tag(0x5200, 0x9230),
    // item #1
    1,
    // Frame Acquisition Date Time (DT)
    Tag(0x0018, 0x9074)
).into();

For a more dynamic construction, the new function supports an iterator of attribute selector steps (of type AttributeSelectorStep). Note that the function fails if the last step refers to a sequence item.

let selector = AttributeSelector::new([
    // Per-frame functional groups sequence, item #1
    AttributeSelectorStep::Nested {
        tag: Tag(0x5200, 0x9230),
        // item #1
        item: 1,
    },
    // Frame Acquisition Date Time
    AttributeSelectorStep::Tag(Tag(0x0018, 0x9074)),
]).ok_or_else(|| "should be a valid sequence")?;

A data dictionary’s parse_selector method can be used if you want to describe these selectors in text.

use dicom_core::dictionary::DataDictionary;
use dicom_dictionary_std::StandardDataDictionary;

assert_eq!(
    StandardDataDictionary.parse_selector(
        "PerFrameFunctionalGroupsSequence[1].(0018,9074)"
    )?,
    AttributeSelector::from((
        // Per-frame functional groups sequence
        Tag(0x5200, 0x9230),
        // item #1
        1,
        // Frame Acquisition Date Time (DT)
        Tag(0x0018, 0x9074)
    )),
);

Selectors can be decomposed back into its constituent steps by turning it into an iterator:

let steps: Vec<AttributeSelectorStep> = selector.into_iter().collect();

assert_eq!(
    &steps,
    &[
        AttributeSelectorStep::Nested {
            tag: Tag(0x5200, 0x9230),
            item: 1,
        },
        AttributeSelectorStep::Tag(Tag(0x0018, 0x9074)),
    ],
);

Implementations

impl AttributeSelector

pub fn new( steps: impl IntoIterator<Item = AttributeSelectorStep>, ) -> Option<Self>

Construct an attribute selector from an arbitrary sequence of selector steps.

Intermediate steps of variant Tag (which do not specify an item index) are automatically reinterpreted as item selectors for item index 0.

Returns None if the sequence is empty or the last step is not a tag selector step.

pub fn iter(&self) -> impl Iterator<Item = &AttributeSelectorStep>

Return a non-empty iterator over the steps of attribute selection.

The iterator is guaranteed to produce a series starting with zero or more steps of the variant Nested, and terminated by one item guaranteed to be a tag.

pub fn first_step(&self) -> &AttributeSelectorStep

Obtain a reference to the first attribute selection step.

pub fn last_step(&self) -> &AttributeSelectorStep

Obtain a reference to the last attribute selection step.

pub fn last_tag(&self) -> Tag

Obtain the tag of the last attribute selection step.

Trait Implementations

impl Clone for AttributeSelector

fn clone(&self) -> AttributeSelector

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AttributeSelector

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

Formats the value using the given formatter.

impl Display for AttributeSelector

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

Formats the value using the given formatter.

impl From<(Tag, Tag)> for AttributeSelector

Creates an attribute selector for tag.tag (where the first)

fn from((tag0, tag1): (Tag, Tag)) -> Self

Creates an attribute selector which navigates to the first data set item in the sequence at the first DICOM tag (tag0), then selects the element with the second DICOM tag (tag1).

impl From<(Tag, Tag, Tag)> for AttributeSelector

Creates an attribute selector for tag.tag.tag

fn from((tag0, tag1, tag2): (Tag, Tag, Tag)) -> Self

Creates an attribute selector which navigates to the first data set item in the sequence at tag0, navigates further down to the first item in the sequence at tag1, then selects the element at tag2.

impl From<(Tag, Tag, u32, Tag)> for AttributeSelector

Creates an attribute selector for tag.tag[item].tag

fn from((tag0, tag1, item1, tag2): (Tag, Tag, u32, Tag)) -> Self

Creates an attribute selector which navigates to the first data set item in the sequence at tag0, navigates further down to item #item1 in the sequence at tag1, then selects the element at tag2.

impl From<(Tag, u32, Tag)> for AttributeSelector

Creates an attribute selector for tag[item].tag

fn from((tag0, item, tag1): (Tag, u32, Tag)) -> Self

Creates an attribute selector which navigates to the data set item at index item in the sequence at the first DICOM tag (tag0), then selects the element with the second DICOM tag (tag1).

impl From<(Tag, u32, Tag, Tag)> for AttributeSelector

Creates an attribute selector for tag[item].tag.tag

fn from((tag0, item0, tag1, tag2): (Tag, u32, Tag, Tag)) -> Self

Creates an attribute selector which navigates to the data set item #item0 in the sequence at tag0, navigates further down to the first item in the sequence at tag1, then selects the element at tag2.

impl From<(Tag, u32, Tag, u32, Tag)> for AttributeSelector

Creates an attribute selector for tag[item].tag[item].tag

fn from((tag0, item0, tag1, item1, tag2): (Tag, u32, Tag, u32, Tag)) -> Self

Creates an attribute selector which navigates to data set item #item0 in the sequence at tag0, navigates further down to item #item1 in the sequence at tag1, then selects the element at tag2.

impl From<(Tag, u32, Tag, u32, Tag, u32, Tag)> for AttributeSelector

Creates an attribute selector for tag[item].tag[item].tag[item].tag

fn from( (tag0, item0, tag1, item1, tag2, item2, tag3): (Tag, u32, Tag, u32, Tag, u32, Tag), ) -> Self

Converts to this type from the input type.

impl From<Tag> for AttributeSelector

Creates an attribute selector for just a tag.

fn from(tag: Tag) -> Self

Creates a simple attribute selector by selecting the element at the data set root with the given DICOM tag.

impl Hash for AttributeSelector

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<'a> IntoIterator for &'a AttributeSelector

fn into_iter(self) -> Self::IntoIter

Returns a non-empty iterator over the steps of attribute selection.

The iterator is guaranteed to produce a series starting with zero or more steps of the variant Nested, and terminated by one item guaranteed to be a tag.

type Item = &'a AttributeSelectorStep

The type of the elements being iterated over.

type IntoIter = <&'a SmallVec<[AttributeSelectorStep; 2]> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

impl IntoIterator for AttributeSelector

fn into_iter(self) -> Self::IntoIter

Returns a non-empty iterator over the steps of attribute selection.

The iterator is guaranteed to produce a series starting with zero or more steps of the variant Nested, and terminated by one item guaranteed to be a tag.

type Item = AttributeSelectorStep

The type of the elements being iterated over.

type IntoIter = <SmallVec<[AttributeSelectorStep; 2]> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

impl PartialEq for AttributeSelector

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for AttributeSelector

impl StructuralPartialEq for AttributeSelector