docs

3 files changed, 72 insertions, 16 deletions

diff --git a/src/lib.rs b/src/lib.rs
index c78b18d..6fe3223 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -12,13 +12,68 @@
 //! can also be built by composing mutliple `RRule`s for its rrule and exrule properties and DateTime<Tz> for its
 //! exdate and rdate properties. See the examples below.
 //!
-//! # Interface
-//! `RRule` and `RRuleSet` have the same interface for generating recurrences. The four methods for "querying" for recurrences are:
+//! # Generating occurences
+//! `RRule` and `RRuleSet` have four quick start methods for "querying" for recurrences:
 //! - `all`: Generate all recurrences that matches the rules
 //! - `between`: Generate all recurrences that matches the rules and are between two given dates
 //! - `before`: Generate the last recurrence that matches the rules and is before a given date
 //! - `after`: Generate the first recurrence that matches the rules and is after a given date
 //!
+//! If you have some additional filters or want to work with inifite recurrence rules
+//! both `RRule` and `RRuleSet` implements the `Iterator` traits which makes them very flexible.
+//! All the methods above uses the iterator trait in its implementation as shown below.
+//! ````
+//! extern crate rrule;
+//! extern crate chrono;
+//! extern crate chrono_tz;
+//!
+//! use chrono::prelude::*;
+//! use chrono_tz::UTC;
+//! use rrule::RRule;
+//!
+//! let mut rrule: RRule = "DTSTART:20120201T093000Z\nRRULE:FREQ=DAILY;COUNT=3".parse().unwrap();
+//!
+//!
+//! // All dates
+//! let all_occurences: Vec<_> = rrule.clone().into_iter().collect();
+//! assert_eq!(all_occurences, rrule.all());
+//!
+//! // Between two dates
+//! let after = UTC.ymd(2012, 2, 1).and_hms(10, 0, 0);
+//! let before = UTC.ymd(2012, 4, 1).and_hms(9, 0, 0);
+//! let inc = true; // Wheter dates equal to after or before should be added;
+//!
+//! let occurences_between_dates: Vec<_> = rrule.clone()
+//!     .into_iter()
+//!     .skip_while(|d| if inc { *d <= after } else { *d < after })
+//!     .take_while(|d| if inc { *d <= before } else { *d < before })
+//!     .collect();
+//! assert_eq!(occurences_between_dates, rrule.between(after, before, inc));
+//!
+//!
+//! // After a date
+//! let after = UTC.ymd(2012, 2, 1).and_hms(10, 0, 0);
+//! let inc = true; // Wheter dates equals to after should be added;
+//!
+//! let occurences_after_date = rrule.clone()
+//!     .into_iter()
+//!     .skip_while(|d| if inc { *d <= after } else { *d < after })
+//!     .next();
+//! assert_eq!(occurences_after_date, rrule.after(after, inc));
+//!
+//!
+//! // Before a date
+//! let before = UTC.ymd(2012, 4, 1).and_hms(10, 0, 0);
+//! let inc = true; // Wheter dates equals to before should be added;
+//!
+//! let occurences_before_date = rrule.clone()
+//!     .into_iter()
+//!     .take_while(|d| if inc { *d <= before } else { *d < before })
+//!     .last();
+//! assert_eq!(occurences_before_date, rrule.before(before, inc));
+//!
+//! ````
+//!
 //! Note: All the generated recurrence will be in the same time zone as the dtstart property.
 //!
 //! # Examples
@@ -208,7 +263,7 @@ mod rruleset_iter;
 mod rrulestr;
 mod utils;
 
-pub use crate::options::{Frequenzy, Options, ParsedOptions, NWeekday};
+pub use crate::options::{Frequenzy, NWeekday, Options, ParsedOptions};
 pub use crate::rrule::RRule;
 pub use crate::rruleset::RRuleSet;
 pub use chrono::Weekday;
diff --git a/src/parse_options.rs b/src/parse_options.rs
index 7953887..f6af1d9 100644
--- a/src/parse_options.rs
+++ b/src/parse_options.rs
@@ -1,4 +1,6 @@
-use crate::options::{Frequenzy, NWeekday, NWeekdayIdentifier, Options, ParsedOptions, RRuleParseError};
+use crate::options::{
+    Frequenzy, NWeekday, NWeekdayIdentifier, Options, ParsedOptions, RRuleParseError,
+};
 use crate::utils::is_some_and_not_empty;
 use chrono::prelude::*;
 use chrono_tz::{Tz, UTC};
