skn_utils 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e5f35b9cb8f4d40e5450210986430079a3dc62b
-  data.tar.gz: 165cb18c3053dedaa3f72a96c007a4b1d2170d3a
+  metadata.gz: aec86482b36e3dc0625a89641a5220417cbb4761
+  data.tar.gz: dd1e2519bf5d407deb7c05f1d7454e2b2db2e9e1
 SHA512:
-  metadata.gz: 6ad5ece92556a9124e64178cf0d51b47a146fd338fdbd07fdfe97b44d8dcd217857308a4e31b963b54bbef2c401ee1191b94fda25f300744aeb042cef58a70d0
-  data.tar.gz: 879e7b4feb2b76ebfd0ba5ff540e8deb96fa52d198050b8402b4906a10a8dbea65164ebe997a15c45b8591176c9b336295a03e136392d32aec4299635ed5ba30
+  metadata.gz: 1f8b4978cd8bdf65eece11e09f400ba65f1b3904fc61e7c6f88889b968a9802cad5155b3bb9dea96ad960f5d147b81bf00ca1a04e742e86fe6863afdafa6ef54
+  data.tar.gz: f61b021c403bf7dcade30dab45625078e0e8e19c48f41d3f1a73820e7996f48663683a1a16bca40997630ced0bfce38ae57640d4b86b37aff4a703f498a551ed

data/README.md

@@ -16,6 +16,10 @@ Ruby Gem containing a Ruby PORO (Plain Old Ruby Object) that can be instantiated
 
 
 ## New Features
+    08/2017  V3.3.0
+    Added Linked List classes which implement value based Singular, Doubly, and Circular linked lists patterns.  Value based implies
+    the internal nodes of a linked list are never returned through the public interface, only node contents or values.
+
     07/2017  V3.1.5
     Added SknSettings class for use as a replacement to the popular, but obsolete, Config.gem
     SknSettings.load_configuration_basename!(config_file_name-only) or 'Rails.env.to_s' value, will load all the yml files in this order:
@@ -48,10 +52,56 @@ Ruby Gem containing a Ruby PORO (Plain Old Ruby Object) that can be instantiated
 	Last Version to depend on Rails (ActiveModel) for #to_json and #to_xml serialization
 
 
+## Public Components
+    SknUtils::NestedResult           # >= V 3.0.0 Primary Key/Value Container with Dot/Hash notiation support.
+    SknSettings                      # Application Configuration class, Key/Value Container with Dot/Hash notiation support.
+
+    SknHash                          # Wrapper for name only, WITHOUT SknUtils namespace, inherits from SknUtils::NestedResult
+    SknUtils::ResultBean             # Wrapper for name only, inherits from SknUtils::NestedResult
+    SknUtils::PageControls           # Wrapper for name only, inherits from SknUtils::NestedResult
+
+    SknUtils::List::LinkedList          # List with forward (#next) navigation, and tail/open
+    SknUtils::List::DoublyLinkedList    # List with forward (#next) and backward (#prev) navigation, and head/tail open
+    SknUtils::List::CircularLinkedList  # List with forward (#next) and backward (#prev) navigation, and head/tail wrapping
+
+
 ## Configuration Options
     None required other than initialization hash
 
 
+## Public Methods: SknUtils::Lists::LinkedList, SknUtils::Lists::DoublyLinkedList, and SknUtils::Lists::CircularLinkedList
+    Each concrete Class supports the following methods:
+
+    Navigation: return related value from relative positon in list, stops on first/last node for Single/Double, wraps for Circular.
+      #first                       -- returns first value in list
+      #next                        -- returns next value from current position
+      #current                     -- returns current value
+      #prev                        -- returns previous value from current position (*not supported in Single)
+      #last                        -- returns last value from list
+      #nth(i)                      -- returns value of node at +|- positon relative to current position, (*negative not supported in Singular)
+      #at_index(i)                 -- returns value of i node relative to list's head
+
+    Enumeration
+      #each                        -- yields each value in list when block given, on Enumerator object
+      #to_a                        -- returns Array of each value in the list
+
+    State
+      #clear                       -- removes all elements and return number of elements removed
+      #empty?                      -- returns true if list has no elements, otherwise false
+      #size                        -- returns total count of elements in the list
+
+    Modification: returns number of elements in the list after the operation
+      #insert(value)                        -- inserts value after node at current positon, or appends
+      #append(value)                        -- inserts value after node at current positon
+      #prepend(value)                       -- inserts value before node at current positon
+      #insert_before(position_value, value) -- finds node matching position_value, then prepends new node
+      #insert_after(position_value, value)  -- finds node matching position_value, then appends new node
+      #remove(value)                        -- finds first node matching value, then destroys it
+
+    Initialization
+      #new(*values=nil)                     -- Instansiates new list and optionally creates nodes for each comma-seperated value.
+
+
 ## Public Methods: SknSettings ONLY
     SknSettings is global constant containing an initialized Object of SknUtils::SknConfiguration using defaults
     To change the 'development'.yml default please use the following method early or in the case of Rails in 'application.rb
