[−][src]Enum dicom_core::PrimitiveValue

pub enum PrimitiveValue {
    Empty,
    Strs(SmallVec<[String; 2]>),
    Str(String),
    Tags(SmallVec<[Tag; 2]>),
    U8(SmallVec<[u8; 2]>),
    I16(SmallVec<[i16; 2]>),
    U16(SmallVec<[u16; 2]>),
    I32(SmallVec<[i32; 2]>),
    U32(SmallVec<[u32; 2]>),
    I64(SmallVec<[i64; 2]>),
    U64(SmallVec<[u64; 2]>),
    F32(SmallVec<[f32; 2]>),
    F64(SmallVec<[f64; 2]>),
    Date(SmallVec<[NaiveDate; 2]>),
    DateTime(SmallVec<[DateTime<FixedOffset>; 2]>),
    Time(SmallVec<[NaiveTime; 2]>),
}

An enum representing a primitive value from a DICOM element. The result of decoding an element's data value may be one of the enumerated types depending on its content and value representation.

Multiple elements are contained in a smallvec vector, conveniently aliased to the type C.

See the macro dicom_value! for a more intuitive means of constructing these values. Alternatively, From conversions into PrimitiveValue exist for single element types, including numeric types, String, and &str.

Example

let value = PrimitiveValue::from("Smith^John");
assert_eq!(value, PrimitiveValue::Str("Smith^John".to_string()));
assert_eq!(value.multiplicity(), 1);

let value = PrimitiveValue::from(512_u16);
assert_eq!(value, PrimitiveValue::U16(smallvec![512]));

Variants

Empty

No data. Usually employed for zero-lengthed values.

Strs(SmallVec<[String; 2]>)

A sequence of strings. Used for AE, AS, PN, SH, CS, LO, UI and UC. Can also be used for IS, SS, DS, DA, DT and TM when decoding with format preservation.

Str(String)

A single string. Used for ST, LT, UT and UR, which are never multi-valued.

Tags(SmallVec<[Tag; 2]>)

A sequence of attribute tags. Used specifically for AT.

U8(SmallVec<[u8; 2]>)

The value is a sequence of unsigned 16-bit integers. Used for OB and UN.

I16(SmallVec<[i16; 2]>)

The value is a sequence of signed 16-bit integers. Used for SS.

U16(SmallVec<[u16; 2]>)

A sequence of unsigned 168-bit integers. Used for US and OW.

I32(SmallVec<[i32; 2]>)

A sequence of signed 32-bit integers. Used for SL and IS.

U32(SmallVec<[u32; 2]>)

A sequence of unsigned 32-bit integers. Used for UL and OL.

I64(SmallVec<[i64; 2]>)

A sequence of signed 64-bit integers. Used for SV.

U64(SmallVec<[u64; 2]>)

A sequence of unsigned 64-bit integers. Used for UV and OV.

F32(SmallVec<[f32; 2]>)

The value is a sequence of 32-bit floating point numbers. Used for OF and FL.

F64(SmallVec<[f64; 2]>)

The value is a sequence of 64-bit floating point numbers. Used for OD and FD, DS.

Date(SmallVec<[NaiveDate; 2]>)

A sequence of complete dates. Used for the DA representation.

DateTime(SmallVec<[DateTime<FixedOffset>; 2]>)

A sequence of complete date-time values. Used for the DT representation.

Time(SmallVec<[NaiveTime; 2]>)

A sequence of complete time values. Used for the TM representation.

Implementations

`impl PrimitiveValue`[src]

`pub fn new_u16(value: u16) -> Self`[src]

Create a single unsigned 16-bit value.

`pub fn new_u32(value: u32) -> Self`[src]

Create a single unsigned 32-bit value.

`pub fn new_i32(value: u32) -> Self`[src]

Create a single I32 value.

`pub fn multiplicity(&self) -> u32`[src]

