From 8aee739706222e67803b784257b7878a68ce84ac Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 20 Dec 2019 11:14:29 +0100 Subject: Add crate top-level documentation Signed-off-by: Matthias Beyer --- src/lib.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 71579d8..d0fc056 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,11 @@ +//! libical high level interface +//! +//! This library offers a high-level interface for the widely used libical. It relies upon the +//! libical-sys crate, which is a thin rust layer over the libical C API. +//! It provides a safe interface to libical that is rather lower-level, as well as convenience +//! functionality build on this low-level interface for easy handling of icalendar data. +//! + #![warn(unused_extern_crates)] #![allow(clippy::redundant_closure)] // disable "redundant closure" lint @@ -48,3 +56,4 @@ pub use crate::timezone::IcalTimeZone; pub use crate::vcalendar::IcalEventIter; pub use crate::vcalendar::IcalVCalendar; pub use crate::vevent::IcalVEvent; + -- cgit v1.2.3 From 0505704787744e6e425d553ae00d0a2a8cc6277b Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 20 Dec 2019 11:20:09 +0100 Subject: Add documentation for IcalDuration Signed-off-by: Matthias Beyer --- src/duration.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/duration.rs b/src/duration.rs index d080584..6de4c49 100644 --- a/src/duration.rs +++ b/src/duration.rs @@ -5,17 +5,23 @@ use std::fmt::{Display, Error, Formatter}; use std::ops::{Add, Deref}; use std::str::FromStr; +/// Duration type +/// +/// A type that represents a duration of time #[derive(Clone, Debug)] pub struct IcalDuration { duration: ical::icaldurationtype, } impl IcalDuration { + + /// Convert a number of seconds to an IcalDuration pub fn from_seconds(seconds: i32) -> IcalDuration { let duration = unsafe { ical::icaldurationtype_from_int(seconds) }; IcalDuration { duration } } + /// Get the number of seconds the IcalDuration represents pub fn to_seconds(&self) -> i32 { unsafe { ical::icaldurationtype_as_int(self.duration) } } -- cgit v1.2.3 From 908033c6260dc9d9518e2641aca4f5ead49f6d61 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 20 Dec 2019 11:22:47 +0100 Subject: Add description of IcalProperty type Signed-off-by: Matthias Beyer --- src/property.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/property.rs b/src/property.rs index 55b5914..63e7540 100644 --- a/src/property.rs +++ b/src/property.rs @@ -5,6 +5,9 @@ use std::fmt; use super::component::IcalComponent; use crate::ical; +/// A property in the ical data +/// +/// This type represents a single property (name + value). pub struct IcalProperty<'a> { pub ptr: *mut ical::icalproperty, _parent: &'a dyn IcalComponent, -- cgit v1.2.3 From 785a796702ce28381cd067e9f284bc89f679b346 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 20 Dec 2019 11:39:05 +0100 Subject: Add documentation for IcalTime type Signed-off-by: Matthias Beyer --- src/time.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/time.rs b/src/time.rs index 2fe4a33..49b7f4a 100644 --- a/src/time.rs +++ b/src/time.rs @@ -9,20 +9,27 @@ use std::fmt::{Display, Error, Formatter}; use std::ops::{Add, Deref}; use std::str::FromStr; +/// Time type +/// +/// A type representing "time" #[derive(Clone, Debug)] pub struct IcalTime { time: ical::icaltimetype, } impl IcalTime { + + /// Get an IcalTime object that represents UTC now pub fn utc() -> Self { dateutil::now().into() } + /// Get an IcalTime object that represents the current time in the local timezone. pub fn local() -> Self { dateutil::now().with_timezone(&Local).into() } + /// Get an IcalTime object that represents a specific day. pub fn floating_ymd(year: i32, month: i32, day: i32) -> Self { let time = ical::icaltimetype { year, @@ -38,6 +45,8 @@ impl IcalTime { IcalTime { time } } + /// Get an IcalTime object that is the same as the object this function is called on, but with + /// hour, minute and second set pub fn and_hms(&self, hour: i32, minute: i32, second: i32) -> Self { let mut time = self.time; time.hour = hour; @@ -48,6 +57,7 @@ impl IcalTime { IcalTime { time } } + /// Get an IcalTime object based on a timestamp pub fn from_timestamp(timestamp: i64) -> Self { let _lock = TZ_MUTEX.lock(); let utc = IcalTimeZone::utc(); @@ -56,21 +66,25 @@ impl IcalTime { IcalTime { time } } + /// Get the timestamp representation of the IcalTime object pub fn timestamp(&self) -> i64 { let _lock = TZ_MUTEX.lock(); unsafe { ical::icaltime_as_timet_with_zone(self.time, self.time.zone) } } + /// Get whether the IcalTime object is a date object pub fn is_date(&self) -> bool { self.time.is_date != 0 } + /// Get the IcalTime object as a date object pub fn as_date(&self) -> IcalTime { let mut time = self.time; time.is_date = 1; IcalTime { time } } + /// Get the timezone for the IcalTime object pub fn get_timezone(&self) -> Option { if self.time.zone.is_null() { return None; @@ -79,6 +93,7 @@ impl IcalTime { Some(IcalTimeZone::from_ptr_copy(tz_ptr)) } + /// Get a new IcalTime object with a different timezone pub fn with_timezone(&self, timezone: &IcalTimeZone) -> IcalTime { let _lock = TZ_MUTEX.lock(); let mut time = unsafe { ical::icaltime_convert_to_zone(self.time, **timezone) }; @@ -87,6 +102,7 @@ impl IcalTime { IcalTime { time } } + /// Get a new IcalTime object with the day before the day of the current object pub fn pred(&self) -> IcalTime { let mut time = self.time; time.day -= 1; @@ -94,6 +110,7 @@ impl IcalTime { IcalTime { time } } + /// Get a new IcalTime object with the day after the day of the current object pub fn succ(&self) -> IcalTime { let mut time = self.time; time.day += 1; -- cgit v1.2.3 From f8e22561f0bf9164d2094d45360f898fe525b693 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 20 Dec 2019 11:47:23 +0100 Subject: Add description for IcalTimeZone type Signed-off-by: Matthias Beyer --- src/timezone.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/timezone.rs b/src/timezone.rs index 843a1ed..855b9da 100644 --- a/src/timezone.rs +++ b/src/timezone.rs @@ -5,6 +5,7 @@ use std::ops::Deref; use super::IcalTime; use crate::utils::dateutil; +/// A type representing a timezone. pub struct IcalTimeZone { timezone: *mut ical::icaltimezone, } -- cgit v1.2.3