Time zone handling: accept only DateTime<Utc> and NaiveDateTime

This is a breaking API change.

- [Todo::due] and [Todo::completed] now take their date-time argument by value rather than by
  reference
- [Todo::completed] now requires its [chrono::DateTime] argument to have exactly [chrono::Utc]
  specified as its time zone as mandated by the RFC.
- [Component::starts], [Component::ends] and [Todo::due] now take newly introduced
  [CalendarDateTime] (through `Into<CalendarDateTime>` indirection). This allows callers to
  define time zone handling. Conversions from [chrono::NaiveDateTime] and
  [`chrono::DateTime<Utc>`] are provided for ergonomics, the latter also restoring API
  compatibility in case of UTC date-times.

Note that we now implement 2 of the 3 DATE-TIME variants defined by the RFC.
The third variant can be implemented in the future.

Fixes #2.

1 files changed, 13 insertions, 1 deletions

diff --git a/src/lib.rs b/src/lib.rs
index fe9ee3b..31916b1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -47,6 +47,18 @@
 //! calendar.add(bday);
 //! # }
 //! ```
+//!
+//! ## Breaking API Changes in version 0.7.0
+//!
+//! - [Todo::due] and [Todo::completed] now take their date-time argument by value rather than by
+//!   reference
+//! - [Todo::completed] now requires its [chrono::DateTime] argument to have exactly [chrono::Utc]
+//!   specified as its time zone as mandated by the RFC.
+//! - [Component::starts], [Component::ends] and [Todo::due] now take newly introduced
+//!   [CalendarDateTime] (through `Into<CalendarDateTime>` indirection). This allows callers to
+//!   define time zone handling. Conversions from [`chrono::NaiveDateTime`] and
+//!   [`chrono::DateTime<Utc>`](chrono::DateTime) are provided for ergonomics, the latter also restoring API
+//!   compatibility in case of UTC date-times.
 
 #![warn(missing_docs,
         missing_copy_implementations,
@@ -83,7 +95,7 @@ mod calendar;
 //pub mod repeats;
 pub use crate::properties::{Property, Parameter, Class, ValueType};
 pub use crate::properties::{TodoStatus, EventStatus};
-pub use crate::components::{Event, Todo, Component};
+pub use crate::components::{CalendarDateTime, Event, Todo, Component};
 pub use crate::calendar::Calendar;
 
 // TODO Calendar TimeZone VTIMEZONE STANDARD DAYLIGHT (see thunderbird exports)