@@ -69,8 +71,10 @@ pub fn parse_options(options: &Options) -> Result<ParsedOptions, RRuleParseError
                 partial_options.bymonthday = Some(vec![dtstart.day() as isize]);
             }
             Frequenzy::Weekly => {
-                partial_options.byweekday =
-                    Some(vec![NWeekday::new(dtstart.weekday() as usize, NWeekdayIdentifier::Every)]);
+                partial_options.byweekday = Some(vec![NWeekday::new(
+                    dtstart.weekday() as usize,
+                    NWeekdayIdentifier::Every,
+                )]);
             }
             _ => (),
         };
@@ -100,9 +104,7 @@ pub fn parse_options(options: &Options) -> Result<ParsedOptions, RRuleParseError
     if let Some(opts_byweekday) = partial_options.byweekday {
         for wday in opts_byweekday {
             match wday.n {
-                NWeekdayIdentifier::Every => {
-                byweekday.push(wday.weekday)
-                }
+                NWeekdayIdentifier::Every => byweekday.push(wday.weekday),
                 NWeekdayIdentifier::Identifier(n) => {
                     bynweekday.push(vec![wday.weekday as isize, n]);
                 }
diff --git a/src/rrulestr.rs b/src/rrulestr.rs
index d700401..232f5a4 100644
--- a/src/rrulestr.rs
+++ b/src/rrulestr.rs
@@ -63,7 +63,7 @@ fn datestring_to_date(dt: &str, tz: &Tz) -> Result<DTime, RRuleParseError> {
 
 fn parse_dtstart(s: &str) -> Result<Options, RRuleParseError> {
     let caps = DTSTART_RE.captures(s);
-    
+
     match caps {
         Some(caps) => {
             let tzid: Tz = if let Some(tzid) = caps.get(1) {
@@ -89,7 +89,7 @@ fn parse_dtstart(s: &str) -> Result<Options, RRuleParseError> {
             options.dtstart = Some(UTC.timestamp(Utc::now().timestamp(), 0));
             options.tzid = Some(UTC);
             Ok(options)
-        },
+        }
     }
 }
 
@@ -573,8 +573,8 @@ pub fn build_rrule(s: &str) -> Result<RRule, RRuleParseError> {
 
 #[cfg(test)]
 mod test {
-    use super::*;
     use super::NWeekdayIdentifier;
+    use super::*;
     use chrono_tz::{Tz, UTC};
 
     #[test]
@@ -683,7 +683,7 @@ mod test {
     #[test]
     fn parses_byday_as_nweekday_when_n_is_first() {
         let res = build_rrule("DTSTART;VALUE=DATE:20200701\nRRULE:FREQ=MONTHLY;UNTIL=20210303T090000Z;INTERVAL=1;BYDAY=1WE").unwrap();
-        assert_eq!(res.options.bynweekday, vec![vec![2,1]]);
+        assert_eq!(res.options.bynweekday, vec![vec![2, 1]]);
     }
 
     #[test]
@@ -708,9 +708,9 @@ mod test {
         let opts = vec![
             vec![NWeekday::new(1, NWeekdayIdentifier::Identifier(1))],
             vec![NWeekday::new(2, NWeekdayIdentifier::Identifier(1))],
-            vec![NWeekday::new(2,NWeekdayIdentifier::Identifier(-1))],
+            vec![NWeekday::new(2, NWeekdayIdentifier::Identifier(-1))],
             vec![NWeekday::new(6, NWeekdayIdentifier::Identifier(12))],
-            vec![NWeekday::new(0,NWeekdayIdentifier::Identifier(4))]
+            vec![NWeekday::new(0, NWeekdayIdentifier::Identifier(4))],
         ];
         for i in 0..cases.len() {
             let opts_or_err = parse_string(cases[i]);
@@ -744,7 +744,6 @@ mod test {
         assert_eq!(res.options.freq, Frequenzy::Daily);
         assert!(Utc::now().timestamp() - res.options.dtstart.timestamp() < 2);
 
-
         let res = build_rruleset("FREQ=DAILY;COUNT=7");
         assert!(res.is_ok());
         let occurences = res.unwrap().all();