module Custodian

  module Util

    #
    # A class for working with time-spans.
    #
    class TimeSpan


      #
      # Convert an hour-string into a sane integer.
      #
      def TimeSpan.to_hour(desc)

        #
        #  Handle PM times.
        #
        if  (desc.kind_of? String) &&
             (desc =~ /([0-9]+)pm$/i) 
          desc = $1.dup.to_i + 12
        end

        #
        #  Handle AM times.
        #
        if  desc.kind_of? String 
          desc = desc.sub(/am$/, '')
          desc = desc.to_i
        end

        #
        #  Ensure within a valid range
        #
        raise ArgumentError, 'Integer required for time'   unless desc.kind_of? Integer
        raise ArgumentError,  "Invalid time: #{desc}" unless (desc >= 0) && (desc <= 23)


        #
        # Return the updated string.
        #
        desc
      end




      #
      # Given a start/end string convert that
      # to a hash of hours which are inside the
      # range - inclusively.
      #
      def TimeSpan.to_hours(p_start, p_end)

        p_start = Custodian::Util::TimeSpan.to_hour(p_start)
        p_end   = Custodian::Util::TimeSpan.to_hour(p_end)


        #
        #  Valid hours, within the span
        #
        valid = {}


        #
        #  Iterate over the hours.  Store in a hash.
        #
        hour = p_start
        while (hour != p_end)
          valid[hour] = 1
          hour += 1
          hour  = 0 if  hour > 23 
        end
        valid[p_end] = 1

        #
        #  Return the hash
        #
        valid
      end




      #
      # Given a starting hour, such as 10pm, and an ending hour,
      # such as 4am, test whether a time is within that period.
      #
      def TimeSpan.inside?(p_start, p_end, cur_hour = nil)

        #
        # Default to the current hour, if not specified.
        #
        if  cur_hour.nil? 
          cur_hour = Time.now.hour
        end

        #
        # Ensure all values are sane and reasonable.
        #
        p_start  = Custodian::Util::TimeSpan.to_hour(p_start)
        p_end    = Custodian::Util::TimeSpan.to_hour(p_end)
        cur_hour = Custodian::Util::TimeSpan.to_hour(cur_hour)

        #
        #  Get the expanded hours
        #
        valid =
          Custodian::Util::TimeSpan.to_hours(p_start, p_end)

        #
        # Lookup to see if the specified hour is within the
        # hours between the range.
        #
        (valid[cur_hour] == 1)
      end

    end
  end
end