[california/wip/calendar-spans: 12/13] DiscreteUnit -> Unit

[Jim Nelson <jnelson src gnome org>]

commit e53653b55a92fc08a7f398bfcfea54931bfba6a4
Author: Jim Nelson <jim yorba org>
Date:   Fri May 9 14:30:33 2014 -0700

    DiscreteUnit -> Unit

 src/Makefile.am                          |    1 -
 src/calendar/calendar-date.vala          |    2 +-
 src/calendar/calendar-discrete-unit.vala |  112 -----------------------------
 src/calendar/calendar-month-of-year.vala |    2 +-
 src/calendar/calendar-unit-span.vala     |   18 +++---
 src/calendar/calendar-unit.vala          |  114 +++++++++++++++++++++++++-----
 src/calendar/calendar-week.vala          |    2 +-
 src/calendar/calendar-year.vala          |    2 +-
 src/calendar/calendar.vala               |   25 +++++++
 9 files changed, 134 insertions(+), 144 deletions(-)
---
diff --git a/src/Makefile.am b/src/Makefile.am
index 91b35d3..69be554 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -52,7 +52,6 @@ california_VALASOURCES = \
        calendar/calendar-day-of-week.vala \
        calendar/calendar-date.vala \
        calendar/calendar-dbus.vala \
-       calendar/calendar-discrete-unit.vala \
        calendar/calendar-duration.vala \
        calendar/calendar-error.vala \
        calendar/calendar-exact-time.vala \
