time_span 0.0.1.beta.01 → 0.0.2

data/lib/time_span.rb

@@ -1,18 +1,29 @@
-#require "time_span/version"
+require "time_span/version"
 
+# @author Craig A. Cook
 module TimeSpan
 
-  #######################################################################################################
-  #    this classes' object have a starting and ending RelativeTime, and both times must be on the same TimeLine
-  #
-  #    it implements a large selection of comparators, both for start / end times (single time compartors),
-  #    and also range comparators
+  # this class' objects have a starting and ending TimeSpan::RelativeTime, and both times must be on the same TimeSpan::TimeLine
+  # implements a large selection of comparators, both for start / end times (single time compartors),
+  # and also range comparators
+  # @author Craig A. Cook
   class TimeSpan
 
-    attr_accessor :starts, :ends, :time_line, :name     # RelativeTime objects
-
+    # TimeSpan::RelativeTime start time
+    attr_accessor :starts
+    # TimeSpan::RelativeTime end time
+    attr_accessor :ends
+    # TimeSpan::TimeLine this TimeSpan is associated with
+    attr_accessor :time_line
+    attr_accessor :name
+
+    # @param [TimeSpan::RelativeTime] starting_at is when the span starts
+    # @param [TimeSpan::RelativeTime] ending_at is when the spa nends
+    # @param [TimeSpan::TimeLIne] is the associated TimeLine
+    # @param [String] The name of the TimeSpan (Actually any Ruby Object for which '#respond_to?(:to_s) == true')
+    # @return [Boolean] true if passed arguments are valid to create a TimeSpan
     def initialize(starting_at, ending_at, t_line, nom="(unnamed)")
-      raise "Cannot make a span unless both points are on the same time_line" unless  starting_at.colinear_with?(ending_at)
+      raise ArgumentError, "Cannot make a span unless both points are on the same time_line" unless  starting_at.colinear_with?(ending_at)
       self.starts           = starting_at
       self.ends             = ending_at
       self.time_line        = t_line
@@ -21,6 +32,8 @@ module TimeSpan
       starting_at.kind_of?(RelativeTime) && ending_at.kind_of?(RelativeTime) && (starting_at <= ending_at)
     end
 
+    # returns the 'statuses' for the start and end times
+    # @return start and end time statuses in a hash with key is self
     def endpoint_statuses
       {self => [self.starts.reference_to, self.ends.reference_to]}
     end
@@ -31,61 +44,102 @@ module TimeSpan
   #                                                                                                     #
   #######################################################################################################
 
-    def starts_before?(b)
-      starts < b.starts
+    # tests  if one TimeSpan starts before another (on the same TimeLine)
+    # @param [TimeSpan::TimeSpan] other_time_span the TimeSpan being compared to self
+    # @return  true if self starts before b starts
+    def starts_before?(other_time_span)
+      starts < other_time_span.starts
     end
 
-    def starts_after?(b)
-      starts > b.starts
+    # tests  if one TimeSpan starts after another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self starts after other_time_span starts
+    def starts_after?(other_time_span)
+      starts > other_time_span.starts
     end
 
-    def starts_on_or_after?(b)
-      starts >= b.starts
+    # tests  if one TimeSpan starts with or after another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self starts on or after other_time_span starts
+    def starts_on_or_after?(other_time_span)
+      starts >= other_time_span.starts
     end
 
-
-    def starts_with?(b)
-      starts == b.starts
+    # tests  if one TimeSpan starts at the same time as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self starts at the same time as other_time_span starts
+    def starts_with?(other_time_span)
+      starts == other_time_span.starts
     end
 
-    def starts_before_or_with?(b)
-      starts <= b.starts
+    # tests  if one TimeSpan starts before or at the same time as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self starts before or at the same time as other_time_span starts
+    def starts_before_or_with?(other_time_span)
+      starts <= other_time_span.starts
     end
 
