- as default, ambiguous DT range uses local clock time-zone

- doc changes

core/src/value/partial.rs

@@ -75,11 +75,13 @@ pub enum DateComponent {
     Millisecond,
     // microsecond (full second fraction)
     Fraction,
+    // West UTC time-zone offset
     UtcWest,
+    // East UTC time-zone offset
     UtcEast,
 }
 
-/// Represents a Dicom Date value with a partial precision,
+/// Represents a Dicom date (DA) value with a partial precision,
 /// where some date components may be missing.
 ///
 /// Unlike [chrono::NaiveDate], it does not allow for negative years.
@@ -113,7 +115,7 @@ pub enum DateComponent {
 #[derive(Clone, Copy, PartialEq)]
 pub struct DicomDate(DicomDateImpl);
 
-/// Represents a Dicom Time value with a partial precision,
+/// Represents a Dicom time (TM) value with a partial precision,
 /// where some time components may be missing.
 ///
 /// Unlike [chrono::NaiveTime], this implemenation has only 6 digit precision
@@ -181,14 +183,14 @@ enum DicomTimeImpl {
     Fraction(u8, u8, u8, u32, u8),
 }
 
-/// Represents a Dicom DateTime value with a partial precision,
+/// Represents a Dicom date-time (DT) value with a partial precision,
 /// where some date or time components may be missing.
 ///
 /// `DicomDateTime` is always internally represented by a [DicomDate].
 /// The [DicomTime] and a timezone [FixedOffset] values are optional.
 ///
-/// It implements [AsRange] trait, which serves to access usable precise values from `DicomDateTime` values
-/// with missing components in the form of [PreciseDateTimeResult].
+/// It implements [AsRange] trait, which serves to retrieve a [PreciseDateTimeResult] from values
+/// with missing components.
 /// # Example
 /// ```
 /// # use std::error::Error;

core/src/value/primitive.rs

@@ -2978,7 +2978,7 @@ impl PrimitiveValue {
     ///
     /// ```
     /// # use dicom_core::value::{C, PrimitiveValue};
-    /// use chrono::{DateTime, NaiveDate, NaiveTime, NaiveDateTime, FixedOffset, TimeZone};
+    /// use chrono::{DateTime, NaiveDate, NaiveTime, NaiveDateTime, FixedOffset, TimeZone, Local};
     /// # use std::error::Error;
     /// use dicom_core::value::{DateTimeRange, PreciseDateTimeResult};
     ///
@@ -3011,22 +3011,23 @@ impl PrimitiveValue {
     ///
     /// let lower = PrimitiveValue::from("2012-").to_datetime_range()?;
     ///
+    /// // range has no upper bound
     /// assert!(lower.end().is_none());
     ///
     /// // The DICOM protocol allows for parsing text representations of date-time ranges,
     /// // where one bound has a time-zone but the other has not.
     /// let dt_range = PrimitiveValue::from("1992+0500-1993").to_datetime_range()?;
     ///
-    /// // the default behavior in this case is to use the known time-zone to construct
-    /// // two time-zone aware DT bounds.
+    /// // the default behavior in this case is to use the local clock time-zone offset
+    /// // in place of the missing time-zone. This can be customized with [to_datetime_range_custom()]
     /// assert_eq!(
     ///   dt_range,
     ///   DateTimeRange::TimeZone{
     ///         start: Some(FixedOffset::east_opt(5*3600).unwrap()
     ///             .ymd_opt(1992, 1, 1).unwrap()
     ///             .and_hms_micro_opt(0, 0, 0, 0).unwrap()
     ///         ),
-    ///         end: Some(FixedOffset::east_opt(5*3600).unwrap()
+    ///         end: Some(Local::now().offset()
     ///             .ymd_opt(1993, 12, 31).unwrap()
     ///             .and_hms_micro_opt(23, 59, 59, 999_999).unwrap()
     ///         )
@@ -3128,7 +3129,7 @@ impl PrimitiveValue {
     ///     ).unwrap()
     /// );
     ///
-    /// // fail upon parsing a ambiguous DT range
+    /// // always fail upon parsing an ambiguous DT range
     /// assert!(
     /// PrimitiveValue::from("1992+0599-1993")
     ///     .to_datetime_range_custom::<FailOnAmbiguousRange>().is_err()
@@ -4311,7 +4312,7 @@ mod tests {
     use crate::value::partial::{DicomDate, DicomDateTime, DicomTime};
     use crate::value::range::{DateRange, DateTimeRange, TimeRange};
     use crate::value::{PrimitiveValue, ValueType};
-    use chrono::{FixedOffset, NaiveDate, NaiveDateTime, NaiveTime, TimeZone};
+    use chrono::{FixedOffset, Local, NaiveDate, NaiveDateTime, NaiveTime, TimeZone};
     use smallvec::smallvec;
 
     #[test]
@@ -4926,15 +4927,15 @@ mod tests {
             .unwrap()
         );
         // East UTC offset gets parsed and the missing lower bound time-zone
-        // will be the same as the parsed offset value
+        // will be the local clock time-zone offset
         assert_eq!(
             PrimitiveValue::from(&b"2020-2030+0800"[..])
                 .to_datetime_range()
                 .unwrap(),
             DateTimeRange::TimeZone {
                 start: Some(
-                    FixedOffset::east_opt(8 * 3600)
-                        .unwrap()
+                    Local::now()
+                        .offset()
                         .from_local_datetime(&NaiveDateTime::new(
                             NaiveDate::from_ymd_opt(2020, 1, 1).unwrap(),
                             NaiveTime::from_hms_opt(0, 0, 0).unwrap()