@@ -86,16 +136,7 @@ Ruby Gem containing a Ruby PORO (Plain Old Ruby Object) that can be instantiated
       #eql?(other)                          -- returns true/false from camparison of the two objects
 
 
-## Public Components
-    SknUtils::NestedResult           # >= V 3.0.0 Primary Key/Value Container with Dot/Hash notiation support.
-    SknSettings                      # Application Configuration class, Key/Value Container with Dot/Hash notiation support.
-
-    SknHash                          # Wrapper for name only, WITHOUT SknUtils namespace, inherits from SknUtils::NestedResult
-    SknUtils::ResultBean             # Wrapper for name only, inherits from SknUtils::NestedResult
-    SknUtils::PageControls           # Wrapper for name only, inherits from SknUtils::NestedResult
-
-
-## Basic features include:
+## NestedResult Basic features include:
 ```ruby
  - provides the hash or dot notation methods of accessing values:
 
@@ -133,7 +174,7 @@ Ruby Gem containing a Ruby PORO (Plain Old Ruby Object) that can be instantiated
 ```
 
 
-## Usage:
+## NestedResult Usage:
 
 * The NestedResult produces these effects when given a params hash;
 * Follow VALUES that are Hashes, Arrays of Hashes, and Arrays of Arrays of Hashes

data/lib/skn_utils/lists/circular_linked_list.rb

