From 22a3c21c4e4977f2ce98f18b2bdc93d2e6c1a0df Mon Sep 17 00:00:00 2001 From: Tpt Date: Sat, 14 Jan 2023 22:20:23 +0100 Subject: [PATCH] Improves oxsdatatypes documentation --- lib/oxsdatatypes/README.md | 13 +++++++++++++ lib/oxsdatatypes/src/date_time.rs | 26 +++++++++++++++++++++++++- lib/oxsdatatypes/src/decimal.rs | 2 ++ lib/oxsdatatypes/src/double.rs | 2 ++ lib/oxsdatatypes/src/duration.rs | 6 +++--- lib/oxsdatatypes/src/float.rs | 2 ++ lib/oxsdatatypes/src/parser.rs | 1 + 7 files changed, 48 insertions(+), 4 deletions(-) diff --git a/lib/oxsdatatypes/README.md b/lib/oxsdatatypes/README.md index c5f35fff..b89bc272 100644 --- a/lib/oxsdatatypes/README.md +++ b/lib/oxsdatatypes/README.md @@ -19,6 +19,19 @@ use oxsdatatypes::Decimal; assert!(Decimal::from_str("22.2").unwrap() > Decimal::from_str("21").unwrap()); ``` +Each datatype is represented by a Rust struct. + +Each datatype provides: +* `FromStr` implementation to parse a datatype string serialization following its [lexical mapping](https://www.w3.org/TR/xmlschema11-2/#dt-lexical-mapping). +* `Display` implementation to serialize a datatype following its [canonical mapping](https://www.w3.org/TR/xmlschema11-2/#dt-canonical-mapping). +* `is_identical_with` method following its [identity relation](https://www.w3.org/TR/xmlschema11-2/#identity). +* `PartialEq`, and `Eq` if possible, implementations following its [equality relation](https://www.w3.org/TR/xmlschema11-2/#equality). +* `PartialOrd`, and `Ord` if possible, implementations following its [order relation](https://www.w3.org/TR/xmlschema11-2/#order). +* `From` and `TryFrom` implementations to implement [XPath casting](https://www.w3.org/TR/xpath-functions-31/#casting). +* Various methods implementing [XPath functions](https://www.w3.org/TR/xpath-functions/). +* `from_be_bytes` and `to_be_bytes` methods for serialization. + + ## License This project is licensed under either of diff --git a/lib/oxsdatatypes/src/date_time.rs b/lib/oxsdatatypes/src/date_time.rs index 5c59652f..66829adb 100644 --- a/lib/oxsdatatypes/src/date_time.rs +++ b/lib/oxsdatatypes/src/date_time.rs @@ -12,6 +12,9 @@ use std::str::FromStr; use std::time::SystemTimeError; /// [XML Schema `dateTime` datatype](https://www.w3.org/TR/xmlschema11-2/#dateTime) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`] +/// and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct DateTime { timestamp: Timestamp, @@ -190,7 +193,7 @@ impl DateTime { } } - // [fn:adjust-dateTime-to-timezone](https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone) + /// [fn:adjust-dateTime-to-timezone](https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone) #[inline] pub fn adjust(&self, timezone_offset: Option) -> Option { Some(Self { @@ -256,6 +259,9 @@ impl fmt::Display for DateTime { } /// [XML Schema `time` datatype](https://www.w3.org/TR/xmlschema11-2/#time) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the date 1972-12-31, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct Time { timestamp: Timestamp, @@ -446,6 +452,9 @@ impl fmt::Display for Time { } /// [XML Schema `date` datatype](https://www.w3.org/TR/xmlschema11-2/#date) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the time 00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct Date { timestamp: Timestamp, @@ -633,6 +642,9 @@ impl fmt::Display for Date { } /// [XML Schema `gYearMonth` datatype](https://www.w3.org/TR/xmlschema11-2/#gYearMonth) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the day-time 31T00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct GYearMonth { timestamp: Timestamp, @@ -752,6 +764,9 @@ impl fmt::Display for GYearMonth { } /// [XML Schema `gYear` datatype](https://www.w3.org/TR/xmlschema11-2/#gYear) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the month-day-time 12-31T00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct GYear { timestamp: Timestamp, @@ -870,6 +885,9 @@ impl fmt::Display for GYear { } /// [XML Schema `gMonthDay` datatype](https://www.w3.org/TR/xmlschema11-2/#gMonthDay) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the year 1972 and the time 31T00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct GMonthDay { timestamp: Timestamp, @@ -985,6 +1003,9 @@ impl fmt::Display for GMonthDay { } /// [XML Schema `gMonth` datatype](https://www.w3.org/TR/xmlschema11-2/#gMonth) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the year 1972 and the day-time 31T00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct GMonth { timestamp: Timestamp, @@ -1108,6 +1129,9 @@ impl fmt::Display for GMonth { } /// [XML Schema `date` datatype](https://www.w3.org/TR/xmlschema11-2/#date) +/// +/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`], +/// when combined with the year-month 1972-12 and the 00:00:00, and an optional timezone offset in minutes. #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)] pub struct GDay { timestamp: Timestamp, diff --git a/lib/oxsdatatypes/src/decimal.rs b/lib/oxsdatatypes/src/decimal.rs index e710707b..3b6ea6af 100644 --- a/lib/oxsdatatypes/src/decimal.rs +++ b/lib/oxsdatatypes/src/decimal.rs @@ -13,6 +13,8 @@ const DECIMAL_PART_HALF_POW: i128 = 1_000_000_000; /// [XML Schema `decimal` datatype](https://www.w3.org/TR/xmlschema11-2/#decimal) /// /// It stores the decimal in a fix point encoding allowing nearly 18 digits before and 18 digits after ".". +/// +/// It stores the value in a [`i128`] integer after multiplying it by 10¹⁸. #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)] pub struct Decimal { value: i128, // value * 10^18 diff --git a/lib/oxsdatatypes/src/double.rs b/lib/oxsdatatypes/src/double.rs index b49410a4..6b5f10b9 100644 --- a/lib/oxsdatatypes/src/double.rs +++ b/lib/oxsdatatypes/src/double.rs @@ -8,6 +8,8 @@ use std::str::FromStr; /// [XML Schema `double` datatype](https://www.w3.org/TR/xmlschema11-2/#double) /// /// Uses internally a [`f64`]. +/// +/// Beware: serialization is currently buggy and do not follow the canonical mapping yet. #[derive(Debug, Clone, Copy, Default, PartialEq)] #[repr(transparent)] pub struct Double { diff --git a/lib/oxsdatatypes/src/duration.rs b/lib/oxsdatatypes/src/duration.rs index 386fd599..6998164e 100644 --- a/lib/oxsdatatypes/src/duration.rs +++ b/lib/oxsdatatypes/src/duration.rs @@ -9,7 +9,7 @@ use std::time::Duration as StdDuration; /// [XML Schema `duration` datatype](https://www.w3.org/TR/xmlschema11-2/#duration) /// -/// It stores the duration using a pair of a `YearMonthDuration` and a `DayTimeDuration`. +/// It stores the duration using a pair of a [`YearMonthDuration`] and a [`DayTimeDuration`]. #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Default)] pub struct Duration { year_month: YearMonthDuration, @@ -238,7 +238,7 @@ impl Neg for Duration { /// [XML Schema `yearMonthDuration` datatype](https://www.w3.org/TR/xmlschema11-2/#yearMonthDuration) /// -/// It stores the duration as a number of months encoded using a `i64` +/// It stores the duration as a number of months encoded using a [`i64`]. #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)] pub struct YearMonthDuration { months: i64, @@ -389,7 +389,7 @@ impl Neg for YearMonthDuration { /// [XML Schema `dayTimeDuration` datatype](https://www.w3.org/TR/xmlschema11-2/#dayTimeDuration) /// -/// It stores the duration as a number of seconds encoded using a `Decimal` +/// It stores the duration as a number of seconds encoded using a [`Decimal`]. #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)] pub struct DayTimeDuration { seconds: Decimal, diff --git a/lib/oxsdatatypes/src/float.rs b/lib/oxsdatatypes/src/float.rs index e94ff0aa..dde70893 100644 --- a/lib/oxsdatatypes/src/float.rs +++ b/lib/oxsdatatypes/src/float.rs @@ -8,6 +8,8 @@ use std::str::FromStr; /// [XML Schema `float` datatype](https://www.w3.org/TR/xmlschema11-2/#float) /// /// Uses internally a [`f32`]. +/// +/// Beware: serialization is currently buggy and do not follow the canonical mapping yet. #[derive(Debug, Clone, Copy, Default, PartialEq)] #[repr(transparent)] pub struct Float { diff --git a/lib/oxsdatatypes/src/parser.rs b/lib/oxsdatatypes/src/parser.rs index 1b056c07..22d652ea 100644 --- a/lib/oxsdatatypes/src/parser.rs +++ b/lib/oxsdatatypes/src/parser.rs @@ -16,6 +16,7 @@ use std::fmt; use std::num::ParseIntError; use std::str::FromStr; +/// A parsing error #[derive(Debug, Clone)] pub struct XsdParseError { kind: XsdParseErrorKind,