Obtain the number of individual elements. This number may not match the DICOM value multiplicity in some value representations.

`pub fn calculate_byte_len(&self) -> usize`[src]

Determine the length of the DICOM value in its encoded form.

In other words, this is the number of bytes that the value would need to occupy in a DICOM file, without compression and without the element header. The output is always an even number, so as to consider the mandatory trailing padding.

This method is particularly useful for presenting an estimated space occupation to the end user. However, consumers should not depend on this number for decoding or encoding values. The calculated number does not need to match the length of the original byte stream from where the value was originally decoded.

`pub fn to_str(&self) -> Cow<'_, str>`[src]

Convert the primitive value into a string representation.

String values already encoded with the Str and Strs variants are provided as is. In the case of Strs, the strings are first joined together with a backslash ('\\'). All other type variants are first converted to a string, then joined together with a backslash.

Note: As the process of reading a DICOM value may not always preserve its original nature, it is not guaranteed that to_str() returns a string with the exact same byte sequence as the one originally found at the source of the value, even for the string variants. Therefore, this method is not reliable for compliant DICOM serialization.

Examples

assert_eq!(
    dicom_value!(Str, "Smith^John").to_str(),
    "Smith^John",
);
assert_eq!(
    dicom_value!(Date, NaiveDate::from_ymd(2014, 10, 12)).to_str(),
    "20141012",
);
assert_eq!(
    dicom_value!(Strs, [
        "DERIVED",
        "PRIMARY",
        "WHOLE BODY",
        "EMISSION",
    ])
    .to_str(),
    "DERIVED\\PRIMARY\\WHOLE BODY\\EMISSION",
);

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

Convert the primitive value into a multi-string representation.

String values already encoded with the Str and Strs variants are provided as is. All other type variants are first converted to a string, then collected into a vector.

Note: As the process of reading a DICOM value may not always preserve its original nature, it is not guaranteed that to_multi_str() returns strings with the exact same byte sequence as the one originally found at the source of the value, even for the string variants. Therefore, this method is not reliable for compliant DICOM serialization.

Examples

assert_eq!(
    dicom_value!(Strs, [
        "DERIVED",
        "PRIMARY",
        "WHOLE BODY",
        "EMISSION",
    ])
    .to_multi_str(),
    &["DERIVED", "PRIMARY", "WHOLE BODY", "EMISSION"][..],
);

assert_eq!(
    dicom_value!(Str, "Smith^John").to_multi_str(),
    &["Smith^John"][..],
);

assert_eq!(
    dicom_value!(Date, NaiveDate::from_ymd(2014, 10, 12)).to_multi_str(),
    &["20141012"][..],
);

assert_eq!(
    dicom_value!(I64, [128, 256, 512]).to_multi_str(),
    &["128", "256", "512"][..],
);

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

Retrieve this DICOM value as raw bytes.

Binary numeric values are returned with a reintepretation of the holding vector's occupied data block as bytes, without copying, under the platform's native byte order.

String values already encoded with the Str and Strs variants are provided as their respective bytes in UTF-8. In the case of Strs, the strings are first joined together with a backslash ('\\'). Other type variants are first converted to a string, joined together with a backslash, then turned into a byte vector. For values which are inherently textual according the standard, this is equivalent to calling as_bytes() after to_str().

Note: As the process of reading a DICOM value may not always preserve its original nature, it is not guaranteed that to_bytes() returns the same byte sequence as the one originally found at the source of the value. Therefore, this method is not reliable for compliant DICOM serialization.

Examples

U8 provides a straight, zero-copy slice of bytes.


assert_eq!(
    PrimitiveValue::U8(smallvec![
        1, 2, 5,
    ]).to_bytes(),
    &[1, 2, 5][..],
);

Other values are converted to text first.