diff --git a/src/calendar/calendar-date.vala b/src/calendar/calendar-date.vala
index 4291b99..0644d02 100644
--- a/src/calendar/calendar-date.vala
+++ b/src/calendar/calendar-date.vala
@@ -20,7 +20,7 @@ namespace California.Calendar {
  * issues.
  */
 
-public class Date : DiscreteUnit<Date>, Gee.Comparable<Date>, Gee.Hashable<Date> {
+public class Date : Unit<Date>, Gee.Comparable<Date>, Gee.Hashable<Date> {
     public const string PROP_DAY_OF_WEEK = "day-of-week";
     public const string PROP_DAY_OF_MONTH = "day-of-month";
     public const string PROP_MONTH = "month";
diff --git a/src/calendar/calendar-month-of-year.vala b/src/calendar/calendar-month-of-year.vala
index 5110928..da16504 100644
--- a/src/calendar/calendar-month-of-year.vala
+++ b/src/calendar/calendar-month-of-year.vala
@@ -10,7 +10,7 @@ namespace California.Calendar {
  * An immutable representation of a { link Month} of a { link Year}.
  */
 
-public class MonthOfYear : DiscreteUnit<MonthOfYear>, Gee.Comparable<MonthOfYear>, Gee.Hashable<MonthOfYear> 
{
+public class MonthOfYear : Unit<MonthOfYear>, Gee.Comparable<MonthOfYear>, Gee.Hashable<MonthOfYear> {
     /**
      * The { link Month} of the associated { link Year}.
      */
diff --git a/src/calendar/calendar-unit-span.vala b/src/calendar/calendar-unit-span.vala
index 6843cba..201db9c 100644
--- a/src/calendar/calendar-unit-span.vala
+++ b/src/calendar/calendar-unit-span.vala
@@ -7,7 +7,7 @@
 namespace California.Calendar {
 
 /**
- * An arbitrary, immutable span of { link DiscreteUnit}s.
+ * An arbitrary, immutable span of { link Unit}s.
  *
  * @see DateSpan
  * @see MonthSpan
@@ -21,17 +21,17 @@ public abstract class UnitSpan<G> : Span, Collection.SimpleIterable<G>, Gee.Comp
     public const string PROP_LAST = "last";
     
     /**
-     * This relies on the fact that DiscreteUnit<G> is, in fact, G, i.e. Week is a
-     * DiscreteUnit<Week>.  This will blow-up if that's every not true.
+     * This relies on the fact that Unit<G> is, in fact, G, i.e. Week is a
+     * Unit<Week>.  This will blow-up if that's every not true.
      */
     private class UnitSpanIterator<G> : BaseObject, Collection.SimpleIterator<G> {
-        public DiscreteUnit<G> first;
-        public DiscreteUnit<G> last;
-        public DiscreteUnit<G>? current = null;
+        public Unit<G> first;
+        public Unit<G> last;
+        public Unit<G>? current = null;
         
         public UnitSpanIterator(G first, G last) {
-            this.first = (DiscreteUnit<G>) first;
-            this.last = (DiscreteUnit<G>) last;
+            this.first = (Unit<G>) first;
+            this.last = (Unit<G>) last;
         }
         
         public new G get() {
@@ -42,7 +42,7 @@ public abstract class UnitSpan<G> : Span, Collection.SimpleIterable<G>, Gee.Comp
             if (current == null)
                 current = first;
             else if (current.start_date.compare_to(last.start_date) < 0)
-                current = (DiscreteUnit<G>) current.adjust(1);
+                current = (Unit<G>) current.adjust(1);
             else
                 return false;
             
diff --git a/src/calendar/calendar-unit.vala b/src/calendar/calendar-unit.vala
index dd145fe..4717e48 100644
--- a/src/calendar/calendar-unit.vala
+++ b/src/calendar/calendar-unit.vala
@@ -7,28 +7,106 @@
 namespace California.Calendar {
 
 /**
- * An enumeration of various calendar units.
+ * An immutable, discrete, well-recognized unit of calendar dates.
  *
- * @see DiscreteUnit
- */
-
-public enum DateUnit {
-    DAY,
-    WEEK,
-    MONTH,
-    YEAR
-}
-
-/**
- * An enumeration of various time units.
+ * This interface indicates the { link Calendar.Span} represents a discrete unit of time (each of
+ * which may not contain the same number of days, such as { link Year}s, while some might, such as
+ * { link Week}s), in contrast to a { link DateSpan}, which represents an ''arbitrary''
+ * span of dates that may or may not correspond to a well-recognized unit of dates.
  *
- * @see WallTime
+ * Note that this different than a { link UnitSpan} such as { link MonthSpan} which is designed to
+ * hold an arbitrary consecutive number of their date units (i.e. a span of months).  Unit
+ * represents a single unit of time (a week or a month).
+ *
+ * If Vala supported constrained generics, a UnitSpan would be defined as requiring a generic type
+ * of Unit.
+ *
+ * Unit is not designed to work with discrete { link ExactTime} or { link WallTime} units.
+ *
+ * @see Date
+ * @see Week
+ * @see MonthOfYear
+ * @see Year
  */
 
-public enum TimeUnit {
-    SECOND,
-    MINUTE,
-    HOUR
+public abstract class Unit<G> : Span, Collection.SimpleIterable<Date> {
+    public const string PROP_DATE_UNIT = "date-unit";
+    
+    /**
+     * Returns the { link DateUnit} this { link Unit} represents.
+     */
+    public DateUnit date_unit { get; private set; }
+    
+    protected Unit(DateUnit date_unit, Date start_date, Date end_date) {
+        base (start_date, end_date);
+        
+        this.date_unit = date_unit;
+    }
+    
+    /**
+     * This is specifically for { link Date}, which can't pass itself down to { link Span} as that
+     * will create a reference cycle, or for child classes which need to do more work before
+     * providing a date span.
+     *
+     * If the latter, the child class should call { link init_span} to complete initialization.
+     */
+    protected Unit.uninitialized(DateUnit date_unit) {
+        base.uninitialized();
+        
+        this.date_unit = date_unit;
+    }
+    
+    /**
+     * The next chronological discrete unit of time.
+     */
+    public G next() {
+        return adjust(1);
+    }
+    
+    /**
+     * The previous chronological discrete unit of time.
+     */
+    public G previous() {
+        return adjust(-1);
+    }
+    
+    /**
+     * Returns the same type of { link Unit} adjusted a quantity of units from this one.
+     *
+     * Subtraction (adjusting to a past date) is acheived by using a negative quantity.
+     */
+    public abstract G adjust(int quantity);
+    
+    /**
+     * Returns the number of { link Unit}s between the two.
+     *
+     * If the supplied Unit is earlier than this one, a negative value is returned.
+     */
+    public abstract int difference(G other);
+    
+    /**
+     * True if the { link Unit} contains the specified { link Date}.
+     *
+     * This is named to conform to Vala's rule for automatic syntax support.  This allows for the
+     * ''in'' operator to function on DiscreteUnits, but only for Dates (which is a common
+     * operation).
+     */
+    public bool contains(Date date) {
+        return has_date(date);
+    }
+    
+    /**
+     * Returns a { link Collection.SimpleIterator} of all the { link Date}s in the
+     * { link Unit}'s span of time.
+     *
+     * This is named to conform to Vala's rule for automatic iterator support.  This allows for
+     * the ''foreach'' operator to function on DiscreteUnits, but only for Dates (which is a
+     * common operation).
+     */
+    public Collection.SimpleIterator<Date> iterator() {
+        return date_iterator();
+    }
 }
 
 }
+
diff --git a/src/calendar/calendar-week.vala b/src/calendar/calendar-week.vala
index 64349e7..b52d83d 100644
--- a/src/calendar/calendar-week.vala
+++ b/src/calendar/calendar-week.vala
@@ -18,7 +18,7 @@ namespace California.Calendar {
  * { link Date.week_of} to obtain a Week for a particular calendar day.
  */
 
-public class Week : DiscreteUnit<Week>, Gee.Comparable<Week>, Gee.Hashable<Week> {
+public class Week : Unit<Week>, Gee.Comparable<Week>, Gee.Hashable<Week> {
     /**
      * The one-based week of the month (1 to 6).
      */
diff --git a/src/calendar/calendar-year.vala b/src/calendar/calendar-year.vala
index a5b8eb1..a04960c 100644
--- a/src/calendar/calendar-year.vala
+++ b/src/calendar/calendar-year.vala
@@ -13,7 +13,7 @@ namespace California.Calendar {
  * value is described as thousands of years from now.
  */
 
-public class Year : DiscreteUnit<Year>, Gee.Comparable<Year>, Gee.Hashable<Year> {
+public class Year : Unit<Year>, Gee.Comparable<Year>, Gee.Hashable<Year> {
     /**
      * The year as an integer.
      */
diff --git a/src/calendar/calendar.vala b/src/calendar/calendar.vala
index 97df645..6c4d5bc 100644
--- a/src/calendar/calendar.vala
+++ b/src/calendar/calendar.vala
@@ -17,6 +17,31 @@
 
 namespace California.Calendar {
 
+/**
+ * An enumeration of various calendar units.
+ *
+ * @see Unit
+ */
+
+public enum DateUnit {
+    DAY,
+    WEEK,
+    MONTH,
+    YEAR
+}
+
+/**
+ * An enumeration of various time units.
+ *
+ * @see WallTime
+ */
+
+public enum TimeUnit {
+    SECOND,
+    MINUTE,
+    HOUR
+}
+
 private int init_count = 0;
 
 private static unowned string FMT_MONTH_YEAR_FULL;