@@ -0,0 +1,217 @@
+
+module SknUtils
+  module Lists
+    # Circularly Linked List
+    # Forward (#next) and Backwards (#prev) navigation
+    # No Head or Tail
+    class CircularLinkedList
+      attr_accessor :size
+
+      def initialize(*values)
+        @current = nil
+        @head = nil
+        @tail = nil
+        @size = 0
+        values.each {|value| insert(value) }
+      end
+
+      #
+      # Navigation
+      #
+
+      # return values and position current to last node accessed
+      # prevent @current from nil assignment
+      def first
+        @current = head if head
+        @current.value rescue nil
+      end
+
+      def next
+        @current = @current.next if @current and @current.next
+        @current.value rescue nil
+      end
+
+      def current
+        @current.value rescue nil
+      end
+
+      def prev
+        @current = @current.prev if @current and @current.prev
+        @current.value rescue nil
+      end
+
+      def last
+        @current = tail if tail
+        @current.value rescue nil
+      end
+
+      # -+ int position from current node
+      def nth(index)
+        node = @current
+        position = node
+        if index > 0
+          while index > 1 and node and node.next
+            node = node.next
+            index -= 1
+            @current = node
+            break if position === node
+          end
+        elsif index < 0
+          while index < 0 and node and node.prev
+            node = node.prev
+            index += 1
+            @current = node
+            break if position === node
+          end
+        end
+        current
+      end
+
+      # return node at positive index from head
+      def at_index(index)
+        find_by_index(index)
+        current
+      end
+
+      def empty?
+        size == 0
+      end
+
+      #
+      # Modifications
+      #
+
+      # return new size
+      def insert(value)
+        temp = @current.value rescue nil
+        insert_after(temp, value)
+      end
+
+      # return new size
+      def prepend(value)
+        temp = head.value rescue nil
+        insert_before(temp, value)
+      end
+      # return new size
+      def append(value)
+        temp = tail.value rescue nil
+        insert_after(temp, value)
+      end
+
+      # return new size
+      def insert_before(position_value, value)
+        target = find_by_value(position_value)
+        node = LinkNode.new(value, target, :circle_before)
+        @current = node if target
+        self.head = node if head === target
+        self.tail = node if tail.nil?
+        self.size += 1
+      end
+
+      # return new size
+      def insert_after(position_value, value)
+        target = find_by_value(position_value)
+        node = LinkNode.new(value, target, :circle_after)
+        @current = node
+        self.head = node if head.nil?
+        self.tail = node if tail === target
+        self.size += 1
+      end
+
+      # return remaining size
+      def remove(value)
+        target_node = find_by_value(value)
+        if target_node
+          @current = target_node.prev
+          @current.next = target_node.next
+          @current.next.prev = @current if @current and @current.next and @current.next.prev
+          target_node.remove!
+        end
+        self.tail = @current if tail === target_node
+        self.head = @current if head === target_node
+        self.size -= 1
+      end
+
+      # return number cleared
+      def clear
+        rc = 0
+        node = head
+        position = head
+        while node do
+          node = node.remove!
+          rc += 1
+          break if position === node
+        end
+
+        @current = nil
+        self.head = nil
+        self.tail = nil
+        self.size = 0
+        rc
+      end
+
+      #
+      # Enumerate
+      #
+
+      # perform each() or return enumerator
+      def each(&block)
+        @current = head
+        position = head
+        if block_given?
+          while position do
+            yield position.value.dup
+            position = position.next
+            break if position === @current
+          end
+        else
+          Enumerator.new do |yielder, val|
+            while position do
+              yielder << position.value.dup
+              position = position.next
+              break if position === @current
+            end
+          end
+        end
+      end
+
+      # convert self to a value array
+      def to_a
+        @current = head
+        position = head
+        result = []
+        while position do
+          result << position.value.dup
+          position = position.next
+          break if position === @current
+        end
+        result
+      end
+
+    private
+
+      attr_accessor :head, :tail
+
+      def find_by_value(value)
+        return nil if head.nil?
+        prior = head
+        target = prior
+        while not target.match_by_value(value)
+          prior = target
+          target = prior.next
+          @current = target if target
+        end
+        target
+      end
+
+      def find_by_index(index)
+        return nil if head.nil? or index < 1 or index > size
+        node = head
+        node = node.next while ((index -= 1) > 0 and node.next)
+        @current = node if node
+        node
+      end
+
+    end # end class
+  end # module
+end # end module

data/lib/skn_utils/lists/doubly_linked_list.rb

@@ -0,0 +1,215 @@
+
+module SknUtils
+  module Lists
+    # Doubly Linked List
+    # Forward (#next) and Backwards (#prev) navigation
+    # Head when (prev == nil)
+    # Tail when (next == nil)
+    class DoublyLinkedList
+      attr_accessor :size
+
+      def initialize(*values)
+        @current = nil
+        @head = nil
+        @tail = nil
+        @size = 0
+        values.each {|value| insert(value) }
+      end
+
+      #
+      # Navigation
+      #
+
+      # return values and position current to last node accessed
+      # prevent @current from nil assignment
+      def first
+        @current = head if head
+        @current.value rescue nil
+      end
+
+      def next
+        @current = @current.next if @current and @current.next
+        @current.value rescue nil
+      end
+
+      def current
+        @current.value rescue nil
+      end
+
+      def prev
+        @current = @current.prev if @current and @current.prev
+        @current.value rescue nil
+      end
+
+      def last
+        @current = tail if tail
+        @current.value rescue nil
+      end
+
+      # -+ int position from current node
+      def nth(index)
+        node = @current
+        if index > 0
+          while index > 1 and node and node.next
+            node = node.next
+            index -= 1
+          end
+          @current = node
+        elsif index < 0
+          while index < 0 and node and node.prev
+            node = node.prev
+            index += 1
+          end
+          @current = node
+        end
+        current
+      end
+
+      # return node at positive index from head
+      def at_index(index)
+        find_by_index(index)
+        current
+      end
+
+      def empty?
+        size == 0
+      end
+
+      #
+      # Modifications
+      #
+
+      # return new size
+      def insert(value)
+        temp = @current.value rescue nil
+        insert_after(temp, value)
+      end
+
+      # return new size
+      def prepend(value)
+        temp = head.value rescue nil
+        insert_before(temp, value)
+      end
+      # return new size
+      def append(value)
+        temp = tail.value rescue nil
+        insert_after(temp, value)
+      end
+
+      # return new size
+      def insert_before(position_value, value)
+        target = find_by_value(position_value)
+        node = LinkNode.new(value, target, :before)
+        @current = node if target
+        self.head = node if head === target
+        self.tail = node if tail.nil?
+        self.size += 1
+      end
+
+      # return new size
+      def insert_after(position_value, value)
+        target = find_by_value(position_value)
+        node = LinkNode.new(value, target, :after)
+        @current = node
+        self.head = node if head.nil?
+        self.tail = node if tail === target
+        self.size += 1
+      end
+
+      # return remaining size
+      def remove(value)
+        target_node = find_by_value(value)
+        if target_node
+          @current = target_node.prev if target_node.prev
+          @current.next = target_node.next if target_node.next
+          @current.next.prev = @current if @current and @current.next and @current.next.prev
+          target_node.remove!
+        end
+        self.tail = @current if tail === target_node
+        self.head = @current if head === target_node
+        self.size -= 1
+      end
+
+      # return number cleared
+      def clear
+        rc = 0
+        node = head
+        position = head
+        while node do
+          node = node.remove!
+          rc += 1
+          break if position === node
+        end
+
+        @current = nil
+        self.head = nil
+        self.tail = nil
+        self.size = 0
+        rc
+      end
+
+      #
+      # Enumerate
+      #
+
+      # perform each() or return enumerator
+      def each(&block)
+        @current = head
+        position = head
+        if block_given?
+          while position do
+            yield position.value.dup
+            position = position.next
+            break if position === @current
+          end
+        else
+          Enumerator.new do |yielder, val|
+            while position do
+              yielder << position.value.dup
+              position = position.next
+              break if position === @current
+            end
+          end
+        end
+      end
+
+      # convert self to a value array
+      def to_a
+        @current = head
+        position = head
+        result = []
+        while position do
+          result << position.value.dup
+          position = position.next
+          break if position === @current
+        end
+        result
+      end
+
+    private
+
+      attr_accessor :head, :tail
+
+      def find_by_value(value)
+        return nil if head.nil?
+        prior = head
+        target = prior
+        while not target.match_by_value(value)
+          prior = target
+          target = prior.next
+          @current = target if target
+        end
+        target
+      end
+
+      def find_by_index(index)
+        return nil if head.nil? or index < 1 or index > size
+        node = head
+        node = node.next while ((index -= 1) > 0 and node.next)
+        @current = node if node
+        node
+      end
+
+    end # end class
+  end # module
+end # end module

data/lib/skn_utils/lists/link_node.rb

@@ -0,0 +1,59 @@
+##
+#
+##
+
+module SknUtils
+  module Lists
+
+    class LinkNode
+      attr_accessor :prev, :next, :value
+
+      def initialize(val, anchor_node=nil, strategy=:after)
+        @value = val
+        @prev = nil
+        @next = nil
+
+        case strategy
+          when :single # after logic
+            anchor_node.next = self if anchor_node
+          when :before
+            @prev = anchor_node.prev if anchor_node
+            @next = anchor_node
+            anchor_node.prev = self if anchor_node
+          when :after
+            @prev = anchor_node
+            @next = anchor_node.next if anchor_node
+            anchor_node.next = self if anchor_node
+            @next.prev = self if @next
+          when :circle_before
+            @prev = anchor_node ? anchor_node.prev : self
+            @next = anchor_node ? anchor_node : self
+            anchor_node.prev = self if anchor_node
+            @prev.next = self if anchor_node
+          when :circle_after
+            @prev = anchor_node ? anchor_node : self
+            @next = anchor_node ? anchor_node.next : self
+            anchor_node.next = self if anchor_node
+            @next.prev = self if anchor_node
+        end
+      end
+
+      def match_by_value(other_value)
+        self.value === other_value
+      end
+
+      # returns next node
+      def remove!
+        next_node = @next
+        @value = nil
+        @prev = nil
+        @next = nil
+        next_node
+      end
+
+      def to_s
+        "Node with value: #{@value}"
+      end
+    end
+  end # module
+end