assert_eq!(
    PrimitiveValue::from("Smith^John").to_bytes(),
    &b"Smith^John"[..],
);
assert_eq!(
    PrimitiveValue::from(NaiveDate::from_ymd(2014, 10, 12))
    .to_bytes(),
    &b"20141012"[..],
);
assert_eq!(
    dicom_value!(Strs, [
        "DERIVED",
        "PRIMARY",
        "WHOLE BODY",
        "EMISSION",
    ])
    .to_bytes(),
    &b"DERIVED\\PRIMARY\\WHOLE BODY\\EMISSION"[..],
);

`pub fn to_int<T>(&self) -> Result<T, ConvertValueError> where T: NumCast, T: FromStr<Err = ParseIntError>,` [src]

Retrieve a single integer of type T from this value.

If the value is already represented as an integer, it is returned after a conversion to the target type. An error is returned if the integer cannot be represented by the given integer type. If the value is a string or sequence of strings, the first string is parsed to obtain an integer, potentially failing if the string does not represent a valid integer. The string is stripped of trailing whitespace before parsing, in order to account for the possible padding to even length. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Note that this method does not enable the conversion of floating point numbers to integers via truncation. If this is intentional, retrieve a float via to_float32 or to_float64 instead, then cast it to an integer.

Example


assert_eq!(
    PrimitiveValue::I32(smallvec![
        1, 2, 5,
    ])
    .to_int::<u32>().ok(),
    Some(1_u32),
);

assert_eq!(
    PrimitiveValue::from("505 ").to_int::<i32>().ok(),
    Some(505),
);

`pub fn to_multi_int<T>(&self) -> Result<Vec<T>, ConvertValueError> where T: NumCast, T: FromStr<Err = ParseIntError>,` [src]

Retrieve a sequence of integers of type T from this value.

If the values is already represented as an integer, it is returned after a NumCast conversion to the target type. An error is returned if any of the integers cannot be represented by the given integer type. If the value is a string or sequence of strings, each string is parsed to obtain an integer, potentially failing if the string does not represent a valid integer. The string is stripped of trailing whitespace before parsing, in order to account for the possible padding to even length. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Note that this method does not enable the conversion of floating point numbers to integers via truncation. If this is intentional, retrieve a float via to_float32 or to_float64 instead, then cast it to an integer.

Example


assert_eq!(
    PrimitiveValue::I32(smallvec![
        1, 2, 5,
    ])
    .to_multi_int::<u32>().ok(),
    Some(vec![1_u32, 2, 5]),
);

assert_eq!(
    dicom_value!(Strs, ["5050", "23 "]).to_multi_int::<i32>().ok(),
    Some(vec![5050, 23]),
);

`pub fn to_float32(&self) -> Result<f32, ConvertValueError>`[src]

Retrieve one single-precision floating point from this value.

If the value is already represented as a number, it is returned after a conversion to f32. An error is returned if the number cannot be represented by the given number type. If the value is a string or sequence of strings, the first string is parsed to obtain a number, potentially failing if the string does not represent a valid number. The string is stripped of trailing whitespace before parsing, in order to account for the possible padding to even length. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::F32(smallvec![
        1.5, 2., 5.,
    ])
    .to_float32().ok(),
    Some(1.5_f32),
);

assert_eq!(
    PrimitiveValue::from("-6.75 ").to_float32().ok(),
    Some(-6.75),
);

`pub fn to_multi_float32(&self) -> Result<Vec<f32>, ConvertValueError>`[src]

Retrieve a sequence of single-precision floating point numbers from this value.

If the value is already represented as numbers, they are returned after a conversion to f32. An error is returned if any of the numbers cannot be represented by an f32. If the value is a string or sequence of strings, the strings are parsed to obtain a number, potentially failing if the string does not represent a valid number. The string is stripped of trailing whitespace before parsing, in order to account for the possible padding to even length. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::F32(smallvec![
        1.5, 2., 5.,
    ])
    .to_multi_float32().ok(),
    Some(vec![1.5_f32, 2., 5.]),
);

