Enum dicom_core::value::Value

pub enum Value<I = EmptyObject, P = InMemFragment> {
    Primitive(PrimitiveValue),
    Sequence(DataSetSequence<I>),
    PixelSequence(PixelFragmentSequence<P>),
}

Representation of a full DICOM value, which may be either primitive or another DICOM object.

I is the complex type for nest data set items, which should usually implement HasLength. P is the encapsulated pixel data provider, which should usually implement AsRef<[u8]>.

Variants

Primitive(PrimitiveValue)

Primitive value.

Sequence(DataSetSequence<I>)

A complex sequence of items.

PixelSequence(PixelFragmentSequence<P>)

A sequence of encapsulated pixel data fragments.

Implementations

impl<P> Value<EmptyObject, P>

pub fn new_pixel_sequence<T>(offset_table: C<u32>, fragments: T) -> Self

where T: Into<C<P>>,

Construct an isolated DICOM pixel sequence sequence value from a basic offset table and a list of fragments.

This function will define the data set sequence item type I to an empty object (EmptyObject), so that it can be used more easily in isolation. As a consequence, it cannot be directly combined with DICOM objects that may contain sequence values. To let the type parameter I be inferred from its context, create a PixelFragmentSequence and use Value::from instead.

Note: This function does not validate the offset table against the fragments.

impl<I> Value<I>

pub fn new_sequence<T>(items: T, length: Length) -> Self

where T: Into<C<I>>,

Construct an isolated DICOM data set sequence value from a list of items and length.

This function will define the pixel data fragment type parameter P to the Value type’s default (InMemFragment), so that it can be used more easily. If necessary, it is possible to let this type parameter be inferred from its context by creating a DataSetSequence and using Value::from instead.

impl Value

pub fn new(value: PrimitiveValue) -> Self

Construct a DICOM value from a primitive value.

This is equivalent to Value::from in behavior, except that suitable type parameters are specified instead of inferred.

This function will automatically define the sequence item parameter I to EmptyObject and the pixel data fragment type parameter P to the default fragment data type (InMemFragment), so that it can be used more easily in isolation. As a consequence, it cannot be directly combined with DICOM objects that may contain nested data sets or encapsulated pixel data. To let the type parameters I and P be inferred from their context, create a value of one of the types and use Value::from instead.

• PrimitiveValue
• PixelFragmentSequence
• DataSetSequence

impl<I, P> Value<I, P>

pub fn multiplicity(&self) -> u32

Obtain the number of individual values. In a primitive, this is the number of individual elements in the value. In a sequence item, this is the number of items. In a pixel sequence, this is currently set to 1 regardless of the number of compressed fragments or frames.

pub fn primitive(&self) -> Option<&PrimitiveValue>

Gets a reference to the primitive value.

pub fn primitive_mut(&mut self) -> Option<&mut PrimitiveValue>

Gets a mutable reference to the primitive value.

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

Gets a reference to the items of a sequence.

Returns None if the 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.

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

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

Gets a reference to the fragments of a pixel data sequence.

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

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

Gets a mutable reference to the fragments of a pixel data sequence.

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

pub fn into_primitive(self) -> Option<PrimitiveValue>

Retrieves the primitive value.

pub fn into_items(self) -> Option<C<I>>

Retrieves the data set items, discarding the recorded length information.

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

pub fn into_fragments(self) -> Option<C<P>>

Retrieves the pixel data fragments, discarding the rest of the information.

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

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

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

pub fn offset_table_mut(&mut self) -> Option<&mut C<u32>>

Gets a mutable reference to the encapsulated pixel data’s offset table.

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

pub fn truncate(&mut self, limit: usize)

Shorten this value by removing trailing elements to fit the given limit.

On primitive values, elements are counted by the number of individual value items (note that bytes in a PrimitiveValue::U8 are treated as individual items). On data set sequences and pixel data fragment sequences, this operation is applied to the data set items (or fragments) in the sequence.

Nothing is done if the value’s cardinality is already lower than or equal to the limit.

impl<I, P> Value<I, P>

where I: HasLength,

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

Convert the full primitive value into a clean string.

The value is converted into a strings as described in PrimitiveValue::to_str. If the value contains multiple strings, they are trimmed at the end and concatenated (separated by the standard DICOM value delimiter '\\') into an owned string.

Returns an error if the value is not primitive.

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

Convert the full primitive value into a single raw string, with trailing whitespace kept.

If the value contains multiple strings, they are concatenated (separated by the standard DICOM value delimiter '\\') into an owned string.

Returns an error if the value is not primitive.

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

Convert the full primitive value 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_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_int<T>(&self) -> Result<T, ConvertValueError>

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

Retrieve and convert the primitive value into an integer.

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

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

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

Retrieve and convert the primitive value 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 primitive value 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.

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

Retrieve and convert the primitive value 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.

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

Retrieve and convert the primitive value 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.

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

Retrieve and convert the primitive value 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.

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

Retrieve and convert the primitive value into a DicomDate.

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

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

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

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

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

Retrieve and convert the primitive value into a DicomTime.

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

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

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

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

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

Retrieve and convert the primitive value into a DicomDateTime.

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

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

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

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

pub fn to_date_range(&self) -> Result<DateRange, ConvertValueError>

Retrieve and convert the primitive value into a DateRange.

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

pub fn to_time_range(&self) -> Result<TimeRange, ConvertValueError>

Retrieve and convert the primitive value into a TimeRange.

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

pub fn to_datetime_range(&self) -> Result<DateTimeRange, ConvertValueError>

Retrieve and convert the primitive value into a DateTimeRange.

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

pub fn to_tag(&self) -> Result<Tag, CastValueError>

Retrieves the primitive value as a DICOM tag.

pub fn to_person_name(&self) -> Result<PersonName<'_>, ConvertValueError>

Retrieves the primitive value as a PersonName.

impl<I, P> Value<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 tag(&self) -> Result<Tag, 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 tags(&self) -> Result<&[Tag], CastValueError>

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

An error is returned if the variant is not compatible.

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 Value<I, P>

fn clone(&self) -> Value<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 Value<I, P>

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

Formats the value using the given formatter.

impl<I, P> DicomValueType for Value<I, P>

fn value_type(&self) -> ValueType

Retrieve the specific type of this value.

fn cardinality(&self) -> usize

Retrieve the number of elements contained in the DICOM value.

impl<I, P> From<&str> for Value<I, P>

fn from(value: &str) -> Self

Converts a string into a primitive textual value.

impl<I, P> From<DataSetSequence<I>> for Value<I, P>

fn from(value: DataSetSequence<I>) -> Self

Converts to this type from the input type.

impl<I, P> From<PixelFragmentSequence<P>> for Value<I, P>

fn from(value: PixelFragmentSequence<P>) -> Self

Converts to this type from the input type.

impl<I, P> From<PrimitiveValue> for Value<I, P>

fn from(v: PrimitiveValue) -> Self

Converts to this type from the input type.

impl<I, P> From<String> for Value<I, P>

fn from(value: String) -> Self

Converts a string into a primitive textual value.

impl<I, P> HasLength for Value<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: PartialEq, P: PartialEq> PartialEq for Value<I, P>

fn eq(&self, other: &Value<I, P>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<I, P> StructuralPartialEq for Value<I, P>