-    def ends_before?(b)
-      ends < b.ends
+    # tests  if one TimeSpan ends before another starts (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends before another time_span starts
+    def ends_before?(other_time_span)
+      ends < other_time_span.ends
     end
 
-    def ends_on_or_before?(b)
-      ends <= b.ends
+    # tests  if one TimeSpan end before or at the same time as another ends (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends before or at the same time as another time_span ends
+    def ends_on_or_before?(other_time_span)
+      ends <= other_time_span.ends
     end
 
-    def ends_on_or_after?(b)
-      ends >= b.ends
+    # tests  if one TimeSpan ends after or at the same time as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends after or at the same time as another time_span ends
+    def ends_on_or_after?(other_time_span)
+      ends >= other_time_span.ends
     end
 
-    def ends_after?(b)
-      ends > b.ends
+    # tests  if one TimeSpan ends after another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends after another time_span ends
+    def ends_after?(other_time_span)
+      ends > other_time_span.ends
     end
 
-    def ends_with?(b)
-      ends == b.ends
+    # tests  if one TimeSpan ends at the same time as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends at the same time as another time_span ends
+    def ends_with?(other_time_span)
+      ends == other_time_span.ends
     end
 
-    def ends_before_other_starts?(b)
-      ends < b.starts
+    # tests  if one TimeSpan ends before another starts (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends before another time_span starts
+    def ends_before_other_starts?(other_time_span)
+      ends < other_time_span.starts
     end
 
-    def ends_as_other_starts?(b)
-      ends == b.starts
+    # tests  if one TimeSpan ends at the same time as another starts (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends at the same time as another time_span starts (no gap)
+    def ends_as_other_starts?(other_time_span)
+      ends == other_time_span.starts
     end
 
-    def starts_after_other_ends?(b)
-      starts > b.ends
+    # tests  if one TimeSpan ends at the same time as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self ends at the same time as another time_span ends
+    def starts_after_other_ends?(other_time_span)
+      starts > other_time_span.ends
     end
 
-    def starts_as_other_ends?(b)
-      starts == b.ends
+    # tests  if one TimeSpan starts at the same time as another ends (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self starts at the same time as another time_span ends
+    def starts_as_other_ends?(other_time_span)
+      starts == other_time_span.ends
     end
 
     ##################################
@@ -98,36 +152,62 @@ module TimeSpan
     ##    unless it is meant < XOR =
 
 
-    def == (b)
-      ends_with?(b) && starts_with?(b)
+    # tests  if one TimeSpan is the same as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return [Boolean] true if same as the other
+    def == (other_time_span)
+      ends_with?(other_time_span) && starts_with?(other_time_span)
     end
 
-    def != (b)
-      !end_with(b) || !starts_with(b)
+    # tests  if one TimeSpan is not the same as another (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return [Boolean] true if not same as the other
+    def != (other_time_span)
+      !end_with(other_time_span) || !starts_with(other_time_span)
     end
 
-    def < (b)
-      ends_before_other_starts?(b)
+    # tests  if one TimeSpan ends before another starts (on the same TimeLine)
+    # alias for '#ends_before_other_starts'
+    # @param (see #starts_before? )
+    # @return [Boolean] true if self ends before another starts
+    def < (other_time_span)
+      ends_before_other_starts?(other_time_span)
     end
 
-    def > (b)
-      starts_after_other_ends?(b)
+    # tests  if one TimeSpan starts after another ends (on the same TimeLine)
+    # alias for '#starts_after_other_ends'
+    # @param (see #starts_before? )
+    # @return [Boolean] true if self starts after another ends
+    def > (other_time_span)
+      starts_after_other_ends?(other_time_span)
     end
 
-    def contained_fully_inside?(b)
-      starts_after?(b) && ends_before?(b)
+    # tests  if one TimeSpan is contained within  another  (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self contained inside another
+    def contained_fully_inside?(other_time_span)
+      starts_after?(other_time_span) && ends_before?(other_time_span)
     end
 