assert_eq!(
    PrimitiveValue::from("-6.75 ").to_multi_float32().ok(),
    Some(vec![-6.75]),
);

`pub fn to_float64(&self) -> Result<f64, ConvertValueError>`[src]

Retrieve one double-precision floating point from this value.

If the value is already represented as a number, it is returned after a conversion to f64. An error is returned if the number cannot be represented by the given number type. If the value is a string or sequence of strings, the first string is parsed to obtain a number, potentially failing if the string does not represent a valid number. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::F64(smallvec![
        1.5, 2., 5.,
    ])
    .to_float64().ok(),
    Some(1.5_f64),
);

assert_eq!(
    PrimitiveValue::from("-6.75 ").to_float64().ok(),
    Some(-6.75),
);

`pub fn to_multi_float64(&self) -> Result<Vec<f64>, ConvertValueError>`[src]

Retrieve a sequence of double-precision floating point numbers from this value.

If the value is already represented as numbers, they are returned after a conversion to f64. An error is returned if any of the numbers cannot be represented by an f64. If the value is a string or sequence of strings, the strings are parsed to obtain a number, potentially failing if the string does not represent a valid number. The string is stripped of trailing whitespace before parsing, in order to account for the possible padding to even length. If the value is a sequence of U8 bytes, the bytes are individually interpreted as independent numbers. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::F64(smallvec![
        1.5, 2., 5.,
    ])
    .to_multi_float64().ok(),
    Some(vec![1.5_f64, 2., 5.]),
);

assert_eq!(
    PrimitiveValue::from("-6.75 ").to_multi_float64().ok(),
    Some(vec![-6.75]),
);

`pub fn to_date(&self) -> Result<NaiveDate, ConvertValueError>`[src]

Retrieve a single DICOM date from this value.

If the value is already represented as a date, it is returned as is. If the value is a string or sequence of strings, the first string is decoded to obtain a date, potentially failing if the string does not represent a valid date. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::Date(smallvec![
        NaiveDate::from_ymd(2014, 10, 12),
    ])
    .to_date().ok(),
    Some(NaiveDate::from_ymd(2014, 10, 12)),
);

assert_eq!(
    PrimitiveValue::Strs(smallvec![
        "20141012".to_string(),
    ])
    .to_date().ok(),
    Some(NaiveDate::from_ymd(2014, 10, 12)),
);

`pub fn to_multi_date(&self) -> Result<Vec<NaiveDate>, ConvertValueError>`[src]

Retrieve the full sequence of DICOM dates from this value.

If the value is already represented as a sequence of dates, it is returned as is. If the value is a string or sequence of strings, the strings are decoded to obtain a date, potentially failing if any of the strings does not represent a valid date. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string, then as a backslash-separated list of dates. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::Date(smallvec![
        NaiveDate::from_ymd(2014, 10, 12),
    ]).to_multi_date().ok(),
    Some(vec![NaiveDate::from_ymd(2014, 10, 12)]),
);

assert_eq!(
    PrimitiveValue::Strs(smallvec![
        "20141012".to_string(),
        "20200828".to_string(),
    ]).to_multi_date().ok(),
    Some(vec![
        NaiveDate::from_ymd(2014, 10, 12),
        NaiveDate::from_ymd(2020, 8, 28),
    ]),
);

`pub fn to_time(&self) -> Result<NaiveTime, ConvertValueError>`[src]

Retrieve a single DICOM time from this value.

If the value is already represented as a time, it is returned as is. If the value is a string or sequence of strings, the first string is decoded to obtain a time, potentially failing if the string does not represent a valid time. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::from(NaiveTime::from_hms(11, 2, 45)).to_time().ok(),
    Some(NaiveTime::from_hms(11, 2, 45)),
);

assert_eq!(
    PrimitiveValue::from("110245.78").to_time().ok(),
    Some(NaiveTime::from_hms_milli(11, 2, 45, 780)),
);

