Struct DataElement

pub struct DataElement<I = EmptyObject, P = InMemFragment> { /* private fields */ }

A data type that represents and owns a DICOM data element.

This type is capable of representing any data element fully in memory, whether it be a primitive value, a nested data set (where I is the object type for data set items), or an encapsulated pixel data sequence (each item of type P). The type parameter I should usually implement HasLength, whereas P should usually implement AsRef<[u8]>.

Implementations

impl<I, P> DataElement<I, P>

pub fn empty(tag: Tag, vr: VR) -> Self

Create an empty data element.

pub fn header(&self) -> &DataElementHeader

Retrieve the element header.

pub fn vr(&self) -> VR

Retrieve the value representation, which may be unknown or not applicable.

pub fn value(&self) -> &Value<I, P>

Retrieve the data value.

pub fn into_value(self) -> Value<I, P>

Move the data value out of the element, discarding the rest. If the value is a sequence, its lifetime may still be bound to its original source.

pub fn into_parts(self) -> (DataElementHeader, Value<I, P>)

Split the constituent parts of this element into a tuple. If the value is a sequence, its lifetime may still be bound to the original source.

pub fn update_value(&mut self, f: impl FnMut(&mut Value<I, P>))

Obtain a temporary mutable reference to the value, so that mutations can be applied within.

Once updated, the header is automatically updated based on this set of rules:

• if the value is a data set sequence, the VR is set to SQ and the length is reset to undefined;
• if the value is a pixel data fragment sequence, the VR is set to OB and the length is reset to undefined;
• if the value is primitive, the length is recalculated, leaving the VR as is.

If these rules do not result in a valid element, consider reconstructing the data element instead.

impl<I, P> DataElement<I, P>

where I: HasLength,

pub fn new<T>(tag: Tag, vr: VR, value: T) -> Self

where T: Into<Value<I, P>>,

Create a data element from the given parts, where the length is inferred from the value’s byte length.

If the value is textual, the byte length of that value encoded in UTF-8 is assumed. If you already have a length in this context, prefer calling new_with_len instead.

This method will not check whether the value representation is compatible with the given value.

pub fn new_with_len<T>(tag: Tag, vr: VR, length: Length, value: T) -> Self

where T: Into<Value<I, P>>,

Create a primitive data element from the given parts.

This method will not check whether the length accurately represents the given value’s byte length, nor whether the value representation is compatible with the value.

pub fn to_str(&self) -> Result<Cow<'_, str>, ConvertValueError>

Retrieve the element’s value as a single clean string, with no trailing whitespace.

Returns an error if the value is not primitive.

pub fn to_raw_str(&self) -> Result<Cow<'_, str>, ConvertValueError>

Retrieve the element’s value as a single raw string, with trailing whitespace kept.

Returns an error if the value is not primitive.

pub fn to_bytes(&self) -> Result<Cow<'_, [u8]>, ConvertValueError>

Convert the full primitive value into raw bytes.

String values already encoded with the Str and Strs variants are provided in UTF-8.

Returns an error if the value is not primitive.

pub fn to_multi_str(&self) -> Result<Cow<'_, [String]>, CastValueError>

Convert the full value of the data element into a sequence of strings.

If the value is a primitive, it will be converted into a vector of strings as described in PrimitiveValue::to_multi_str.

Returns an error if the value is not primitive.

pub fn to_int<T>(&self) -> Result<T, ConvertValueError>

where T: Clone + NumCast + FromStr<Err = ParseIntError>,

Retrieve and convert the value of the data element into an integer.

If the value is a primitive, it will be converted into an integer as described in PrimitiveValue::to_int.

Returns an error if the value is not primitive.

pub fn to_multi_int<T>(&self) -> Result<Vec<T>, ConvertValueError>

where T: Clone + NumCast + FromStr<Err = ParseIntError>,

Retrieve and convert the value of the data element into a sequence of integers.

If the value is a primitive, it will be converted into a vector of integers as described in PrimitiveValue::to_multi_int.