-    def contained_inside?(b)
-      starts_on_or_after?(b) && ends_on_or_before?(b)
+    # tests  if one TimeSpan is contained within another, possibly begining as or ends as another  (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self contained inside another, including same endpoints
+    def contained_inside?(other_time_span)
+      starts_on_or_after?(other_time_span) && ends_on_or_before?(other_time_span)
     end
 
-    def contains_fully?(b)
-      starts_before?(b) && ends_after?(b)
+    # tests  if one TimeSpan contains another  (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self contains another
+    def contains_fully?(other_time_span)
+      starts_before?(other_time_span) && ends_after?(other_time_span)
     end
 
-    def contains?(b)
-      starts_before_or_with?(b) && ends_on_or_after?(b)
+    # tests  if one TimeSpan contains within  another  (on the same TimeLine)
+    # @param (see #starts_before? )
+    # @return true if self contains another
+    def contains?(other_time_span)
+      starts_before_or_with?(other_time_span) && ends_on_or_after?(other_time_span)
     end
 
   end
@@ -152,44 +232,58 @@ module TimeSpan
   #    compress! -- compresses the TimeLine, removing [] and adjusting the index accordingly            #
   #                                                                                                     #
   #######################################################################################################
+  # @author Craig A. .Cook
   class TimeLine <  Array
 
     attr_accessor :line, :indices_of, :name, :spans
 
+
+    def initialize(name="")
+      @name = name
+      @line = []
+      @indices_of = {}
+      @spans = []
+    end
+
+    # returns the TimeLine's name
+    # @return [String] TimeLine's name'
     def to_s
       name.to_s
     end
 
+    # endpoint statuses for all TimeSpans on the TimeLine, plus TimeLine name
+    # @return [String] TimeSpan endpoint statuses + TimeLine name
     def inspect
       line.inspect + name
     end
 
+    # @return [Array] endpoint statuses for all TimeSpan s on the TimeLine
     def all_endpoint_statuses
       spans.inject({}){ |acc, span| acc.merge!(span.endpoint_statuses) }
     end
 
-    ## attached times only
+    ## attached times only (internal API)
+    # @return [Array] indices of keys
     def relative_times
       indices_of.keys
     end
 
+    # all statuses on the TimeLine
+    # @return [Array] statuses for all attached RelativeTime s on the TimeLine
     def all_relative_time_statuses
       relative_times.inject([]) {|acc, v| acc << v.reference_to }
     end
 
-    def initialize(name="")
-      @name = name
-      @line = []
-      @indices_of = {}
-      @spans = []
-    end
-
     ## indices methods
 
+    ## find the position of a RelativeTime on the TimeLine
+    # @return [Fixnum] RelativeTime's position on the TimeLine (self)
     def position_of(obj)
       @indices_of[obj]
     end
 
+    # bump up indices after a point, so that a RelativeTime may be inserted
+    # @return nil  no return value, helper method to keep data structures up to date.
     def increase_after(pos, by=1)
       @indices_of.each_key do |key|
         @indices_of[key] += by if (@indices_of[key] >= pos)
@@ -199,16 +293,25 @@ module TimeSpan
     ## insertion
 
     # add to the  end of the TimeLine
+    # @param obj object to be inserted into the TimeLine
+    # @return (see #insert_at)
     def append(obj)
       insert_at(@line.size, obj)
     end
 
     # inserts to the end of the relative object's time, becoming equal with it
+    # @param  relative_obj object after which to insert  obj
+    # @param  obj  object inserted after relative_object
+    # @return (see #insert_at)
     def append_to_next(relative_obj, obj, relative=1)
       insert_at(position_of(relative_obj)+relative, obj)
     end
 
     ## inserts into a new space before the relative object (first parameter)
+    # inserts obj before relative_obj by offset
+    # @param relative_obj object for computing position where obj is inserted
+    # @param the inserted object
+    # @return (see #insert_at)
     def insert_before_next(relative_obj, obj, relative_offset=1)
       relative_position = position_of(relative_obj)
       increase_after(relative_position + relative_offset, relative_offset)