`pub fn to_multi_time(&self) -> Result<Vec<NaiveTime>, ConvertValueError>`[src]

Retrieve the full sequence of DICOM times from this value.

If the value is already represented as a sequence of times, it is returned as is. If the value is a string or sequence of strings, the strings are decoded to obtain a date, potentially failing if any of the strings does not represent a valid date. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string, then as a backslash-separated list of times. Otherwise, the operation fails.

Example


assert_eq!(
    PrimitiveValue::from(NaiveTime::from_hms(22, 58, 2)).to_multi_time().ok(),
    Some(vec![NaiveTime::from_hms(22, 58, 2)]),
);

assert_eq!(
    PrimitiveValue::Strs(smallvec![
        "225802".to_string(),
        "225916.742388".to_string(),
    ]).to_multi_time().ok(),
    Some(vec![
        NaiveTime::from_hms(22, 58, 2),
        NaiveTime::from_hms_micro(22, 59, 16, 742388),
    ]),
);

`pub fn to_datetime( &self, default_offset: FixedOffset ) -> Result<DateTime<FixedOffset>, ConvertValueError>`[src]

Retrieve a single DICOM date-time from this value.

If the value is already represented as a date-time, it is returned as is. If the value is a string or sequence of strings, the first string is decoded to obtain a date-time, potentially failing if the string does not represent a valid time. If the value in its textual form does not present a time zone, default_offset is used. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string. Otherwise, the operation fails.

Users of this method are advised to retrieve the default time zone offset from the same source of the DICOM value.

Example

let default_offset = FixedOffset::east(0);

assert_eq!(
    PrimitiveValue::from(
        FixedOffset::east(0)
            .ymd(2012, 12, 21)
            .and_hms(9, 30, 1)
    ).to_datetime(default_offset).ok(),
    Some(FixedOffset::east(0)
        .ymd(2012, 12, 21)
        .and_hms(9, 30, 1)
    ),
);

assert_eq!(
    PrimitiveValue::from("20121221093001")
        .to_datetime(default_offset).ok(),
    Some(FixedOffset::east(0)
        .ymd(2012, 12, 21)
        .and_hms(9, 30, 1)
    ),
);

`pub fn to_multi_datetime( &self, default_offset: FixedOffset ) -> Result<Vec<DateTime<FixedOffset>>, ConvertValueError>`[src]

Retrieve the full sequence of DICOM date-times from this value.

If the value is already represented as a sequence of date-times, it is returned as is. If the value is a string or sequence of strings, the strings are decoded to obtain a date, potentially failing if any of the strings does not represent a valid date. If the value is a sequence of U8 bytes, the bytes are first interpreted as an ASCII character string, then as a backslash-separated list of date-times. Otherwise, the operation fails.

Example

let default_offset = FixedOffset::east(0);

assert_eq!(
    PrimitiveValue::from(
        FixedOffset::east(0)
            .ymd(2012, 12, 21)
            .and_hms(9, 30, 1)
    ).to_multi_datetime(default_offset).ok(),
    Some(vec![FixedOffset::east(0)
        .ymd(2012, 12, 21)
        .and_hms(9, 30, 1)
    ]),
);

assert_eq!(
    PrimitiveValue::Strs(smallvec![
        "20121221093001".to_string(),
        "20180102100123".to_string(),
    ]).to_multi_datetime(default_offset).ok(),
    Some(vec![
        FixedOffset::east(0)
            .ymd(2012, 12, 21)
            .and_hms(9, 30, 1),
        FixedOffset::east(0)
            .ymd(2018, 1, 2)
            .and_hms(10, 1, 23)
    ]),
);

`impl PrimitiveValue`[src]

Per variant, strongly checked getters to DICOM values.

Conversions from one representation to another do not take place when using these methods.

`pub fn string(&self) -> Result<&str, CastValueError>`[src]

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>`[src]

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.