pub fn to_float32(&self) -> Result<f32, ConvertValueError>

Retrieve and convert the value of the data element into a single-precision floating point number.

If the value is a primitive, it will be converted into a number as described in PrimitiveValue::to_float32.

Returns an error if the value is not primitive.

pub fn to_multi_float32(&self) -> Result<Vec<f32>, ConvertValueError>

Retrieve and convert the value of the data element into a sequence of single-precision floating point numbers.

If the value is a primitive, it will be converted into a vector of numbers as described in PrimitiveValue::to_multi_float32.

Returns an error if the value is not primitive.

pub fn to_float64(&self) -> Result<f64, ConvertValueError>

Retrieve and convert the value of the data element into a double-precision floating point number.

If the value is a primitive, it will be converted into a number as described in PrimitiveValue::to_float64.

Returns an error if the value is not primitive.

pub fn to_multi_float64(&self) -> Result<Vec<f64>, ConvertValueError>

Retrieve and convert the value of the data element into a sequence of double-precision floating point numbers.

If the value is a primitive, it will be converted into a vector of numbers as described in PrimitiveValue::to_multi_float64.

Returns an error if the value is not primitive.

pub fn to_date(&self) -> Result<DicomDate, ConvertValueError>

Retrieve and convert the primitive value into a date.

If the value is a primitive, it will be converted into a DicomDate as described in PrimitiveValue::to_date.

Returns an error if the value is not primitive.

pub fn to_multi_date(&self) -> Result<Vec<DicomDate>, ConvertValueError>

Retrieve and convert the primitive value into a sequence of dates.

If the value is a primitive, it will be converted into a vector of DicomDate as described in PrimitiveValue::to_multi_date.

Returns an error if the value is not primitive.

pub fn to_time(&self) -> Result<DicomTime, ConvertValueError>

Retrieve and convert the primitive value into a time.

If the value is a primitive, it will be converted into a DicomTime as described in PrimitiveValue::to_time.

Returns an error if the value is not primitive.

pub fn to_multi_time(&self) -> Result<Vec<DicomTime>, ConvertValueError>

Retrieve and convert the primitive value into a sequence of times.

If the value is a primitive, it will be converted into a vector of DicomTime as described in PrimitiveValue::to_multi_time.

Returns an error if the value is not primitive.

pub fn to_datetime(&self) -> Result<DicomDateTime, ConvertValueError>

Retrieve and convert the primitive value into a date-time.

If the value is a primitive, it will be converted into a DicomDateTime as described in PrimitiveValue::to_datetime.

Returns an error if the value is not primitive.

pub fn to_multi_datetime(&self) -> Result<Vec<DicomDateTime>, ConvertValueError>

Retrieve and convert the primitive value into a sequence of date-times.

If the value is a primitive, it will be converted into a vector of DicomDateTime as described in PrimitiveValue::to_multi_datetime.

Returns an error if the value is not primitive.

pub fn items(&self) -> Option<&[I]>

Retrieve the items stored in a sequence value.

Returns None if the underlying value is not a data set sequence.

pub fn items_mut(&mut self) -> Option<&mut C<I>>

Gets a mutable reference to the items of a sequence value.

The header’s recorded length is automatically reset to undefined, in order to prevent inconsistencies.

Returns None if the underlying value is not a data set sequence.

pub fn fragments(&self) -> Option<&[P]>

Retrieve the fragments stored in a pixel data sequence value.

Returns None if the value is not a pixel data sequence.

pub fn fragments_mut(&mut self) -> Option<&mut C<P>>

Obtain a mutable reference to the fragments stored in a pixel data sequence value.

The header’s recorded length is automatically reset to undefined, in order to prevent inconsistencies.

Returns None if the value is not a pixel data sequence.

pub fn offset_table(&self) -> Option<&[u32]>

Obtain a reference to the encapsulated pixel data’s basic offset table.

Returns None if the underlying value is not a pixel data sequence.

impl<I, P> DataElement<I, P>

pub fn string(&self) -> Result<&str, CastValueError>

Get a single string value.

If it contains multiple strings, only the first one is returned.

An error is returned if the variant is not compatible.

To enable conversions of other variants to a textual representation, see to_str() instead.

pub fn strings(&self) -> Result<&[String], CastValueError>

Get the inner sequence of string values if the variant is either Str or Strs.

An error is returned if the variant is not compatible.

To enable conversions of other variants to a textual representation, see to_str() instead.

pub fn date(&self) -> Result<DicomDate, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn dates(&self) -> Result<&[DicomDate], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn time(&self) -> Result<DicomTime, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn times(&self) -> Result<&[DicomTime], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn datetime(&self) -> Result<DicomDateTime, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn datetimes(&self) -> Result<&[DicomDateTime], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn uint8(&self) -> Result<u8, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn uint8_slice(&self) -> Result<&[u8], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn uint16(&self) -> Result<u16, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn uint16_slice(&self) -> Result<&[u16], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn int16(&self) -> Result<i16, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn int16_slice(&self) -> Result<&[i16], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn uint32(&self) -> Result<u32, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn uint32_slice(&self) -> Result<&[u32], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn int32(&self) -> Result<i32, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn int32_slice(&self) -> Result<&[i32], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn int64(&self) -> Result<i64, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn int64_slice(&self) -> Result<&[i64], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn uint64(&self) -> Result<u64, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn uint64_slice(&self) -> Result<&[u64], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn float32(&self) -> Result<f32, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn float32_slice(&self) -> Result<&[f32], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

pub fn float64(&self) -> Result<f64, CastValueError>

Get a single value of the requested type.

If it contains multiple values, only the first one is returned. An error is returned if the variant is not compatible.

pub fn float64_slice(&self) -> Result<&[f64], CastValueError>

Get a sequence of values of the requested type without copying.

An error is returned if the variant is not compatible.

Trait Implementations

impl<I: Clone, P: Clone> Clone for DataElement<I, P>

fn clone(&self) -> DataElement<I, P>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<I: Debug, P: Debug> Debug for DataElement<I, P>

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

Formats the value using the given formatter.

impl<I, P> From<PrimitiveDataElement> for DataElement<I, P>

fn from(o: PrimitiveDataElement) -> Self

Converts to this type from the input type.

impl<I, P> HasLength for &DataElement<I, P>

fn length(&self) -> Length

Retrieve the value data’s length as specified by the data element or item, in bytes.

fn is_empty(&self) -> bool

Check whether the value is empty (0 length).

impl<I, P> HasLength for DataElement<I, P>

fn length(&self) -> Length

Retrieve the value data’s length as specified by the data element or item, in bytes.

fn is_empty(&self) -> bool

Check whether the value is empty (0 length).

impl<I, P> Header for &DataElement<I, P>

fn tag(&self) -> Tag

Retrieve the element’s tag as a (group, element) tuple.

fn is_item(&self) -> bool

Check whether this is the header of an item.

fn is_item_delimiter(&self) -> bool

Check whether this is the header of an item delimiter.

fn is_sequence_delimiter(&self) -> bool

Check whether this is the header of a sequence delimiter.

fn is_encapsulated_pixeldata(&self) -> bool

Check whether this is the header of an encapsulated pixel data.

impl<I, P> Header for DataElement<I, P>

fn tag(&self) -> Tag

Retrieve the element’s tag as a (group, element) tuple.

fn is_item(&self) -> bool

Check whether this is the header of an item.

fn is_item_delimiter(&self) -> bool

Check whether this is the header of an item delimiter.

fn is_sequence_delimiter(&self) -> bool

Check whether this is the header of a sequence delimiter.

fn is_encapsulated_pixeldata(&self) -> bool

Check whether this is the header of an encapsulated pixel data.

impl<I: PartialEq, P: PartialEq> PartialEq for DataElement<I, P>

fn eq(&self, other: &DataElement<I, P>) -> 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<I, P> StructuralPartialEq for DataElement<I, P>