@@ -217,8 +320,11 @@ module TimeSpan
     end
 
     ## place obj at the numbered position
+    # @param pos where to insert obj in the TimeLIne
+    # @param obj obj inserted into the TimeLIne
+    # @return [Fixnum] ]the (relative) position where the object was inserted
     def insert_at(pos, obj)
-      raise "can only add a time to its own time_line" unless obj.time_line.equal? self
+      raise ArgumentError, "can only add a time to its own time_line" unless obj.time_line.equal? self
       if @line[pos].nil?
         @line[pos] = [obj]
       else
@@ -231,6 +337,8 @@ module TimeSpan
 
     # cannot remove [] or the @indices_of will be wrong
     # call  #compress to remove the extra []s
+    # @param obj object to be removed from the TimeLIne
+    # @return []nil|Fixnum] position of deleted object
     def remove(obj)
       pos =  position_of(obj)
       if pos                        # do nothing if it isn't there'
@@ -241,6 +349,7 @@ module TimeSpan
 
     ## removes all [] elements, and decrements accordingly the @indices_of
     ##  ideally this should be transactional
+    # @return [nil] cleanup method
     def compress!
       mod_level = 0
       offsets = []
@@ -278,41 +387,56 @@ module TimeSpan
   #                                                                                                     #
   #  RelativeTime must be within a TimeLine                                                             #
   #######################################################################################################
+  #
+  # @author Craig A. Cook
   class RelativeTime
 
-    attr_accessor  :time_line, :reference_to    # reference_to should respond_to? :to_s
+    attr_accessor  :time_line       # TimeLine on which this RelativeTime is placed
+    attr_accessor   :reference_to    # Object (PORO) reference_to should respond_to? :to_s
 
     # create a realtive time *within a time_line*  after position
+    # @param tline [TimeSpan::TimeLine] TimeLIne on which this RelativeTime is placed
+    # @param ref [Object] the object placed on the timeline
+    # @return the .to_s of the referenced object
     def initialize  tline, ref
        @time_line= tline
        @reference_to= ref
     end
 
+    # @return [String] the string representation of referenced object
     def to_s
-      reference_to.to_s
+      @reference_to.to_s
     end
 
+    # comparator methods
+    # @param [TimeSpan::RelativeTime] other_relative_time time being compared to
+    # @return [Boolean] depending on the relationship
     ## any method on fixnum with 1 RelativeTime param can be in the list below
     %w{< <= == != >= >}.each{ |meth|
-      self.send(:define_method, meth) {|b|
-        raise "can only compare to other times on the same time_line." unless valid_and_comparable_with?(b)     # can NOT compare across TimeLines
-        self.time_line.position_of(self).send(meth, b.time_line.position_of(b))
+      self.send(:define_method, meth) {|other_relative_time|
+        raise ArgumentError, "can only compare to other times on the same time_line." unless valid_and_comparable_with?(other_relative_time)     # can NOT compare across TimeLines
+        self.time_line.position_of(self).send(meth, other_relative_time.time_line.position_of(other_relative_time))
       }
     }
 
+    # @return [Boolean] true if self has been properly placed on a TimeLine
     def positioned?
       self.time_line && self.time_line.indices_of.include?(self)
     end
 
-    def colinear_with?(b)
-      b.kind_of?(self.class) &&  b.positioned? && positioned? &&  time_line.equal?(b.time_line)
+    # @param [TimeSpan::RelativeTime]  other time to be sure is on self's TimeLIne
+    # @return [Boolean] true if both are on the same TimeLine
+    def colinear_with?(other_relative_time)
+      other_relative_time.kind_of?(self.class) &&  other_relative_time.positioned? && positioned? &&  time_line.equal?(other_relative_time.time_line)
     end
 
 
     protected
 
-    def valid_and_comparable_with?(b)
-      !self.time_line.nil? && !b.time_line.nil?  &&  colinear_with?(b)
+    # @param [TimeSpan::RelativeTime] RelativeTime to check for comparability with
+    # @return [Boolean] true if they can be compared
+    def valid_and_comparable_with?(other_relative_time)
+      !self.time_line.nil? && !other_relative_time.time_line.nil?  &&  colinear_with?(other_relative_time)
     end
 
 

data/spec/time_span/time_span_spec.rb

@@ -31,6 +31,7 @@ describe "TimeSpan" do
     timeline.append time_a
     timeline.append time_b
     timeline.append time_c
+    timeline.spans <<  time_span
   end
 
 
@@ -40,6 +41,10 @@ describe "TimeSpan" do
 
       context "statues" do
 
+        it "should have non-empty endpoint statuses" do
+          timeline.all_endpoint_statuses.should_not be_empty
+        end
+
         it "should get all the endpoint statuses" do
           timeline.all_endpoint_statuses.should ==  {time_span => [time_span.starts.reference_to, time_span.ends.reference_to]}
         end
@@ -69,7 +74,7 @@ describe "TimeSpan" do
         it "won't insert into the wrong timeline" do
           timeline_b = TimeSpan::TimeLine.new "Another Timeline"
           lambda {
-          timeline_b.append(time_a) }.should raise_error RuntimeError
+          timeline_b.append(time_a) }.should raise_error ArgumentError
         end
 
         it "populates the index hash"  do
