Skip to main content

dcmnorm_parser/stateful/
decode.rs

1//! Module holding a stateful DICOM data decoding abstraction,
2//! which also supports text decoding.
3
4use crate::util::n_times;
5use dcmnorm_core::dictionary::VirtualVr;
6use dcmnorm_core::header::{DataElementHeader, HasLength, Length, SequenceItemHeader, Tag, VR};
7use dcmnorm_core::value::deserialize::{
8    parse_date_partial, parse_datetime_partial, parse_time_partial,
9};
10use dcmnorm_core::value::PrimitiveValue;
11use dcmnorm_dictionary::StandardDataDictionary;
12use dcmnorm_encoding::decode::basic::{BasicDecoder, LittleEndianBasicDecoder};
13use dcmnorm_encoding::decode::explicit_le::ExplicitVRLittleEndianDecoder;
14use dcmnorm_encoding::decode::implicit_le::StandardImplicitVRLittleEndianDecoder;
15use dcmnorm_encoding::decode::{BasicDecode, DecodeFrom};
16use dcmnorm_encoding::text::{
17    validate_da, validate_dt, validate_tm, DefaultCharacterSetCodec, SpecificCharacterSet,
18    TextCodec, TextValidationOutcome,
19};
20use dcmnorm_encoding::transfer_syntax::{DynDecoder, TransferSyntax};
21use snafu::{Backtrace, OptionExt, ResultExt, Snafu};
22use std::io::Read;
23use std::{fmt::Debug, io::Seek, io::SeekFrom};
24
25#[derive(Debug, Snafu)]
26#[non_exhaustive]
27pub enum Error {
28    #[snafu(display("Decoding in transfer syntax {} is unsupported", ts))]
29    UnsupportedTransferSyntax {
30        ts: &'static str,
31        backtrace: Backtrace,
32    },
33
34    #[snafu(display("Unsupported character set {:?}", charset))]
35    UnsupportedCharacterSet {
36        charset: SpecificCharacterSet,
37        backtrace: Backtrace,
38    },
39
40    #[snafu(display("Attempted to read non-primitive value at position {}", position))]
41    NonPrimitiveType { position: u64, backtrace: Backtrace },
42
43    #[snafu(display(
44        "Undefined value length of element tagged {} at position {}",
45        tag,
46        position
47    ))]
48    UndefinedValueLength {
49        tag: Tag,
50        position: u64,
51        backtrace: Backtrace,
52    },
53
54    #[snafu(display("Could not decode element header at position {}", position))]
55    DecodeElementHeader {
56        position: u64,
57        #[snafu(backtrace)]
58        source: dcmnorm_encoding::decode::Error,
59    },
60
61    #[snafu(display("Could not decode element header at position {}", position))]
62    DecodeItemHeader {
63        position: u64,
64        #[snafu(backtrace)]
65        source: dcmnorm_encoding::decode::Error,
66    },
67
68    #[snafu(display("Could not decode text at position {}", position))]
69    DecodeText {
70        position: u64,
71        #[snafu(backtrace)]
72        source: dcmnorm_encoding::text::DecodeTextError,
73    },
74
75    #[snafu(display("Could not read value from source at position {}", position))]
76    ReadValueData {
77        position: u64,
78        source: std::io::Error,
79        backtrace: Backtrace,
80    },
81
82    #[snafu(display(
83        "Could not move source cursor from position {} to {}",
84        position,
85        new_position
86    ))]
87    SeekReader {
88        position: u64,
89        new_position: u64,
90        source: std::io::Error,
91        backtrace: Backtrace,
92    },
93
94    #[snafu(display("Failed value deserialization at position {}", position))]
95    DeserializeValue {
96        position: u64,
97        source: dcmnorm_core::value::deserialize::Error,
98    },
99
100    #[snafu(display("Invalid integer value at position {}", position))]
101    ReadInt {
102        position: u64,
103        source: std::num::ParseIntError,
104    },
105
106    #[snafu(display("Invalid float value at position {}", position))]
107    ReadFloat {
108        position: u64,
109        source: std::num::ParseFloatError,
110    },
111
112    #[snafu(display("Invalid Date value element `{}` at position {}", string, position))]
113    InvalidDateValue {
114        position: u64,
115        string: String,
116        backtrace: Backtrace,
117    },
118
119    #[snafu(display("Invalid Time value element `{}` at position {}", string, position))]
120    InvalidTimeValue {
121        position: u64,
122        string: String,
123        backtrace: Backtrace,
124    },
125
126    #[snafu(display("Invalid DateTime value element `{}` at position {}", string, position))]
127    InvalidDateTimeValue {
128        position: u64,
129        string: String,
130        backtrace: Backtrace,
131    },
132}
133
134pub type Result<T, E = Error> = std::result::Result<T, E>;
135
136pub trait StatefulDecode {
137    type Reader: Read;
138
139    /// Same as `Decode::decode_header` over the bound source.
140    fn decode_header(&mut self) -> Result<DataElementHeader>;
141
142    /// Same as `Decode::decode_item_header` over the bound source.
143    fn decode_item_header(&mut self) -> Result<SequenceItemHeader>;
144
145    /// Eagerly read the following data in the source as a primitive data
146    /// value. When reading values in text form, a conversion to a more
147    /// maleable type is attempted. Namely, numbers in text form (IS, DS) are
148    /// converted to the corresponding binary number types, and date/time
149    /// instances are decoded into binary date/time objects of types defined in
150    /// the `chrono` crate. To avoid this conversion, see
151    /// `read_value_preserved`.
152    ///
153    /// # Errors
154    ///
155    /// Returns an error on I/O problems, or if the header VR describes a
156    /// sequence, which in that case this method should not be used.
157    fn read_value(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue>;
158
159    /// Eagerly read the following data in the source as a primitive data
160    /// value. Unlike `read_value`, this method will preserve the DICOM value's
161    /// original format: numbers saved as text, as well as dates and times, are
162    /// read as strings.
163    ///
164    /// # Errors
165    ///
166    /// Returns an error on I/O problems, or if the header VR describes a
167    /// sequence, which in that case this method should not be used.
168    fn read_value_preserved(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue>;
169
170    /// Eagerly read the following data in the source as a primitive data
171    /// value as bytes, regardless of its value representation.
172    ///
173    /// # Errors
174    ///
175    /// Returns an error on I/O problems, or if the header VR describes a
176    /// sequence, which in that case this method should not be used.
177    fn read_value_bytes(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue>;
178
179    /// Read the following number of bytes into a vector.
180    fn read_to_vec(&mut self, length: u32, vec: &mut Vec<u8>) -> Result<()>;
181
182    /// Read the following number of bytes
183    /// as a sequence of unsigned 32 bit integers
184    /// into a vector.
185    fn read_u32_to_vec(&mut self, length: u32, vec: &mut Vec<u32>) -> Result<()>;
186
187    /// Read the following number of bytes into a generic writer.
188    fn read_to<W>(&mut self, length: u32, out: W) -> Result<()>
189    where
190        Self: Sized,
191        W: std::io::Write;
192
193    /// Skip the following bytes into a vector,
194    /// counting them as if they were read.
195    fn skip_bytes(&mut self, length: u32) -> Result<()>;
196
197    /// Reposition the reader so that it starts reading
198    /// at the reader's given position.
199    ///
200    /// The number of bytes read is not expected to be modified.
201    fn seek(&mut self, position: u64) -> Result<()>
202    where
203        Self::Reader: Seek;
204
205    /// Skip the following `length` bytes by seeking past them rather than reading them,
206    /// counting them as if they were read (the same position bookkeeping as `skip_bytes`, which
207    /// defined-length sequence/item tracking relies on). Seeking past the end of the source is
208    /// not detected here - callers that need that must check the resulting range themselves.
209    fn skip_bytes_seek(&mut self, length: u64) -> Result<()>
210    where
211        Self::Reader: Seek;
212
213    /// Retrieve the known position of the inner reader source.
214    /// If the stateful decoder was constructed at the beginning of the reader,
215    /// this equals to the number of bytes read so far.
216    fn position(&self) -> u64;
217
218    /// Enter the content of an undefined-length `UN` element, which PS3.5 6.2.2 requires to be
219    /// encoded as a sequence in Implicit VR Little Endian whatever the transfer syntax: element
220    /// headers are decoded as Implicit VR Little Endian until the matching
221    /// [`leave_implicit_vr`](StatefulDecode::leave_implicit_vr). Calls nest.
222    fn enter_implicit_vr(&mut self) {}
223
224    /// Leave the innermost undefined-length `UN` content entered with
225    /// [`enter_implicit_vr`](StatefulDecode::enter_implicit_vr).
226    fn leave_implicit_vr(&mut self) {}
227}
228
229/// Alias for a dynamically resolved DICOM stateful decoder. Although the data
230/// source may be known at compile time, the required decoder may vary
231/// according to an object's transfer syntax.
232pub type DynStatefulDecoder<S> = StatefulDecoder<DynDecoder<S>, S>;
233
234/// The initial capacity of the `DicomParser` buffer.
235const PARSER_BUFFER_CAPACITY: usize = 2048;
236
237/// Defines a special override for
238/// how text of certain value representations is decoded.
239#[derive(Debug, Default, Copy, Clone, Eq, Hash, PartialEq)]
240#[non_exhaustive]
241pub enum CharacterSetOverride {
242    /// The standard behavior.
243    /// Use the declared character set for
244    /// LO, LT, PN, SH, ST, UC, UT.
245    /// Use the default character repertoire
246    /// for AE, AS, CS.
247    #[default]
248    None,
249
250    /// Use the declared character set to decode text
251    /// for more value representations,
252    /// including CS and UR.
253    ///
254    /// DA, TM, DT, IS, DS, and FD will not be affected by this change.
255    AnyVr,
256}
257
258/// A stateful abstraction for the full DICOM content reading process.
259/// This type encapsulates the necessary codecs in order
260/// to be as autonomous as possible in the DICOM content reading
261/// process.
262/// `S` is the generic parameter type for the original source,
263/// `D` is the parameter type that the decoder interprets as,
264/// whereas `DB` is the parameter type for the basic decoder.
265/// `TC` defines the text codec used underneath.
266#[derive(Debug)]
267pub struct StatefulDecoder<D, S, BD = BasicDecoder, TC = SpecificCharacterSet> {
268    from: S,
269    decoder: D,
270    basic: BD,
271    text: TC,
272    charset_override: CharacterSetOverride,
273    buffer: Vec<u8>,
274    /// the assumed position of the reader source
275    position: u64,
276    signed_pixeldata: Option<bool>,
277    /// how many undefined-length `UN` sequences enclose the current position: their content is
278    /// always Implicit VR Little Endian (PS3.5 6.2.2), decoded with `implicit_vr`
279    implicit_vr_depth: u32,
280    implicit_vr: StandardImplicitVRLittleEndianDecoder,
281}
282
283impl<S> StatefulDecoder<DynDecoder<S>, S> {
284    /// Create a new DICOM parser for the given transfer syntax, character set,
285    /// and assumed position of the reader source.
286    pub fn new_with(
287        from: S,
288        ts: &TransferSyntax,
289        charset: SpecificCharacterSet,
290        position: u64,
291    ) -> Result<Self>
292    where
293        S: Read,
294    {
295        let basic = ts.basic_decoder();
296        let decoder = ts
297            .decoder_for::<S>()
298            .context(UnsupportedTransferSyntaxSnafu { ts: ts.name() })?;
299
300        Ok(StatefulDecoder::new_with_position(
301            from, decoder, basic, charset, position,
302        ))
303    }
304
305    /// Create a new DICOM parser for the given transfer syntax,
306    /// character set override, and assumed position of the reader source.
307    pub fn new_with_override(
308        from: S,
309        ts: &TransferSyntax,
310        charset: SpecificCharacterSet,
311        charset_override: CharacterSetOverride,
312        position: u64,
313    ) -> Result<Self>
314    where
315        S: Read,
316    {
317        let basic = ts.basic_decoder();
318        let decoder = ts
319            .decoder_for::<S>()
320            .context(UnsupportedTransferSyntaxSnafu { ts: ts.name() })?;
321
322        Ok(StatefulDecoder::new_with_all_options(
323            from,
324            decoder,
325            basic,
326            charset,
327            charset_override,
328            position,
329        ))
330    }
331
332    /// Create a new DICOM parser for the given transfer syntax
333    /// and assumed position of the reader source.
334    ///
335    /// The default character set is assumed
336    /// until a _Specific Character Set_ attribute is found.
337    pub fn new_with_ts(from: S, ts: &TransferSyntax, position: u64) -> Result<Self>
338    where
339        S: Read,
340    {
341        Self::new_with(from, ts, SpecificCharacterSet::default(), position)
342    }
343}
344
345/// Type alias for the DICOM parser of a file's Meta group.
346pub type FileHeaderParser<S> = StatefulDecoder<
347    ExplicitVRLittleEndianDecoder,
348    S,
349    LittleEndianBasicDecoder,
350    DefaultCharacterSetCodec,
351>;
352
353impl<S> FileHeaderParser<S>
354where
355    S: Read,
356{
357    /// Create a new DICOM stateful decoder for reading the file meta header,
358    /// which is always in _Explicit VR Little Endian_.
359    pub fn file_header_parser(from: S) -> Self {
360        Self {
361            from,
362            basic: LittleEndianBasicDecoder,
363            decoder: ExplicitVRLittleEndianDecoder::default(),
364            text: DefaultCharacterSetCodec,
365            charset_override: Default::default(),
366            buffer: Vec::with_capacity(PARSER_BUFFER_CAPACITY),
367            position: 0,
368            signed_pixeldata: None,
369            implicit_vr_depth: 0,
370            implicit_vr: Default::default(),
371        }
372    }
373}
374
375impl<D, S, BD, TC> StatefulDecoder<D, S, BD, TC>
376where
377    BD: BasicDecode,
378    TC: TextCodec,
379{
380    /// Create a new DICOM stateful decoder from its parts.
381    #[inline]
382    pub fn new(from: S, decoder: D, basic: BD, text: TC) -> StatefulDecoder<D, S, BD, TC> {
383        Self::new_with_position(from, decoder, basic, text, 0)
384    }
385
386    /// Create a new DICOM stateful decoder from its parts,
387    /// while assuming a base reading position.
388    ///
389    /// `position` should be calculated with care.
390    /// Decoding or parsing errors may occur
391    /// if this position does not match the real position of the reader.
392    #[inline]
393    pub fn new_with_position(from: S, decoder: D, basic: BD, text: TC, position: u64) -> Self {
394        Self::new_with_all_options(from, decoder, basic, text, Default::default(), position)
395    }
396
397    #[inline]
398    pub(crate) fn new_with_all_options(
399        from: S,
400        decoder: D,
401        basic: BD,
402        text: TC,
403        charset_override: CharacterSetOverride,
404        position: u64,
405    ) -> Self {
406        Self {
407            from,
408            basic,
409            decoder,
410            text,
411            charset_override,
412            buffer: Vec::with_capacity(PARSER_BUFFER_CAPACITY),
413            position,
414            signed_pixeldata: None,
415            implicit_vr_depth: 0,
416            implicit_vr: Default::default(),
417        }
418    }
419}
420
421impl<D, S, BD, TC> StatefulDecoder<D, S, BD, TC>
422where
423    S: Seek,
424    BD: BasicDecode,
425    TC: TextCodec,
426{
427    /// Create a new DICOM stateful decoder from its parts,
428    /// while determining the data source's current position via `seek`.
429    pub fn new_positioned(
430        mut from: S,
431        decoder: D,
432        basic: BD,
433        text: TC,
434    ) -> Result<Self, std::io::Error> {
435        let position = from.stream_position()?;
436        Ok(Self::new_with_position(
437            from, decoder, basic, text, position,
438        ))
439    }
440}
441
442/// Read `n` fixed-width numeric elements via `$self.basic.$decode_fn`, in bounded chunks rather
443/// than allocating a `SmallVec` sized to the full, untrusted `n` upfront - `n` is always derived
444/// from a file-controlled length field here, so a corrupt/malicious file lying about a huge
445/// element count can only ever force a single bounded chunk's worth of allocation before the
446/// decode call's own read fails against the actually-truncated stream. Same reasoning as
447/// `StatefulDecoder::read_into_buffer`/`read_u32`, generalized over element type since
448/// `decode_ss_into`/`decode_fl_into`/etc. all take a pre-sized `&mut [T]` rather than supporting
449/// incremental growth the way `Read::read_to_end` does.
450macro_rules! read_numeric_chunked {
451    ($self:ident, $n:expr, $decode_fn:ident, $zero:expr) => {{
452        const CHUNK: usize = 65536;
453        let mut vec = smallvec::SmallVec::new();
454        let mut remaining: usize = $n;
455        while remaining > 0 {
456            let batch = remaining.min(CHUNK);
457            let base = vec.len();
458            vec.resize(base + batch, $zero);
459            $self
460                .basic
461                .$decode_fn(&mut $self.from, &mut vec[base..])
462                .context(ReadValueDataSnafu {
463                    position: $self.position,
464                })?;
465            remaining -= batch;
466        }
467        vec
468    }};
469}
470
471impl<D, S, BD, TC> StatefulDecoder<D, S, BD, TC>
472where
473    D: DecodeFrom<S>,
474    BD: BasicDecode,
475    S: Read,
476    TC: TextCodec,
477{
478    // ---------------- private methods ---------------------
479
480    fn require_known_length(&self, header: &DataElementHeader) -> Result<usize> {
481        header
482            .length()
483            .get()
484            .map(|len| len as usize)
485            .context(UndefinedValueLengthSnafu {
486                position: self.position,
487                tag: header.tag,
488            })
489    }
490
491    /// Read exactly `len` bytes into `self.buffer`, replacing its previous contents.
492    ///
493    /// `len` comes from an untrusted, file-controlled 32-bit length field (up to ~4GiB), so this
494    /// deliberately does not pre-allocate `len` bytes upfront the way `resize_with`/`vec![0; len]`
495    /// would - a corrupt or malicious file whose true size is a few hundred bytes but which
496    /// declares a multi-gigabyte element length would otherwise force an allocation attempt that
497    /// large before a single byte is even read, and a failing allocation of that shape aborts the
498    /// process (`handle_alloc_error`) rather than returning a catchable error. Reading via `Take` and
499    /// `read_to_end` instead grows the buffer only in proportion to bytes actually available on
500    /// the stream, so a truncated/lying length surfaces as a clean `ReadValueData` error as soon
501    /// as the real data runs out, never as a runaway allocation.
502    fn read_into_buffer(&mut self, len: usize) -> Result<()> {
503        self.buffer.clear();
504        (&mut self.from)
505            .take(len as u64)
506            .read_to_end(&mut self.buffer)
507            .context(ReadValueDataSnafu {
508                position: self.position,
509            })?;
510        if self.buffer.len() != len {
511            let actual = self.buffer.len();
512            return Err(std::io::Error::new(
513                std::io::ErrorKind::UnexpectedEof,
514                format!("declared value length {len} exceeds available data ({actual} bytes read)"),
515            ))
516            .context(ReadValueDataSnafu {
517                position: self.position,
518            });
519        }
520        Ok(())
521    }
522
523    fn read_value_tag(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
524        let len = self.require_known_length(header)?;
525
526        // tags
527        let ntags = len >> 2;
528        let parts: Result<_> = n_times(ntags)
529            .map(|_| {
530                self.basic
531                    .decode_tag(&mut self.from)
532                    .context(ReadValueDataSnafu {
533                        position: self.position,
534                    })
535            })
536            .collect();
537        self.position += len as u64;
538        Ok(PrimitiveValue::Tags(parts?))
539    }
540
541    fn read_value_ob(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
542        // Note: this function always expects a defined length OB value
543        // (pixel sequence detection needs to be done by the caller)
544        let len = self.require_known_length(header)?;
545
546        // sequence of 8-bit integers (or arbitrary byte data). This is the PixelData path for
547        // every native 8-bit image, so read straight into the value's own allocation (handed to
548        // the SmallVec without a copy) rather than via `self.buffer` + `SmallVec::from_slice`,
549        // which copied and page-faulted the whole value twice. `len` is untrusted and
550        // file-controlled, so the upfront reservation is capped and fallible (see
551        // `read_into_buffer`'s doc comment): a lying length can at most reserve
552        // `MAX_VALUE_PREALLOC` of untouched address space before the read itself fails.
553        const MAX_VALUE_PREALLOC: usize = 256 << 20;
554        let mut buf = Vec::new();
555        let _ = buf.try_reserve_exact(len.min(MAX_VALUE_PREALLOC));
556        (&mut self.from)
557            .take(len as u64)
558            .read_to_end(&mut buf)
559            .context(ReadValueDataSnafu {
560                position: self.position,
561            })?;
562        if buf.len() != len {
563            let actual = buf.len();
564            return Err(std::io::Error::new(
565                std::io::ErrorKind::UnexpectedEof,
566                format!("declared value length {len} exceeds available data ({actual} bytes read)"),
567            ))
568            .context(ReadValueDataSnafu {
569                position: self.position,
570            });
571        }
572        self.position += len as u64;
573        Ok(PrimitiveValue::U8(smallvec::SmallVec::from_vec(buf)))
574    }
575
576    fn read_value_strs(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
577        let len = self.require_known_length(header)?;
578        // sequence of strings
579        self.read_into_buffer(len)?;
580
581        let use_charset_declared = match (self.charset_override, header.vr()) {
582            (CharacterSetOverride::AnyVr, _) => true,
583            (_, VR::AE) | (_, VR::CS) | (_, VR::AS) | (_, VR::UR) => false,
584            _ => true,
585        };
586
587        let parts: Result<_> = if use_charset_declared {
588            self.buffer
589                .split(|v| *v == b'\\')
590                .map(|slice| {
591                    self.text.decode(slice).context(DecodeTextSnafu {
592                        position: self.position,
593                    })
594                })
595                .collect()
596        } else {
597            self.buffer
598                .split(|v| *v == b'\\')
599                .map(|slice| {
600                    DefaultCharacterSetCodec
601                        .decode(slice)
602                        .context(DecodeTextSnafu {
603                            position: self.position,
604                        })
605                })
606                .collect()
607        };
608
609        self.position += len as u64;
610        Ok(PrimitiveValue::Strs(parts?))
611    }
612
613    fn read_value_str(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
614        let len = self.require_known_length(header)?;
615
616        // a single string
617        self.read_into_buffer(len)?;
618        self.position += len as u64;
619        Ok(PrimitiveValue::Str(
620            self.text
621                .decode(&self.buffer[..])
622                .context(DecodeTextSnafu {
623                    position: self.position,
624                })?,
625        ))
626    }
627
628    fn read_value_ss(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
629        // sequence of 16-bit signed integers
630        let len = self.require_known_length(header)?;
631
632        let n = len >> 1;
633        let vec = read_numeric_chunked!(self, n, decode_ss_into, 0i16);
634
635        self.position += len as u64;
636        Ok(PrimitiveValue::I16(vec))
637    }
638
639    fn read_value_fl(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
640        let len = self.require_known_length(header)?;
641        // sequence of 32-bit floats
642        let n = len >> 2;
643        let vec = read_numeric_chunked!(self, n, decode_fl_into, 0f32);
644        self.position += len as u64;
645        Ok(PrimitiveValue::F32(vec))
646    }
647
648    fn read_value_da(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
649        let len = self.require_known_length(header)?;
650        // sequence of dates
651
652        self.read_into_buffer(len)?;
653        let buf = trim_trail_empty_bytes(&self.buffer);
654        if buf.is_empty() {
655            return Ok(PrimitiveValue::Empty);
656        }
657
658        if validate_da(buf) != TextValidationOutcome::Ok {
659            let lossy_str = DefaultCharacterSetCodec
660                .decode(buf)
661                .unwrap_or_else(|_| "[byte stream]".to_string());
662            return InvalidDateValueSnafu {
663                position: self.position,
664                string: lossy_str,
665            }
666            .fail();
667        }
668        let vec: Result<_> = buf
669            .split(|b| *b == b'\\')
670            .map(|part| {
671                parse_date_partial(part)
672                    .map(|t| t.0)
673                    .context(DeserializeValueSnafu {
674                        position: self.position,
675                    })
676            })
677            .collect();
678        self.position += len as u64;
679        Ok(PrimitiveValue::Date(vec?))
680    }
681
682    fn read_value_ds(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
683        let len = self.require_known_length(header)?;
684        // sequence of doubles in text form
685
686        self.read_into_buffer(len)?;
687        let buf = trim_trail_empty_bytes(&self.buffer);
688        if buf.is_empty() {
689            return Ok(PrimitiveValue::Empty);
690        }
691
692        let parts: Result<_> = buf
693            .split(|b| *b == b'\\')
694            .map(|slice| {
695                let codec = DefaultCharacterSetCodec;
696                let txt = codec.decode(slice).context(DecodeTextSnafu {
697                    position: self.position,
698                })?;
699                let txt = txt.trim();
700                txt.parse::<f64>().context(ReadFloatSnafu {
701                    position: self.position,
702                })
703            })
704            .collect();
705        self.position += len as u64;
706        Ok(PrimitiveValue::F64(parts?))
707    }
708
709    fn read_value_dt(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
710        let len = self.require_known_length(header)?;
711        // sequence of datetimes
712
713        self.read_into_buffer(len)?;
714        let buf = trim_trail_empty_bytes(&self.buffer);
715        if buf.is_empty() {
716            return Ok(PrimitiveValue::Empty);
717        }
718
719        if validate_dt(buf) != TextValidationOutcome::Ok {
720            let lossy_str = DefaultCharacterSetCodec
721                .decode(buf)
722                .unwrap_or_else(|_| "[byte stream]".to_string());
723            return InvalidDateTimeValueSnafu {
724                position: self.position,
725                string: lossy_str,
726            }
727            .fail();
728        }
729        let vec: Result<_> = buf
730            .split(|b| *b == b'\\')
731            .map(|part| {
732                parse_datetime_partial(part).context(DeserializeValueSnafu {
733                    position: self.position,
734                })
735            })
736            .collect();
737
738        self.position += len as u64;
739        Ok(PrimitiveValue::DateTime(vec?))
740    }
741
742    fn read_value_is(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
743        let len = self.require_known_length(header)?;
744        // sequence of signed integers in text form
745        self.read_into_buffer(len)?;
746        let buf = trim_trail_empty_bytes(&self.buffer);
747        if buf.is_empty() {
748            return Ok(PrimitiveValue::Empty);
749        }
750
751        let parts: Result<_> = buf
752            .split(|v| *v == b'\\')
753            .map(|slice| {
754                let codec = DefaultCharacterSetCodec;
755                let txt = codec.decode(slice).context(DecodeTextSnafu {
756                    position: self.position,
757                })?;
758                let txt = txt.trim();
759                txt.parse::<i32>().context(ReadIntSnafu {
760                    position: self.position,
761                })
762            })
763            .collect();
764        self.position += len as u64;
765        Ok(PrimitiveValue::I32(parts?))
766    }
767
768    fn read_value_tm(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
769        let len = self.require_known_length(header)?;
770        // sequence of time instances
771
772        self.read_into_buffer(len)?;
773        let buf = trim_trail_empty_bytes(&self.buffer);
774        if buf.is_empty() {
775            return Ok(PrimitiveValue::Empty);
776        }
777
778        if validate_tm(buf) != TextValidationOutcome::Ok {
779            let lossy_str = DefaultCharacterSetCodec
780                .decode(buf)
781                .unwrap_or_else(|_| "[byte stream]".to_string());
782            return InvalidTimeValueSnafu {
783                position: self.position,
784                string: lossy_str,
785            }
786            .fail();
787        }
788        let vec: std::result::Result<_, _> = buf
789            .split(|b| *b == b'\\')
790            .map(|part| {
791                parse_time_partial(part)
792                    .map(|t| t.0)
793                    .context(DeserializeValueSnafu {
794                        position: self.position,
795                    })
796            })
797            .collect();
798        self.position += len as u64;
799        Ok(PrimitiveValue::Time(vec?))
800    }
801
802    fn read_value_od(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
803        let len = self.require_known_length(header)?;
804        // sequence of 64-bit floats
805        let n = len >> 3;
806        let vec = read_numeric_chunked!(self, n, decode_fd_into, 0f64);
807        self.position += len as u64;
808        Ok(PrimitiveValue::F64(vec))
809    }
810
811    fn read_value_ul(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
812        let len = self.require_known_length(header)?;
813        // sequence of 32-bit unsigned integers
814
815        let n = len >> 2;
816        let vec = read_numeric_chunked!(self, n, decode_ul_into, 0u32);
817        self.position += len as u64;
818        Ok(PrimitiveValue::U32(vec))
819    }
820
821    fn read_u32(&mut self, n: usize, vec: &mut Vec<u32>) -> Result<()> {
822        // `n` is derived from an untrusted, file-controlled length field - read (and allocate)
823        // in bounded chunks rather than resizing to the full `n` upfront, so a corrupt/malicious
824        // file that lies about a huge length can only ever force a bounded allocation attempt
825        // per chunk before decode_ul_into's own read fails on the actually-truncated stream. See
826        // `StatefulDecoder::read_into_buffer` for the byte-oriented equivalent of this reasoning.
827        const CHUNK: usize = 65536; // 256KiB per chunk
828        let mut remaining = n;
829        while remaining > 0 {
830            let batch = remaining.min(CHUNK);
831            let base = vec.len();
832            vec.resize(base + batch, 0);
833
834            self.basic
835                .decode_ul_into(&mut self.from, &mut vec[base..])
836                .context(ReadValueDataSnafu {
837                    position: self.position,
838                })?;
839            self.position += batch as u64 * 4;
840            remaining -= batch;
841        }
842        Ok(())
843    }
844
845    fn read_value_us(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
846        let len = self.require_known_length(header)?;
847        // sequence of 16-bit unsigned integers
848
849        let n = len >> 1;
850        let vec = read_numeric_chunked!(self, n, decode_us_into, 0u16);
851
852        self.position += len as u64;
853
854        if header.tag == Tag(0x0028, 0x0103) {
855            //Pixel Representation is not 0, so 2s complement (signed)
856            self.signed_pixeldata = vec.first().map(|rep| *rep != 0);
857        }
858
859        Ok(PrimitiveValue::U16(vec))
860    }
861
862    fn read_value_uv(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
863        let len = self.require_known_length(header)?;
864        // sequence of 64-bit unsigned integers
865
866        let n = len >> 3;
867        let vec = read_numeric_chunked!(self, n, decode_uv_into, 0u64);
868        self.position += len as u64;
869        Ok(PrimitiveValue::U64(vec))
870    }
871
872    fn read_value_sl(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
873        let len = self.require_known_length(header)?;
874        // sequence of 32-bit signed integers
875
876        let n = len >> 2;
877        let vec = read_numeric_chunked!(self, n, decode_sl_into, 0i32);
878        self.position += len as u64;
879        Ok(PrimitiveValue::I32(vec))
880    }
881
882    fn read_value_sv(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
883        let len = self.require_known_length(header)?;
884        // sequence of 64-bit signed integers
885
886        let n = len >> 3;
887        let vec = read_numeric_chunked!(self, n, decode_sv_into, 0i64);
888        self.position += len as u64;
889        Ok(PrimitiveValue::I64(vec))
890    }
891}
892
893impl<S, D, BD> StatefulDecoder<D, S, BD>
894where
895    D: DecodeFrom<S>,
896    BD: BasicDecode,
897    S: Read,
898{
899    fn set_character_set(&mut self, charset: SpecificCharacterSet) -> Result<()> {
900        self.text = charset;
901        Ok(())
902    }
903
904    /// Read a sequence of Code String values. Similar to `read_value_strs`, but also
905    /// triggers a character set change when it finds the _SpecificCharacterSet_
906    /// attribute.
907    fn read_value_cs(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
908        let out = self.read_value_strs(header)?;
909
910        let parts = match &out {
911            PrimitiveValue::Strs(parts) => parts,
912            _ => unreachable!(),
913        };
914
915        // if it's a Specific Character Set, update the decoder immediately.
916        if header.tag == Tag(0x0008, 0x0005) {
917            // Edge case handling strategies for
918            // unsupported specific character sets should probably be considered
919            // in the future. See #40 for discussion.
920            // All the values count: `\ISO 2022 IR 87` (an empty value 1) is ISO 2022 code
921            // extension with JIS X 0208, not the default repertoire (pohcee/dcmnorm#24).
922            match SpecificCharacterSet::from_codes(parts) {
923                Some(charset) => self.set_character_set(charset)?,
924                None => {
925                    tracing::warn!("Unsupported character set `{}`, ignoring", parts.join("\\"))
926                }
927            }
928        }
929
930        Ok(out)
931    }
932}
933
934impl<D> StatefulDecode for &'_ mut D
935where
936    D: StatefulDecode,
937{
938    type Reader = D::Reader;
939
940    fn decode_header(&mut self) -> Result<DataElementHeader> {
941        (**self).decode_header()
942    }
943
944    fn decode_item_header(&mut self) -> Result<SequenceItemHeader> {
945        (**self).decode_item_header()
946    }
947
948    fn read_value(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
949        (**self).read_value(header)
950    }
951
952    fn read_value_preserved(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
953        (**self).read_value_preserved(header)
954    }
955
956    fn read_value_bytes(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
957        (**self).read_value_bytes(header)
958    }
959
960    fn read_to_vec(&mut self, length: u32, vec: &mut Vec<u8>) -> Result<()> {
961        (**self).read_to_vec(length, vec)
962    }
963
964    fn read_u32_to_vec(&mut self, length: u32, vec: &mut Vec<u32>) -> Result<()> {
965        (**self).read_u32_to_vec(length, vec)
966    }
967
968    fn read_to<W>(&mut self, length: u32, out: W) -> Result<()>
969    where
970        Self: Sized,
971        W: std::io::Write,
972    {
973        (**self).read_to(length, out)
974    }
975
976    fn skip_bytes(&mut self, length: u32) -> Result<()> {
977        (**self).skip_bytes(length)
978    }
979
980    fn position(&self) -> u64 {
981        (**self).position()
982    }
983
984    fn enter_implicit_vr(&mut self) {
985        (**self).enter_implicit_vr()
986    }
987
988    fn leave_implicit_vr(&mut self) {
989        (**self).leave_implicit_vr()
990    }
991
992    fn seek(&mut self, position: u64) -> Result<()>
993    where
994        Self::Reader: Seek,
995    {
996        (**self).seek(position)
997    }
998
999    fn skip_bytes_seek(&mut self, length: u64) -> Result<()>
1000    where
1001        Self::Reader: Seek,
1002    {
1003        (**self).skip_bytes_seek(length)
1004    }
1005}
1006
1007impl<D, S, BD> StatefulDecode for StatefulDecoder<D, S, BD>
1008where
1009    D: DecodeFrom<S>,
1010    BD: BasicDecode,
1011    S: Read,
1012{
1013    type Reader = S;
1014
1015    fn decode_header(&mut self) -> Result<DataElementHeader> {
1016        let decoded = if self.implicit_vr_depth > 0 {
1017            DecodeFrom::<S>::decode_header(&self.implicit_vr, &mut self.from)
1018        } else {
1019            self.decoder.decode_header(&mut self.from)
1020        };
1021        let mut header = decoded
1022            .context(DecodeElementHeaderSnafu {
1023                position: self.position,
1024            })
1025            .map(|(header, bytes_read)| {
1026                self.position += bytes_read as u64;
1027                header
1028            })?;
1029
1030        //If we are decoding the PixelPadding element, make sure the VR is the same as the pixel
1031        //representation (US by default, SS for signed data).
1032        let explicit_vr = self.implicit_vr_depth == 0 && self.decoder.is_explicit_vr();
1033        if let Some(vr) = self.determine_vr_based_on_pixel_representation(header.tag, explicit_vr) {
1034            header.vr = vr;
1035        }
1036
1037        Ok(header)
1038    }
1039
1040    fn decode_item_header(&mut self) -> Result<SequenceItemHeader> {
1041        self.decoder
1042            .decode_item_header(&mut self.from)
1043            .context(DecodeItemHeaderSnafu {
1044                position: self.position,
1045            })
1046            .map(|header| {
1047                self.position += 8;
1048                header
1049            })
1050    }
1051
1052    fn read_value(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
1053        if header.length() == Length(0) {
1054            return Ok(PrimitiveValue::Empty);
1055        }
1056
1057        match header.vr() {
1058            VR::SQ => {
1059                // sequence objects should not head over here, they are
1060                // handled at a higher level
1061                NonPrimitiveTypeSnafu {
1062                    position: self.position,
1063                }
1064                .fail()
1065            }
1066            VR::AT => self.read_value_tag(header),
1067            VR::AE | VR::AS | VR::PN | VR::SH | VR::LO | VR::UC | VR::UI => {
1068                self.read_value_strs(header)
1069            }
1070            VR::CS => self.read_value_cs(header),
1071            VR::UT | VR::ST | VR::UR | VR::LT => self.read_value_str(header),
1072            VR::UN | VR::OB => self.read_value_ob(header),
1073            VR::US | VR::OW => self.read_value_us(header),
1074            VR::SS => self.read_value_ss(header),
1075            VR::DA => self.read_value_da(header),
1076            VR::DT => self.read_value_dt(header),
1077            VR::TM => self.read_value_tm(header),
1078            VR::DS => self.read_value_ds(header),
1079            VR::FD | VR::OD => self.read_value_od(header),
1080            VR::FL | VR::OF => self.read_value_fl(header),
1081            VR::IS => self.read_value_is(header),
1082            VR::SL => self.read_value_sl(header),
1083            VR::SV => self.read_value_sv(header),
1084            VR::OL | VR::UL => self.read_value_ul(header),
1085            VR::OV | VR::UV => self.read_value_uv(header),
1086        }
1087    }
1088
1089    fn read_value_preserved(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
1090        if header.length() == Length(0) {
1091            return Ok(PrimitiveValue::Empty);
1092        }
1093
1094        match header.vr() {
1095            VR::SQ => {
1096                // sequence objects... should not work
1097                NonPrimitiveTypeSnafu {
1098                    position: self.position,
1099                }
1100                .fail()
1101            }
1102            VR::AT => self.read_value_tag(header),
1103            VR::AE
1104            | VR::AS
1105            | VR::PN
1106            | VR::SH
1107            | VR::LO
1108            | VR::UC
1109            | VR::UI
1110            | VR::IS
1111            | VR::DS
1112            | VR::DA
1113            | VR::TM
1114            | VR::DT => self.read_value_strs(header),
1115            VR::CS => self.read_value_cs(header),
1116            VR::UT | VR::ST | VR::UR | VR::LT => self.read_value_str(header),
1117            VR::UN | VR::OB => self.read_value_ob(header),
1118            VR::US | VR::OW => self.read_value_us(header),
1119            VR::SS => self.read_value_ss(header),
1120            VR::FD | VR::OD => self.read_value_od(header),
1121            VR::FL | VR::OF => self.read_value_fl(header),
1122            VR::SL => self.read_value_sl(header),
1123            VR::OL | VR::UL => self.read_value_ul(header),
1124            VR::SV => self.read_value_sv(header),
1125            VR::OV | VR::UV => self.read_value_uv(header),
1126        }
1127    }
1128
1129    fn read_value_bytes(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
1130        if header.length() == Length(0) {
1131            return Ok(PrimitiveValue::Empty);
1132        }
1133
1134        match header.vr() {
1135            VR::SQ => {
1136                // sequence objects... should not work
1137                NonPrimitiveTypeSnafu {
1138                    position: self.position,
1139                }
1140                .fail()
1141            }
1142            _ => self.read_value_ob(header),
1143        }
1144    }
1145
1146    fn position(&self) -> u64 {
1147        self.position
1148    }
1149
1150    fn enter_implicit_vr(&mut self) {
1151        self.implicit_vr_depth += 1;
1152    }
1153
1154    fn leave_implicit_vr(&mut self) {
1155        self.implicit_vr_depth = self.implicit_vr_depth.saturating_sub(1);
1156    }
1157
1158    fn read_to_vec(&mut self, length: u32, vec: &mut Vec<u8>) -> Result<()> {
1159        self.read_to(length, vec)
1160    }
1161
1162    fn read_u32_to_vec(&mut self, length: u32, vec: &mut Vec<u32>) -> Result<()> {
1163        self.read_u32((length >> 2) as usize, vec)
1164    }
1165
1166    fn read_to<W>(&mut self, length: u32, mut out: W) -> Result<()>
1167    where
1168        Self: Sized,
1169        W: std::io::Write,
1170    {
1171        let length = u64::from(length);
1172        std::io::copy(&mut self.from.by_ref().take(length), &mut out).context(
1173            ReadValueDataSnafu {
1174                position: self.position,
1175            },
1176        )?;
1177        self.position += length;
1178        Ok(())
1179    }
1180
1181    fn skip_bytes(&mut self, length: u32) -> Result<()> {
1182        std::io::copy(
1183            &mut self.from.by_ref().take(u64::from(length)),
1184            &mut std::io::sink(),
1185        )
1186        .context(ReadValueDataSnafu {
1187            position: self.position,
1188        })?;
1189
1190        self.position += u64::from(length);
1191        Ok(())
1192    }
1193
1194    fn seek(&mut self, position: u64) -> Result<()>
1195    where
1196        Self::Reader: Seek,
1197    {
1198        self.from
1199            .seek(SeekFrom::Start(position))
1200            .context(SeekReaderSnafu {
1201                position: self.position,
1202                new_position: position,
1203            })
1204            .map(|_| ())
1205    }
1206
1207    fn skip_bytes_seek(&mut self, length: u64) -> Result<()>
1208    where
1209        Self::Reader: Seek,
1210    {
1211        let offset = <i64 as std::convert::TryFrom<u64>>::try_from(length)
1212            .map_err(|_| std::io::Error::from(std::io::ErrorKind::InvalidInput));
1213        offset
1214            .and_then(|offset| self.from.seek(SeekFrom::Current(offset)))
1215            .context(SeekReaderSnafu {
1216                position: self.position,
1217                new_position: self.position + length,
1218            })?;
1219        self.position += length;
1220        Ok(())
1221    }
1222}
1223
1224impl<D, S, BD> StatefulDecoder<D, S, BD>
1225where
1226    D: DecodeFrom<S>,
1227    BD: BasicDecode,
1228    S: Read,
1229{
1230    /// The pixel representation affects the VR for several elements.
1231    /// Returns `Some(VR::SS)` if the vr needs to be modified to SS. Returns `None`
1232    /// if this element is not affected _or_ if we have Unsigned Pixel Representation.
1233    ///
1234    /// LUT Descriptors are the exception when their VR is written in the data (explicit VR): the
1235    /// signedness of their first value follows the range of the LUT's input, which for a VOI LUT
1236    /// is the output of the Modality transform (PS3.3 C.11.2.1.1), not the stored Pixel
1237    /// Representation - signed pixels with a Rescale Intercept of 32768 feed a VOI LUT unsigned
1238    /// input. A written `US` there is correct and is kept (pohcee/dcmnorm#27).
1239    fn determine_vr_based_on_pixel_representation(
1240        &self,
1241        tag: Tag,
1242        explicit_vr: bool,
1243    ) -> Option<VR> {
1244        use dcmnorm_core::dictionary::DataDictionary;
1245
1246        if explicit_vr && is_lut_descriptor(tag) {
1247            return None;
1248        }
1249        if self.signed_pixeldata == Some(true)
1250            && StandardDataDictionary.by_tag(tag).map(|e| e.vr) == Some(VirtualVr::Xs)
1251        {
1252            Some(VR::SS)
1253        } else {
1254            None
1255        }
1256    }
1257}
1258
1259/// The LUT Descriptor attributes (`US or SS` first value): LUT Descriptor (0028,3002) of the
1260/// Modality and VOI LUT sequences and the (Large / Segmented) Palette Color LUT Descriptors.
1261fn is_lut_descriptor(tag: Tag) -> bool {
1262    tag.group() == 0x0028 && matches!(tag.element(), 0x3002 | 0x1101..=0x1104 | 0x1111..=0x1113)
1263}
1264
1265/// Remove trailing spaces and null characters.
1266fn trim_trail_empty_bytes(mut x: &[u8]) -> &[u8] {
1267    while x.last() == Some(&b' ') || x.last() == Some(&b'\0') {
1268        x = &x[..x.len() - 1];
1269    }
1270    x
1271}
1272
1273#[cfg(test)]
1274mod tests {
1275    use super::{StatefulDecode, StatefulDecoder};
1276    use dcmnorm_core::header::{DataElementHeader, HasLength, Header, Length, SequenceItemHeader};
1277    use dcmnorm_core::{Tag, VR};
1278    use dcmnorm_encoding::decode::basic::LittleEndianBasicDecoder;
1279    use dcmnorm_encoding::decode::{
1280        explicit_le::ExplicitVRLittleEndianDecoder, implicit_le::ImplicitVRLittleEndianDecoder,
1281    };
1282    use dcmnorm_encoding::text::{SpecificCharacterSet, TextCodec};
1283    use std::io::{Cursor, Seek, SeekFrom};
1284
1285    // manually crafting some DICOM data elements
1286    //  Tag: (0002,0002) Media Storage SOP Class UID
1287    //  VR: UI
1288    //  Length: 26
1289    //  Value: "1.2.840.10008.5.1.4.1.1.1\0"
1290    // --
1291    //  Tag: (0002,0010) Transfer Syntax UID
1292    //  VR: UI
1293    //  Length: 20
1294    //  Value: "1.2.840.10008.1.2.1\0" == ExplicitVRLittleEndian
1295    // --
1296    const RAW: &[u8; 62] = &[
1297        0x02, 0x00, 0x02, 0x00, 0x55, 0x49, 0x1a, 0x00, 0x31, 0x2e, 0x32, 0x2e, 0x38, 0x34, 0x30,
1298        0x2e, 0x31, 0x30, 0x30, 0x30, 0x38, 0x2e, 0x35, 0x2e, 0x31, 0x2e, 0x34, 0x2e, 0x31, 0x2e,
1299        0x31, 0x2e, 0x31, 0x00, 0x02, 0x00, 0x10, 0x00, 0x55, 0x49, 0x14, 0x00, 0x31, 0x2e, 0x32,
1300        0x2e, 0x38, 0x34, 0x30, 0x2e, 0x31, 0x30, 0x30, 0x30, 0x38, 0x2e, 0x31, 0x2e, 0x32, 0x2e,
1301        0x31, 0x00,
1302    ];
1303
1304    fn is_stateful_decoder<T>(_: &T)
1305    where
1306        T: StatefulDecode,
1307    {
1308    }
1309
1310    #[test]
1311    fn decode_data_elements() {
1312        let mut cursor = Cursor::new(&RAW[..]);
1313        let mut decoder = StatefulDecoder::new(
1314            &mut cursor,
1315            ExplicitVRLittleEndianDecoder::default(),
1316            LittleEndianBasicDecoder,
1317            SpecificCharacterSet::default(),
1318        );
1319
1320        is_stateful_decoder(&decoder);
1321
1322        {
1323            // read first element
1324            let elem = decoder.decode_header().expect("should find an element");
1325            assert_eq!(elem.tag(), Tag(2, 2));
1326            assert_eq!(elem.vr(), VR::UI);
1327            assert_eq!(elem.length(), Length(26));
1328
1329            assert_eq!(decoder.position(), 8);
1330
1331            // read value
1332            let value = decoder
1333                .read_value(&elem)
1334                .expect("value after element header");
1335            assert_eq!(value.multiplicity(), 1);
1336            assert_eq!(value.string(), Ok("1.2.840.10008.5.1.4.1.1.1\0"));
1337
1338            assert_eq!(decoder.position(), 8 + 26);
1339        }
1340        {
1341            // read second element
1342            let elem = decoder.decode_header().expect("should find an element");
1343            assert_eq!(elem.tag(), Tag(2, 16));
1344            assert_eq!(elem.vr(), VR::UI);
1345            assert_eq!(elem.length(), Length(20));
1346
1347            assert_eq!(decoder.position(), 8 + 26 + 8);
1348
1349            // read value
1350            let value = decoder
1351                .read_value(&elem)
1352                .expect("value after element header");
1353            assert_eq!(value.multiplicity(), 1);
1354            assert_eq!(value.string(), Ok("1.2.840.10008.1.2.1\0"));
1355
1356            assert_eq!(decoder.position(), 8 + 26 + 8 + 20);
1357
1358            // rolling back to read the last value again
1359            decoder.seek(8 + 26 + 8).unwrap();
1360
1361            // read value
1362            let value = decoder
1363                .read_value(&elem)
1364                .expect("value after element header");
1365            assert_eq!(value.multiplicity(), 1);
1366            assert_eq!(value.string(), Ok("1.2.840.10008.1.2.1\0"));
1367
1368            assert_eq!(decoder.position(), 8 + 26 + 8 + 20 + 20);
1369        }
1370    }
1371
1372    /// Test that the stateful decoder updates
1373    /// the active character set after reaching a Specific Character Set element
1374    /// with a supported text encoding.
1375    #[test]
1376    fn update_character_set() {
1377        const RAW: &[u8; 18] = &[
1378            // Tag: (0008,0005) Specific Character Set
1379            0x08, 0x00, 0x05, 0x00, // VR: CS
1380            b'C', b'S', // Length: 10
1381            0x0a, 0x00, // Value: "ISO_IR 192"
1382            b'I', b'S', b'O', b'_', b'I', b'R', b' ', b'1', b'9', b'2',
1383        ];
1384
1385        let mut cursor = &RAW[..];
1386        let mut decoder = StatefulDecoder::new(
1387            &mut cursor,
1388            ExplicitVRLittleEndianDecoder::default(),
1389            LittleEndianBasicDecoder,
1390            SpecificCharacterSet::default(),
1391        );
1392
1393        is_stateful_decoder(&decoder);
1394
1395        let header = decoder
1396            .decode_header()
1397            .expect("should find an element header");
1398        assert_eq!(
1399            header,
1400            DataElementHeader {
1401                tag: Tag(0x0008, 0x0005),
1402                vr: VR::CS,
1403                len: Length(10),
1404            }
1405        );
1406
1407        let value = decoder
1408            .read_value_preserved(&header)
1409            .expect("should read a value");
1410
1411        assert_eq!(value.string(), Ok("ISO_IR 192"));
1412        assert_eq!(decoder.text.name(), "ISO_IR 192",);
1413    }
1414
1415    #[test]
1416    fn decode_data_elements_with_position() {
1417        let data = {
1418            let mut x = vec![0; 128];
1419            x.extend(RAW);
1420            x
1421        };
1422
1423        // have cursor start 128 bytes ahead
1424        let mut cursor = Cursor::new(&data[..]);
1425        cursor.seek(SeekFrom::Start(128)).unwrap();
1426
1427        let mut decoder = StatefulDecoder::new_with_position(
1428            &mut cursor,
1429            ExplicitVRLittleEndianDecoder::default(),
1430            LittleEndianBasicDecoder,
1431            SpecificCharacterSet::default(),
1432            128,
1433        );
1434
1435        is_stateful_decoder(&decoder);
1436
1437        {
1438            // read first element
1439            let elem = decoder.decode_header().expect("should find an element");
1440            assert_eq!(elem.tag(), Tag(2, 2));
1441            assert_eq!(elem.vr(), VR::UI);
1442            assert_eq!(elem.length(), Length(26));
1443
1444            assert_eq!(decoder.position(), 128 + 8);
1445
1446            // read value
1447            let value = decoder
1448                .read_value(&elem)
1449                .expect("value after element header");
1450            assert_eq!(value.multiplicity(), 1);
1451            assert_eq!(value.string(), Ok("1.2.840.10008.5.1.4.1.1.1\0"));
1452
1453            assert_eq!(decoder.position(), 128 + 8 + 26);
1454        }
1455        {
1456            // read second element
1457            let elem = decoder.decode_header().expect("should find an element");
1458            assert_eq!(elem.tag(), Tag(2, 16));
1459            assert_eq!(elem.vr(), VR::UI);
1460            assert_eq!(elem.length(), Length(20));
1461
1462            assert_eq!(decoder.position(), 128 + 8 + 26 + 8);
1463
1464            // read value
1465            let value = decoder
1466                .read_value(&elem)
1467                .expect("value after element header");
1468            assert_eq!(value.multiplicity(), 1);
1469            assert_eq!(value.string(), Ok("1.2.840.10008.1.2.1\0"));
1470
1471            assert_eq!(decoder.position(), 128 + 8 + 26 + 8 + 20);
1472
1473            // rolling back to read the last value again
1474            decoder.seek(128 + 8 + 26 + 8).unwrap();
1475
1476            // read value
1477            let value = decoder
1478                .read_value(&elem)
1479                .expect("value after element header");
1480            assert_eq!(value.multiplicity(), 1);
1481            assert_eq!(value.string(), Ok("1.2.840.10008.1.2.1\0"));
1482
1483            assert_eq!(decoder.position(), 128 + 8 + 26 + 8 + 20 + 20);
1484        }
1485    }
1486
1487    #[test]
1488    fn decode_nested_datasets() {
1489        const RAW: &[u8; 138] = &[
1490            // 0: (2001, 9000) private sequence
1491            0x01, 0x20, 0x00, 0x90, //
1492            // length: undefined
1493            0xFF, 0xFF, 0xFF, 0xFF, //
1494            // 8: Item start
1495            0xFE, 0xFF, 0x00, 0xE0, //
1496            // Item length explicit (114)
1497            0x72, 0x00, 0x00, 0x00, //
1498            // 16: (0008,1115) ReferencedSeriesSequence
1499            0x08, 0x00, 0x15, 0x11, //
1500            // length: undefined
1501            0xFF, 0xFF, 0xFF, 0xFF, //
1502            // 24: Item start
1503            0xFE, 0xFF, 0x00, 0xE0, //
1504            // Item length undefined
1505            0xFF, 0xFF, 0xFF, 0xFF, //
1506            // 32: (0008,1140) ReferencedImageSequence
1507            0x08, 0x00, 0x40, 0x11, //
1508            // length: undefined
1509            0xFF, 0xFF, 0xFF, 0xFF, //
1510            // 40: Item start
1511            0xFE, 0xFF, 0x00, 0xE0, //
1512            // Item length undefined
1513            0xFF, 0xFF, 0xFF, 0xFF, //
1514            // 48: (0008,1150) ReferencedSOPClassUID
1515            0x08, 0x00, 0x50, 0x11, //
1516            // length: 26
1517            0x1a, 0x00, 0x00, 0x00, //
1518            // Value: "1.2.840.10008.5.1.4.1.1.7\0" (SecondaryCaptureImageStorage)
1519            b'1', b'.', b'2', b'.', b'8', b'4', b'0', b'.', b'1', b'0', b'0', b'0', b'8', b'.',
1520            b'5', b'.', b'1', b'.', b'4', b'.', b'1', b'.', b'1', b'.', b'7', b'\0',
1521            // 82: Item End (ReferencedImageSequence)
1522            0xFE, 0xFF, 0x0D, 0xE0, //
1523            0x00, 0x00, 0x00, 0x00, //
1524            // 90: Sequence End (ReferencedImageSequence)
1525            0xFE, 0xFF, 0xDD, 0xE0, //
1526            0x00, 0x00, 0x00, 0x00, //
1527            // 98: Item End (ReferencedSeriesSequence)
1528            0xFE, 0xFF, 0x0D, 0xE0, //
1529            0x00, 0x00, 0x00, 0x00, //
1530            // 106: Sequence End (ReferencedSeriesSequence)
1531            0xFE, 0xFF, 0xDD, 0xE0, //
1532            0x00, 0x00, 0x00, 0x00, //
1533            // 114: (2050,0020) PresentationLUTShape (CS)
1534            0x50, 0x20, 0x20, 0x00, //
1535            // length: 8
1536            0x08, 0x00, 0x00, 0x00, //
1537            b'I', b'D', b'E', b'N', b'T', b'I', b'T', b'Y', // 130: Sequence end
1538            0xFE, 0xFF, 0xDD, 0xE0, //
1539            0x00, 0x00, 0x00, 0x00, //
1540        ];
1541
1542        let mut cursor = &RAW[..];
1543        let mut decoder = StatefulDecoder::new(
1544            &mut cursor,
1545            ImplicitVRLittleEndianDecoder::default(),
1546            LittleEndianBasicDecoder,
1547            SpecificCharacterSet::default(),
1548        );
1549
1550        is_stateful_decoder(&decoder);
1551
1552        let header = decoder
1553            .decode_header()
1554            .expect("should find an element header");
1555        assert_eq!(header.tag(), Tag(0x2001, 0x9000));
1556        assert_eq!(header.vr(), VR::UN);
1557        assert!(header.length().is_undefined());
1558
1559        assert_eq!(decoder.position(), 8);
1560
1561        let item_header = decoder
1562            .decode_item_header()
1563            .expect("should find an item header");
1564        assert_eq!(item_header, SequenceItemHeader::Item { len: Length(114) });
1565
1566        assert_eq!(decoder.position(), 16);
1567
1568        // enter ReferencedSeriesSequence
1569        let header = decoder
1570            .decode_header()
1571            .expect("should find an element header");
1572        assert_eq!(header.tag(), Tag(0x0008, 0x1115));
1573        assert_eq!(header.vr(), VR::SQ);
1574        assert!(header.length().is_undefined());
1575
1576        assert_eq!(decoder.position(), 24);
1577
1578        let item_header = decoder
1579            .decode_item_header()
1580            .expect("should find an item header (ReferencedSeriesSequence)");
1581        assert!(matches!(
1582            item_header,
1583            SequenceItemHeader::Item {
1584                len,
1585            } if len.is_undefined()
1586        ));
1587
1588        assert_eq!(decoder.position(), 32);
1589
1590        // enter ReferencedImageSequence
1591        let header = decoder
1592            .decode_header()
1593            .expect("should find an element header");
1594        assert_eq!(header.tag(), Tag(0x0008, 0x1140));
1595        assert_eq!(header.vr(), VR::SQ);
1596        assert!(header.length().is_undefined());
1597
1598        assert_eq!(decoder.position(), 40);
1599
1600        let item_header = decoder
1601            .decode_item_header()
1602            .expect("should find an item header (ReferencedImageSequence)");
1603        assert!(matches!(
1604            item_header,
1605            SequenceItemHeader::Item {
1606                len,
1607            } if len.is_undefined()
1608        ));
1609
1610        assert_eq!(decoder.position(), 48);
1611
1612        // read ReferencedSOPClassUID
1613
1614        let header = decoder
1615            .decode_header()
1616            .expect("should find an element header");
1617        assert_eq!(header.tag(), Tag(0x0008, 0x1150));
1618        assert_eq!(header.vr(), VR::UI);
1619        assert_eq!(header.length(), Length(26));
1620
1621        assert_eq!(decoder.position(), 56);
1622
1623        let value = decoder
1624            .read_value(&header)
1625            .expect("should find a value after element header");
1626        assert_eq!(value.to_str(), "1.2.840.10008.5.1.4.1.1.7");
1627
1628        assert_eq!(decoder.position(), 82);
1629
1630        // exit ReferencedImageSequence
1631
1632        let item_header = decoder
1633            .decode_item_header()
1634            .expect("should find item delimiter");
1635        assert_eq!(item_header, SequenceItemHeader::ItemDelimiter);
1636
1637        assert_eq!(decoder.position(), 90);
1638
1639        let item_header = decoder
1640            .decode_item_header()
1641            .expect("should find sequence delimiter");
1642        assert_eq!(item_header, SequenceItemHeader::SequenceDelimiter);
1643
1644        assert_eq!(decoder.position(), 98);
1645
1646        // exit ReferencedSeriesSequence
1647
1648        let item_header = decoder
1649            .decode_item_header()
1650            .expect("should find item delimiter");
1651        assert_eq!(item_header, SequenceItemHeader::ItemDelimiter);
1652
1653        assert_eq!(decoder.position(), 106);
1654
1655        let item_header = decoder
1656            .decode_item_header()
1657            .expect("should find sequence delimiter");
1658        assert_eq!(item_header, SequenceItemHeader::SequenceDelimiter);
1659
1660        assert_eq!(decoder.position(), 114);
1661
1662        // read PresentationLUTShape
1663
1664        let header = decoder
1665            .decode_header()
1666            .expect("should find an element header");
1667        assert_eq!(header.tag(), Tag(0x2050, 0x0020));
1668        assert_eq!(header.vr(), VR::CS);
1669        assert_eq!(header.length(), Length(8));
1670
1671        assert_eq!(decoder.position(), 122);
1672
1673        let value = decoder
1674            .read_value(&header)
1675            .expect("value after element header");
1676        assert_eq!(value.multiplicity(), 1);
1677        assert_eq!(value.to_str(), "IDENTITY");
1678
1679        assert_eq!(decoder.position(), 130);
1680
1681        // exit private sequence
1682        // (no item delimiter because length is explicit)
1683
1684        let item_header = decoder
1685            .decode_item_header()
1686            .expect("should find an item header");
1687        assert_eq!(item_header, SequenceItemHeader::SequenceDelimiter);
1688
1689        assert_eq!(decoder.position(), 138);
1690    }
1691
1692    #[test]
1693    fn decode_and_use_pixel_representation() {
1694        const RAW: &[u8; 20] = &[
1695            0x28, 0x00, 0x03, 0x01, // Tag: (0023,0103) PixelRepresentation
1696            0x02, 0x00, 0x00, 0x00, // Length: 2
1697            0x01, 0x00, // Value: "1",
1698            0x28, 0x00, 0x20, 0x01, // Tag: (0023,0120) PixelPadding
1699            0x02, 0x00, 0x00, 0x00, // Length: 2
1700            0x01, 0x00, // Value: "1"
1701        ];
1702
1703        let mut cursor = &RAW[..];
1704        let mut decoder = StatefulDecoder::new(
1705            &mut cursor,
1706            ImplicitVRLittleEndianDecoder::default(),
1707            LittleEndianBasicDecoder,
1708            SpecificCharacterSet::default(),
1709        );
1710
1711        is_stateful_decoder(&decoder);
1712
1713        let header_1 = decoder
1714            .decode_header()
1715            .expect("should find an element header");
1716        assert_eq!(
1717            header_1,
1718            DataElementHeader {
1719                tag: Tag(0x0028, 0x0103),
1720                vr: VR::US,
1721                len: Length(2),
1722            }
1723        );
1724
1725        decoder
1726            .read_value(&header_1)
1727            .expect("Can read Pixel Representation");
1728
1729        let header_2 = decoder
1730            .decode_header()
1731            .expect("should find an element header");
1732        assert_eq!(
1733            header_2,
1734            DataElementHeader {
1735                tag: Tag(0x0028, 0x0120),
1736                vr: VR::SS,
1737                len: Length(2),
1738            }
1739        );
1740    }
1741
1742    /// pohcee/dcmnorm#27: with signed pixels, an explicitly written `US` LUT Descriptor is kept
1743    /// (a VOI LUT after a Rescale Intercept of 32768 has unsigned input), while an implicit VR one
1744    /// still follows Pixel Representation, and other `US or SS` attributes keep the rule.
1745    #[test]
1746    fn explicit_us_lut_descriptor_is_kept_with_signed_pixel_representation() {
1747        #[rustfmt::skip]
1748        const EXPLICIT: &[u8] = &[
1749            0x28, 0x00, 0x03, 0x01, b'U', b'S', 0x02, 0x00, 0x01, 0x00, // PixelRepresentation 1
1750            0x28, 0x00, 0x02, 0x30, b'U', b'S', 0x06, 0x00, // LUTDescriptor US, 6 bytes
1751            0x04, 0x00, 0x40, 0x9c, 0x10, 0x00, // [4, 40000, 16]
1752            0x28, 0x00, 0x20, 0x01, b'U', b'S', 0x02, 0x00, 0x01, 0x00, // PixelPaddingValue
1753        ];
1754        let mut cursor = EXPLICIT;
1755        let mut decoder = StatefulDecoder::new(
1756            &mut cursor,
1757            ExplicitVRLittleEndianDecoder::default(),
1758            LittleEndianBasicDecoder,
1759            SpecificCharacterSet::default(),
1760        );
1761        let header = decoder.decode_header().unwrap();
1762        decoder.read_value(&header).unwrap();
1763        let header = decoder.decode_header().unwrap();
1764        assert_eq!(header.vr, VR::US, "explicit US LUT Descriptor must be kept");
1765        assert_eq!(
1766            decoder.read_value(&header).unwrap(),
1767            dcmnorm_core::PrimitiveValue::U16([4, 40000, 16].as_ref().into())
1768        );
1769        let header = decoder.decode_header().unwrap();
1770        assert_eq!(header.tag, Tag(0x0028, 0x0120));
1771        assert_eq!(
1772            header.vr,
1773            VR::SS,
1774            "Pixel Padding Value still follows Pixel Representation"
1775        );
1776
1777        #[rustfmt::skip]
1778        const IMPLICIT: &[u8] = &[
1779            0x28, 0x00, 0x03, 0x01, 0x02, 0x00, 0x00, 0x00, 0x01, 0x00,
1780            0x28, 0x00, 0x02, 0x30, 0x06, 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x10, 0x00,
1781        ];
1782        let mut cursor = IMPLICIT;
1783        let mut decoder = StatefulDecoder::new(
1784            &mut cursor,
1785            ImplicitVRLittleEndianDecoder::default(),
1786            LittleEndianBasicDecoder,
1787            SpecificCharacterSet::default(),
1788        );
1789        let header = decoder.decode_header().unwrap();
1790        decoder.read_value(&header).unwrap();
1791        assert_eq!(decoder.decode_header().unwrap().vr, VR::SS);
1792    }
1793
1794    #[test]
1795    fn decode_text_with_charset_override() {
1796        #[rustfmt::skip]
1797        const RAW: &[u8; 28] = &[
1798            // Tag: (0018,0015) Body Part Examined
1799            0x18, 0x00, 0x15, 0x00,
1800            // VR: CS
1801            b'C', b'S',
1802            // Length: 20
1803            0x14, 0x00, // Value: "脊柱侧弯-视图" (scoliosis-view)
1804            232, 132, 138, 230, 159, 177, 228, 190,
1805            167, 229, 188, 175, 45, 232, 167, 134,
1806            229, 155, 190, b' '
1807        ];
1808
1809        let mut cursor = &RAW[..];
1810
1811        let mut decoder = StatefulDecoder::new_with_all_options(
1812            &mut cursor,
1813            ExplicitVRLittleEndianDecoder::default(),
1814            LittleEndianBasicDecoder,
1815            SpecificCharacterSet::ISO_IR_192,
1816            // use AnyVr so that Body Part Examined
1817            super::CharacterSetOverride::AnyVr,
1818            0,
1819        );
1820
1821        is_stateful_decoder(&decoder);
1822
1823        let header_1 = decoder
1824            .decode_header()
1825            .expect("should find an element header");
1826        assert_eq!(
1827            header_1,
1828            DataElementHeader {
1829                tag: Tag(0x0018, 0x0015),
1830                vr: VR::CS,
1831                len: Length(20),
1832            }
1833        );
1834
1835        let val = decoder
1836            .read_value(&header_1)
1837            .expect("Can read Body Part Examined");
1838
1839        assert_eq!(val.to_str(), "脊柱侧弯-视图",);
1840    }
1841
1842    /// A corrupt/malicious file can declare a huge (up to ~4GiB) value length on an element
1843    /// while the file itself is tiny. Before `read_into_buffer`/`read_numeric_chunked!` existed,
1844    /// every VR's value-reading path pre-allocated the full declared length upfront - a failing
1845    /// allocation of that shape aborts the process rather than returning a catchable error. This
1846    /// proves the fix across the three distinct code shapes it touched: a byte buffer (OB), a
1847    /// text buffer (UI), and a typed numeric array (UL) all reject an oversized declared length
1848    /// against a short stream with a clean `Err`, not a hang or an allocation attempt anywhere
1849    /// near the declared size.
1850    #[test]
1851    fn oversized_declared_length_on_short_stream_errors_cleanly_for_every_value_shape() {
1852        let short_data: &[u8] = b"only a few bytes, nowhere near 4GiB";
1853        let huge_len = Length(0xFFFF_FFF0); // ~4GiB, but not the reserved 0xFFFFFFFF sentinel
1854
1855        for vr in [VR::OB, VR::UI, VR::UL] {
1856            let mut cursor = Cursor::new(short_data);
1857            let mut decoder = StatefulDecoder::new(
1858                &mut cursor,
1859                ExplicitVRLittleEndianDecoder::default(),
1860                LittleEndianBasicDecoder,
1861                SpecificCharacterSet::default(),
1862            );
1863            let header = DataElementHeader {
1864                tag: Tag(0x0008, 0x0000),
1865                vr,
1866                len: huge_len,
1867            };
1868
1869            let result = decoder.read_value(&header);
1870            assert!(
1871                result.is_err(),
1872                "expected a clean error for VR {vr:?} with a declared length ({huge_len:?}) far \
1873                 exceeding the {}-byte stream, got {result:?}",
1874                short_data.len()
1875            );
1876        }
1877    }
1878}