sugarcube 0.8.7 → 0.9

data/README.md

@@ -88,43 +88,38 @@ end
  NSDate
 --------
 
-NSDate does not make it easy to get the sensible attributes of your datetime
-object.  This *does* make sense, if you are truly thinking globally, but I am
-not.  :-P
-
-Adds the following methods to get a date component: `year, month, day, hour, minute, second, yms, hms, datetime`
-
-`ymd`, `hms`, and `datetime` return arrays, so that comparing dates, times, or
-both become simple `date1.ymd == date2.ymd`.  If you need to *compare* dates,
-use the Foundation method `date1.compare(date2)` => `-1 or 0 or 1`.
-
-```
-(main)> now = NSDate.new
+`NSDate` objects are converted to `Time` objects automatically by rubymotion.
+That's the good news.  The bad news?  That still doesn't help a lot with some of
+the everyday date&time crap we have to deal with. (I hate dates, especially
+recurring events)
+
+1. Adds the following methods to get date and time components: `date, time, datetime`.
+
+   These methods return arrays.  Comparing dates, times, or both become
+   simple `date1.date == date2.date`.
+2. While I would love to support `date + 1.month` and have that support "smart"
+   calendar math (e.g. "2/13/2013" + 1.month => "3/13/2013"), I can't fudge with
+   the return value of `1.month` (=> `Fixnum`), and I won't make the terrible
+   assumption that "30 days of seconds is *about* one month".  So instead, a new
+   method that accepts date components as options is introduced.  `date.delta(month:1)`
+3. Something that is often done is checking whether two dates are the same,
+   ignoring the time components.  `start_of_day` and `end_of_day` methods help
+   you here.  They are akin to `floor` and `ceil`, if you consider the time to
+   be the "floating" component, and the date to be the nearest "integer".
+
+```
+(main)> now = NSDate.new  # Time.new is the same thing
 => 2012-09-13 09:19:06 -0600
-(main)> now.year
-=> 2012
-(main)> now.month
-=> 9
-(main)> now.day
-=> 13
-(main)> now.hour
-=> 9
-(main)> now.minute
-=> 19
-(main)> now.second
-=> 6
-(main)> now.weekday
-=> 5
-(main)> now.ymd
+(main)> now.date
 => [2012, 9, 13]
-(main)> now.hms
+(main)> now.time
 => [9, 19, 6]
 (main)> now.datetime
 => [2012, 9, 13, 9, 19, 6]
 ```
 
-And it is easy to add seconds to the date, and don't forget about the
-time-related methods added to `Numeric`!
+And it is easy to add seconds to the date using the time-related methods added
+to `Numeric`, and the useful `start_of_day`/`end_of_day` methods.
 
 ```ruby
 (main)> now + 5
@@ -135,11 +130,15 @@ time-related methods added to `Numeric`!
 => 2012-09-13 09:24:06 -0600
 (main)> now + 5.days
 => 2012-09-18 09:19:06 -0600
+(main)> now.start_of_day
+=> 2012-09-13 00:00:00 -0600
+(main)> now.end_of_day
+=> 2012-09-14 00:00:00 -0600
 ```
 
-Time zone objects are available, but the `utc_offset` is a little more
-immediately useful.  It returns the offset *in seconds*, so divide by `1.0.hour`
-to get the offset in hours.
+Time zone objects are available, but the `Time#utc_offset` method is a little
+more useful.  It returns the offset *in seconds*, so divide by `1.0.hour` to get
+the offset in hours.  `utc_offset` is built into `Time`, not added by SugarCube.
 
 ```ruby
 (main)> now.timezone
@@ -148,10 +147,63 @@ to get the offset in hours.
 => "America/Denver"
 (main)> now.utc_offset
 => -21600
-(main)> now.utc_offset / 1.0.hour
-=> -6.0
+(main)> now.utc_offset / 1.hour
+=> -6
 ```
 
+The `delta` method is smart.
+
+```ruby
+(main)> feb_28_2012_stamp = 1330473600  # what, you don't have this memorized?
+=> 1330473600
+(main)> feb_28_2012 = Time.at(feb_28_2012_stamp)
+=> 2012-02-28 17:00:00 -0700
+
+(main)> feb_28_2012.delta(hours:1)
+=> 2012-02-28 18:00:00 -0700
+(main)> feb_28_2012.delta(hours:2)
+=> 2012-02-28 19:00:00 -0700
+
+(main)> feb_28_2012.delta(days:1)
+=> 2012-02-29 17:00:00 -0700
+(main)> feb_28_2012.delta(days:2)
+=> 2012-03-01 17:00:00 -0700
+
+(main)> feb_28_2012.delta(months:1)
+=> 2012-03-28 17:00:00 -0600  # look, the time didn't change, event though there was a DST change!
+(main)> feb_28_2012.delta(months:1, hours:0)
+=> 2012-03-28 18:00:00 -0600  # disable the DST fix by specifying hours, minutes, or seconds (a "precise" delta)
+
+(main)> feb_28_2012.delta(years:1)
+=> 2013-02-28 17:00:00 -0700
+(main)> feb_28_2012.delta(days:1, years:1)
+=> 2013-02-28 17:00:00 -0700
+(main)> feb_28_2012.delta(days:1, years:1, months:1)
+=> 2013-03-29 17:00:00 -0600
+
+(main)> jan_29_2013 = feb_28_2012.delta(days:1, months:11)
+=> 2013-01-29 17:00:00 -0700
+
+# what is 1/29/2013 plus two months?  easy!  march 29, 2013
+(main)> jan_29_2013.delta(months:2)
+=> 2013-03-29 17:00:00 -0600
+
+# yeah, smart guy? well then what is 1/29/2013 plus ONE month.
+# it's feb 28th.  trust me.  when someone says "see you in a month!"
+# they mean "next month", not "in the early part of two months in the future",
+# which is where the math will take you if you don't add a "day of month" correction.
+(main)> jan_29_2013.delta(months:1)
+=> 2013-02-28 17:00:00 -0700
+
+# does it work in reverse?  fuuuuuu...
+(main)> jan_29_2013.delta(months:-11)
+=> 2012-02-29 17:00:00 -0700
+# ...ck yeah!  :-)
+
+# unfortunately you will end up with stuff like this:
+(main)> feb_28_2012 == feb_28_2012.delta(days:1, months:12).delta(months:-12)
+=> true
+```
 
  NSURL
 -------
@@ -465,16 +517,20 @@ after 1.minute do
 end
 
 # other time-related methods
+# for compatibility with Time methods, the mins/secs (and min/sec) aliases are provided.  Personally,
+# I like the more verbose minutes/seconds.
 1.second  || 2.seconds
-1.minute  || 2.minutes  # 60 seconds
-1.hour    || 2.hours    # 60 minutes
-1.day     || 2.days     # 24 hours
-1.week    || 2.weeks    # 7 days
-# with sensible values for 'month' and 'year', even though we all know you can't
+1.sec     || 2.secs     # aliases
+1.minute  || 2.minutes  # 1.minute = 60 seconds
+1.min     || 2.mins     # aliases
+1.hour    || 2.hours    # 1.hour = 60 minutes
+1.day     || 2.days     # 1.day = 24 hours
+1.week    || 2.weeks    # 1.week = 7 days
+# sensible values for 'month' and 'year', even though we all know you can't
 # **really** define them this way (go back to python if you find your brain
 # hemorrhaging):
-1.month   || 2.months   # 30 days
-1.year    || 2.years    # 365 days
+1.month   || 2.months   # 1.month = 30 days
+1.year    || 2.years    # 1.year = 365 days
 ```
 
  NSUserDefaults

data/lib/sugarcube/nsdate.rb

@@ -1,62 +1,49 @@
 class NSDate
-  def year
-    return components(NSYearCalendarUnit).year
+  def timezone
+    return _calendar_components(NSTimeZoneCalendarUnit).timeZone
   end
+  alias timeZone timezone
 
-  def month
-    return components(NSMonthCalendarUnit).month
+  def utc_offset
+    return self.timezone.secondsFromGMT
   end
 
-  def day
-    return components(NSDayCalendarUnit).day
+  def leap?
+    self.year % 4 == 0 and self.year % 100 != 0 or self.year % 400 == 0
   end
 
-  def ymd
+  def date
     return [self.year, self.month, self.day]
   end
 
-  def weekday
-    return components(NSWeekdayCalendarUnit).weekday
-  end
-
-  def hour
-    return components(NSHourCalendarUnit).hour
-  end
-
-  def minute
-    return components(NSMinuteCalendarUnit).minute
+  def time
+    return [self.hour, self.min, self.sec]
   end
 
-  def second
-    return components(NSSecondCalendarUnit).second
-  end
-
-  def timezone
-    return components(NSTimeZoneCalendarUnit).timeZone
+  def datetime
+    return [self.year, self.month, self.day, self.hour, self.min, self.sec]
   end
-  alias timeZone timezone
 
-  def utc_offset
-    return self.timezone.secondsFromGMT
+  def start_of_day
+    time_interval = self.hour.hours + self.min.minutes + self.sec
+    return self - time_interval
   end
 
-  def hms
-    return [self.hour, self.minute, self.second]
+  def end_of_day
+    time_interval = (23 - self.hour).hours + (59 - self.min).minutes + 60 - self.sec
+    return self + time_interval
   end
 
-  def datetime
-    return [self.year, self.month, self.day, self.hour, self.minute, self.second]
+  def days_in_month
+    NSCalendar.currentCalendar.rangeOfUnit(NSDayCalendarUnit, inUnit:NSMonthCalendarUnit, forDate:self).length
   end
 
-  def +(time_interval)
-    return self.dateByAddingTimeInterval(time_interval)
+  def days_in_year
+    NSCalendar.currentCalendar.rangeOfUnit(NSDayCalendarUnit, inUnit:NSYearCalendarUnit, forDate:self).length
   end
 
   private
-  def components(components)
-    unless (@@calendar ||= nil)
-      @@calendar = NSCalendar.alloc.initWithCalendarIdentifier(NSGregorianCalendar)
-    end
-    return @@calendar.components(components, fromDate:self)
+  def _calendar_components(components)
+    return NSCalendar.currentCalendar.components(components, fromDate:self)
   end
 end

data/lib/sugarcube/nsdate_delta.rb

@@ -0,0 +1,114 @@
+class NSDate
+
+  def +(val)
+    if val.is_a?(Hash)
+      return self.delta(val)
+    end
+    super
+  end
+
+  def delta(_components)
+    components = {}.update(_components)
+    is_very_specific = components.has_key?(:seconds)
+    is_very_specific ||= components.has_key?(:minutes)
+    is_very_specific ||= components.has_key?(:hours)
+
+    y = components.delete(:years) || 0
+    mo = components.delete(:months) || 0
+    d = components.delete(:days) || 0
+    h = components.delete(:hours) || 0
+    mi = components.delete(:minutes) || 0
+    s = components.delete(:seconds) || 0
+    w = components.delete(:weeks) || 0
+    raise "Unknown arguments #{components.keys}" unless components.empty?
+
+    is_dst = self.dst?
+
+    delta = s
+    # todo: leap second adjustment?  can leap seconds be detected?
+    delta += mi.minutes
+    delta += h.hours
+
+    delta += d.days
+    delta += w.weeks
+    return_date = self + delta
+
+    # using days_in_month, this is pretty easy.  12 mos per year IS a constant,
+    # and then we just keep adding the number of days in the month (or last month
+    # if we're going backwards).  The curve ball is that when we are in day
+    # 29,30,31, we might jump forward a month and "fall off" to the next month.
+    # In this case, we add a correction.  We will always move forwards or
+    # backwards until the return_date.day is correct.
+    mo += y * 12
+    if mo != 0
+      if return_date.day > 28
+        # we will try and preserve this day
+        correct_day_of_month = return_date.day
+      else
+        correct_day_of_month = nil
+      end
+
+      if mo > 0
+        mo.times do
+          delta = return_date.days_in_month
+          return_date += delta.days
+
+          # if the day_of_month is wrong, it must be because we either added PAST
+          # the correct month (so roll back), or because we WERE rolled back and
+          # when we moved forward a month, we were left back at the smaller day.
+          if correct_day_of_month
+            if return_date.day < 28
+              return_date -= return_date.day.days
+            elsif return_date.day < correct_day_of_month
+              fix = correct_day_of_month > return_date.days_in_month ? return_date.days_in_month : correct_day_of_month
+              return_date += (fix - return_date.day).days
+            end
+          end
+        end
+      elsif mo < 0
+        (-mo).times do
+          # subtract *last* months number of days.
+          # there is a REALLY rare case where subtracting return_date.day is one
+          # hour short of "last month" and so you end up with THIS month.  there
+          # is NEVER a case when subtracting return_date.day+1 days is NOT
+          # "previous month".  dates. :-|  f-em.
+          delta = (return_date - (return_date.day+1).days).days_in_month
+          return_date -= delta.days
+          # same correction as above
+          if correct_day_of_month
+            if return_date.day < 28
+              return_date -= return_date.day.days
+            elsif return_date.day < correct_day_of_month
+              fix = correct_day_of_month > return_date.days_in_month ? return_date.days_in_month : correct_day_of_month
+              return_date += (fix - return_date.day).days
+            end
+          end
+        end
+      end
+    end
+
+    # DST adjustment, unless minutes, hours, or seconds were specified.
+    #
+    # the thinking here is that if they WERE specified, the delta should be
+    # accurate to that granularity.  if they were omitted, the hour component
+    # should not change, even though an off-by-one adjustment is needed
+    #
+    # for instance.  3/10/2012 is not in DST.  3/11/2012 IS.
+    # Time.at(3/10/2012)  # => 2012-03-10 17:00:00 -0700
+    # Time.at(3/10/2012).delta(days:1)  # => 2012-03-11 17:00:00 -0600
+    #
+    # notice the time is the SAME, even though the time zone is different.  BUT:
+    # Time.at(3/10/2012).delta(hours:24)  # => 2012-03-11 17:00:00 -0600
+    # Time.at(3/10/2012).delta(hours:25)  # => 2012-03-11 18:00:00 -0600
+    unless return_date.dst? == is_dst or is_very_specific
+      if is_dst
+        return_date += 1.hour
+      else
+        return_date -= 1.hour
+      end
+    end
+
+    return return_date
+  end
+
+end

data/lib/sugarcube/numeric.rb

@@ -8,11 +8,15 @@ class Numeric
     self
   end
   alias second seconds
+  alias sec seconds
+  alias secs seconds
 
   def minutes
     self * 60
   end
   alias minute minutes
+  alias min minutes
+  alias mins minutes
 
   def hours
     self * 3600

data/lib/sugarcube/version.rb

@@ -1,3 +1,3 @@
 module SugarCube
-  Version = '0.8.7'
+  Version = '0.9'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sugarcube
 version: !ruby/object:Gem::Version
-  version: 0.8.7
+  version: '0.9'
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-13 00:00:00.000000000 Z
+date: 2012-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70310166918200 !ruby/object:Gem::Requirement
+  requirement: &70323060274480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70310166918200
+  version_requirements: *70323060274480
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70310166917660 !ruby/object:Gem::Requirement
+  requirement: &70323060273940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,7 +33,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70310166917660
+  version_requirements: *70323060273940
 description: ! '== Description
 
 
@@ -75,6 +75,7 @@ files:
 - lib/sugarcube/fixnum.rb
 - lib/sugarcube/notifications.rb
 - lib/sugarcube/nsdate.rb
+- lib/sugarcube/nsdate_delta.rb
 - lib/sugarcube/nsindexpath.rb
 - lib/sugarcube/nsindexset.rb
 - lib/sugarcube/nsstring.rb