@@ -182,12 +187,16 @@ describe "TimeSpan" do
 
       context "creation" do
 
+        it "should have a timeline associated" do
+          timeline.spans.should_not be_empty
+        end
+
         it "should not allow creation when RelativeTime elements which are not on the same TimeLine" do
           other_timeline = TimeSpan::TimeLine.new "another timeline"
           time_other = TimeSpan::RelativeTime.new other_timeline, "Time on other timeline"
           lambda {
             TimeSpan::TimeSpan.new(time_a, time_other)
-          }.should raise_error
+          }.should raise_error ArgumentError
         end
 
       end
@@ -353,4 +362,4 @@ describe "TimeSpan" do
 
   end
 
-end
+end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: time_span
 version: !ruby/object:Gem::Version
-  version: 0.0.1.beta.01
-  prerelease: 6
+  version: 0.0.2
+  prerelease: 
 platform: ruby
 authors:
 - Craig A. Cook
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-09 00:00:00.000000000 Z
+date: 2012-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &77411640 !ruby/object:Gem::Requirement
+  requirement: &73419500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *77411640
+  version_requirements: *73419500
 description: Time spans, including many comparators
 email:
 - craig.a.cook@gmail.com
@@ -31,6 +31,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - doc/Gemfile.html
@@ -39,7 +40,15 @@ files:
 - doc/TimeSpan/RelativeTime.html
 - doc/TimeSpan/TimeLine.html
 - doc/TimeSpan/TimeSpan.html
+- doc/_index.html
+- doc/class_list.html
 - doc/created.rid
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file_list.html
+- doc/frames.html
 - doc/images/brick.png
 - doc/images/brick_link.png
 - doc/images/bug.png
@@ -61,15 +70,19 @@ files:
 - doc/images/wrench_orange.png
 - doc/images/zoom.png
 - doc/index.html
+- doc/js/app.js
 - doc/js/darkfish.js
+- doc/js/full_list.js
 - doc/js/jquery.js
 - doc/js/quicksearch.js
 - doc/js/thickbox-compressed.js
 - doc/lib/time_span/version_rb.html
 - doc/lib/time_span_rb.html
+- doc/method_list.html
 - doc/rdoc.css
 - doc/spec/spec_helper_rb.html
 - doc/spec/time_span/time_span_spec_rb.html
+- doc/top-level-namespace.html
 - lib/time_span.rb
 - lib/time_span/version.rb
 - spec/spec_helper.rb
@@ -91,14 +104,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: time_span
-rubygems_version: 1.8.12
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: Time Span
 test_files: []
-has_rdoc: