kxi 1.0.0

data/lib/kxi/collections/array_collection.rb

@@ -0,0 +1,107 @@
+# Created by Matyáš Pokorný on 2017-12-28.
+
+module KXI
+	module Collections
+		# Makes array enumerable
+		class ArrayCollection < KXI::Collections::Enumerable
+			# Instantiates the {KXI::Collections::ArrayCollection} class
+			# @param array [Array] Array for enumeration
+			def initialize(array = [])
+				super()
+				@arr = array
+			end
+			
+			# Creates a new {KXI::Collections::Enumerator} bound to this instance
+			# @return [KXI::Collections::Enumerator] Enumerator bound to this instance
+			def create_enumerator
+				ArrayEnumerator.new(@arr)
+			end
+			
+			# Obtains value in array at specific index
+			# @param index [Number] Index in array to obtain
+			# @return [Object] Value in array at specified index
+			# @raise [KXI::Exceptions::OutOfRangeException] Raised when given index is out of range of array
+			def [](index)
+				raise(KXI::Exceptions::OutOfRangeException.new(index)) if @arr.length == 0
+				raise(KXI::Exceptions::OutOfRangeException.new(index, 0, @arr.length - 1)) if index < 0 or index >= @arr.length
+				lock do
+					return @arr[index]
+				end
+			end
+			
+			# Sets value of array at specific index
+			# @param index [Number] Index in array to set
+			# @param value [Object] Value to set
+			# @return [Object] Set value
+			# @raise [KXI::Exceptions::OutOfRangeException] Raised when given index is out of range of array
+			# @raise [KXI::Exceptions::CollectionException] Raised when collection cannot be locked for writing
+			def []=(index, value)
+				raise(KXI::Exceptions::OutOfRangeException.new(index)) if @arr.length == 0
+				raise(KXI::Exceptions::OutOfRangeException.new(index, 0, @arr.length - 1)) if index < 0 or index >= @arr.length
+				lock(true) do
+					@arr[index] = value
+				end
+				return value
+			end
+			
+			# Adds value into array
+			# @param value [Object] Value to set
+			# @return [Number] Assigned index
+			# @raise [KXI::Exceptions::CollectionException] Raised when collection cannot be locked for writing
+			def add(value)
+				idx = @arr.length
+				lock(true) do
+					@arr.push(value)
+				end
+				return idx
+			end
+			
+			# Removes item at specific index
+			# @param index [Number] Index to remove
+			# @return [Object] Removed item
+			# @raise [KXI::Exceptions::OutOfRangeException] Raised when given index is out of range of array
+			# @raise [KXI::Exceptions::CollectionException] Raised when collection cannot be locked for writing
+			def remove_at(index)
+				raise(KXI::Exceptions::OutOfRangeException.new(index)) if @arr.length == 0
+				raise(KXI::Exceptions::OutOfRangeException.new(index, 0, @arr.length - 1)) if index < 0 or index >= @arr.length
+				ret = nil
+				lock(true) do
+					ret = @arr.delete_at(index)
+				end
+				return ret
+			end
+			
+			# Enumerates array
+			class ArrayEnumerator < KXI::Collections::Enumerator
+				# Instantiates the {KXI::Collections::ArrayCollection::ArrayEnumerator} class
+				# @param array [Array] Array for enumeration
+				def initialize(array)
+					@arr     = array
+					@current = 0
+				end
+				
+				# Selects first item in collection
+				# @return [Bool] True if collection contains elements; otherwise false
+				def rewind
+					@current = 0
+					return @arr.length > 0
+				end
+				
+				# Advances enumerator to next item
+				# @return [Bool] True if item is available; false otherwise
+				def next
+					@current = @current + 1
+					return @current < @arr.length
+				end
+				
+				# Returns current item
+				# @return [Object] Current item
+				def current
+					@arr[@current]
+				end
+			end
+			
+			private :create_enumerator
+		end
+	end
+end

data/lib/kxi/collections/enumerable.rb

@@ -0,0 +1,528 @@
+# Created by Matyáš Pokorný on 2017-12-28.
+
+module KXI
+	module Collections
+		# Allows it's superclass to be enumerated
+		# @note Order of items is not guaranteed
+		# @abstract
+		class Enumerable
+			# Instantiates the {KXI::Collections::Enumerable} class
+			def initialize
+				@locks = 0
+				@alter = false
+			end
+			
+			# Allows protected usage of {KXI::Collections::Enumerator} within bounds of block
+			# @return [nil]
+			# @yield [enumerator] Protected block of code
+			# @yieldparam enumerator [KXI::Collections::Enumerator] Enumerator bound to this instance
+			# @yieldreturn [void]
+			# @raise [KXI::Exceptions::AbstractException] When method {#create_enumerator} is not implemented in superclass
+			def enumerator
+				lock do
+					yield(create_enumerator)
+				end
+				return nil
+			end
+			
+			# Creates a new {KXI::Collections::Enumerator} bound to this instance
+			# @return [KXI::Collections::Enumerator] Enumerator bound to this instance
+			# @raise [KXI::Exceptions::AbstractException] When method is not implemented in superclass
+			# @abstract
+			def create_enumerator
+				raise(KXI::Exceptions::AbstractException.new(Enumerable))
+			end
+			
+			# Calls block with each item of collection
+			# @return [nil]
+			# @yield [item] Function that works with items of collection
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Void]
+			def foreach
+				enumerator do |e|
+					return nil unless e.rewind
+					loop do
+						yield(e.current)
+						break unless e.next
+					end
+				end
+				return nil
+			end
+			
+			# Selects specific values
+			# @return [KXI::Collections::ArrayCollection] Collection of selected values
+			# @yield [item] Function that selects values from items of collection
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Object] Selected value from item
+			def select
+				ret = []
+				foreach do |i|
+					ret.push(yield(i))
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Concatenates selected collections of items
+			# @return [KXI::Collections::ArrayCollection] Collection of selected values
+			# @yield [item] Function that selects collections of items from given items
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Array, KXI::Collections::Enumerable] Selected collection of items
+			# @raise [KXI::Exceptions::CollectionException] Raised if selection function returns object that is not of type {KXI::Collections::Enumerable} nor Array
+			def select_many
+				ret = []
+				foreach do |i|
+					col = yield(i)
+					if col.is_a?(Array)
+						col.each { |j| ret.push(j) }
+					elsif col.is_a?(Enumerable)
+						col.foreach { |j| ret.push(j) }
+					else
+						raise(KXI::Exceptions::CollectionException.new('Selection function returned invalid type of object!'))
+					end
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Selects only those items that satisfy given function
+			# @return [KXI::Collections::ArrayCollection] Collection of selected items
+			# @yield [item] Function that evaluates whether item should be selected
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Bool] True if item should be selected; otherwise false
+			def where
+				ret = []
+				foreach do |i|
+					ret.push(i) if yield(i)
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Counts items in collection
+			# @return [Number] Number of items
+			# @overload count()
+			# 	Counts the total number of items in collection
+			# 	@return [Number] Number of items in collection
+			# @overload count()
+			# 	Counts the number of items that satisfy given function
+			# 	@return [Number] Number of items that satisfy given function
+			# 	@yield [item] Function that evaluates whether item should be counted
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item should be counted; otherwise false
+			def count
+				count = 0
+				if block_given?
+					foreach do |item|
+						count = count + 1 if yield(item)
+					end
+				else
+					enumerator do |e|
+						return 0 unless e.rewind
+						count += 1
+						while e.next
+							count = count + 1
+						end
+					end
+				end
+				return count
+			end
+			
+			# Checks if collection contains any item
+			# @return [Bool] True if collection contains any item; otherwise false
+			# @overload any()
+			# 	Checks if collection is not empty
+			# 	@return [Bool] True if collection is not empty; otherwise false
+			# @overload any()
+			# 	Checks if there is any item in collection that satisfies given function
+			# 	@return [Bool] True if collection contains item that satisfies given function; otherwise false
+			# 	@yield [item] Function used for checking
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item satisfies given function; otherwise false
+			def any
+				if block_given?
+					foreach do |item|
+						return true if yield(item)
+					end
+					return false
+				else
+					enumerator do |e|
+						return false unless e.rewind
+						return true
+					end
+				end
+			end
+			
+			# Checks if all items in collection satisfy given function
+			# @return [Bool] True if all items of collection satisfy given function; otherwise false
+			# @yield [item] Function used for checking
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Bool] True if item satisfies given function; otherwise false
+			def all
+				foreach do |item|
+					return false unless yield(item)
+				end
+				return true
+			end
+			
+			# Gets first item, or default
+			# @overload first(df = nil)
+			# 	Gets first item of collection
+			# 	@param df [Object, nil] Default value
+			# 	@return [Object, nil] First item of collection; default value if collection is empty
+			# @overload first(df = nil)
+			# 	Gets first item of collection that satisfies given function
+			# 	@param df [Object, nil] Default value
+			# 	@return [Object, nil] First item of collection that satisfies given function; default value if no such item exists
+			# 	@yield [item] Function for evaluation
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item satisfies given function; false otherwise
+			def first(df = nil)
+				if block_given?
+					foreach do |item|
+						return item if yield(item)
+					end
+				else
+					enumerator do |e|
+						return e.current if e.rewind
+					end
+				end
+				return df
+			end
+			
+			
+			# Gets first item
+			# @overload first!()
+			# 	Gets first item of collection
+			# 	@return [Object, nil] First item of collection
+			# 	@raise [KXI::Exceptions::CollectionException] Raised when collection is empty
+			# @overload first!()
+			# 	Gets first item of collection that satisfies given function
+			# 	@return [Object, nil] First item of collection that satisfies given function
+			# 	@raise [KXI::Exceptions::CollectionException] Raised when collection contains no element that satisfies given function
+			# 	@yield [item] Function for evaluation
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item satisfies given function; false otherwise
+			def first!
+				if block_given?
+					foreach do |item|
+						return item if yield(item)
+					end
+				else
+					enumerator do |e|
+						return e.current if e.rewind
+					end
+				end
+				raise(KXI::Exceptions::CollectionException.new("Collection contains no #{(block_given? ? 'such ' : '')}items!"))
+			end
+			
+			# Gets last item, or default
+			# @overload last(df = nil)
+			# 	Gets last item of collection
+			# 	@param df [Object, nil] Default value
+			# 	@return [Object, nil] Last item of collection; default value if collection is empty
+			# @overload last(df = nil)
+			# 	Gets last item of collection that satisfies given function
+			# 	@param df [Object, nil] Default value
+			# 	@return [Object, nil] Last item of collection that satisfies given function; default value if no such item exists
+			# 	@yield [item] Function for evaluation
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item satisfies given function; false otherwise
+			def last(df = nil)
+				found = false
+				ret   = nil
+				if block_given?
+					foreach do |item|
+						if yield(item)
+							ret   = item
+							found = true
+						end
+					end
+				else
+					foreach do |item|
+						ret   = item
+						found = true
+					end
+				end
+				return df unless found
+				return ret
+			end
+			
+			# Gets last item
+			# @overload last!()
+			# 	Gets last item of collection
+			# 	@return [Object, nil] Last item of collection
+			# 	@raise [KXI::Exceptions::CollectionException] Raised if collection is empty
+			# @overload last!()
+			# 	Gets last item of collection that satisfies given function
+			# 	@return [Object, nil] Last item of collection that satisfies given function
+			# 	@raise [KXI::Exceptions::CollectionException] Raised when collection doesn't contain element that satisfies given function
+			# 	@yield [item] Function for evaluation
+			# 	@yieldparam item [Object] Item of collection
+			# 	@yieldreturn [Bool] True if item satisfies given function; false otherwise
+			def last!
+				found = false
+				ret   = nil
+				if block_given?
+					foreach do |item|
+						if yield(item)
+							ret   = item
+							found = true
+						end
+					end
+				else
+					foreach do |item|
+						ret   = item
+						found = true
+					end
+				end
+				raise(KXI::Exceptions::CollectionException.new("Collection contains no #{(block_given? ? 'such ' : '')}items!")) unless found
+				return ret
+			end
+			
+			# Skips given number of items and returns the rest
+			# @param count [Number] Number of items to skip
+			# @return [KXI::Collections::ArrayCollection] Collection of items that weren't skipped
+			def skip(count)
+				ret = []
+				foreach do |item|
+					if count > 0
+						count -= 1
+					else
+						ret.push(item)
+					end
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Returns first N elements
+			# @param count [Number] Number of items to take
+			# @return [KXI::Collections::ArrayCollection] Collection of first N items
+			def take(count)
+				ret = []
+				foreach do |item|
+					break unless count > 0
+					count -= 1
+					ret.push(item)
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Aggregates all items of collection
+			# @param start [Object, nil] Starting value
+			# @return [Object] Aggregated value
+			# @yield [current, item] Aggregation function
+			# @yieldparam current [Object] Current aggregate
+			# @yieldparam item [Object] Item of collection
+			# @yieldreturn [Object] Aggregated value
+			def aggregate(start = nil)
+				foreach do |item|
+					start = yield(start, item)
+				end
+				return start
+			end
+			
+			# Orders collection to ascending order
+			# @note Ordering is done using merge sort algorithm
+			# @return [KXI::Collections::ArrayCollection] Ordered collection
+			# @overload order_by()
+			# 	Orders collection using spaceship operator (<=>)
+			# 	@return [KXI::Collections::ArrayCollection] Ordered collection
+			# @overload order_by()
+			# 	Orders collection using given comparison function
+			# 	@return [KXI::Collections::ArrayCollection] Ordered collection
+			# 	@yield [what, with] Comparison function
+			# 	@yieldparam what [Object] Object that is being compared
+			# 	@yieldparam with [Object] Object that is being compared to
+			# 	@yieldreturn [Number] Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with
+			def order_by(&block)
+				block  = lambda { |a, b| a <=> b } if block == nil
+				groups = []
+				g      = []
+				foreach do |item|
+					if g.length == 0
+						g.push(item)
+					else
+						if block.call(g.last, item) <= 0
+							g.push(item)
+						else
+							groups.push(g)
+							g = [item]
+						end
+					end
+				end
+				groups.push(g) if g.length > 0
+				return KXI::Collections::ArrayCollection.new if groups.length == 0
+				while groups.length > 1
+					merges = []
+					while groups.length >= 2
+						merges.push(merge(groups.shift, groups.shift, &block))
+					end
+					merges.push(groups[0]) if groups.length > 0
+					groups = merges
+				end
+				return KXI::Collections::ArrayCollection.new(groups[0])
+			end
+			
+			# Orders collection to descending order
+			# @note Ordering is done using merge sort algorithm
+			# @return [KXI::Collections::ArrayCollection] Ordered collection
+			# @overload order_by()
+			# 	Orders collection using spaceship operator (<=>)
+			# 	@return [KXI::Collections::ArrayCollection] Ordered collection
+			# @overload order_by()
+			# 	Orders collection using given comparison function
+			# 	@return [KXI::Collections::ArrayCollection] Ordered collection
+			# 	@yield [what, with] Comparison function
+			# 	@yieldparam what [Object] Object that is being compared
+			# 	@yieldparam with [Object] Object that is being compared to
+			# 	@yieldreturn [Number] Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with
+			def order_by_descending(&block)
+				if block == nil
+					return order_by { |a, b| b <=> a }
+				else
+					return order_by { |a, b| -block.call(a, b) }
+				end
+			end
+			
+			# Selects only those items that are of at least one of specified types
+			# @param klass [Class] Types to use for selection
+			# @return [KXI::Collections::ArrayCollection] Selected items
+			# @see Object#is_a?
+			def of_type(*klass)
+				ret = []
+				foreach do |i|
+					klass.each do |k|
+						if i.is_a?(k)
+							ret.push(i)
+							break
+						end
+					end
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Selects only those items that are exactly of at least one of specified types
+			# @param klass [Class] Types to use for selection
+			# @return [KXI::Collections::ArrayCollection] Selected items
+			# @see Object#class
+			def of_type!(*klass)
+				ret = []
+				foreach do |i|
+					klass.each do |k|
+						if i.class == k
+							ret.push(i)
+							break
+						end
+					end
+				end
+				return KXI::Collections::ArrayCollection.new(ret)
+			end
+			
+			# Obtains item with the first maximal value
+			# @overload max()
+			# 	Compares items using spaceship operator (<=>)
+			# 	@return [Object] Item with first maximal value; nil if collection is empty
+			# @overload max()
+			# 	Compares items using given comparison function
+			# 	@return [Object] Item with first maximal value; nil if collection is empty
+			# 	@yield [what, with] Comparison function
+			# 	@yieldparam what [Object] Object that is being compared
+			# 	@yieldparam with [Object] Object that is being compared to
+			# 	@yieldreturn [Number] Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with
+			def max(&block)
+				block = lambda { |a, b| a <=> b } if block == nil
+				ret   = nil
+				first = true
+				foreach do |i|
+					if first
+						ret = i
+						first = false
+					elsif block.call(i, ret) > 0
+						ret = i
+					end
+				end
+				return ret
+			end
+			
+			# Obtains item with the first minimal value
+			# @overload min()
+			# 	Compares items using spaceship operator (<=>)
+			# 	@return [Object] Item with first minimal value; nil if collection is empty
+			# @overload min()
+			# 	Compares items using given comparison function
+			# 	@return [Object] Item with first minimal value; nil if collection is empty
+			# 	@yield [what, with] Comparison function
+			# 	@yieldparam what [Object] Object that is being compared
+			# 	@yieldparam with [Object] Object that is being compared to
+			# 	@yieldreturn [Number] Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with
+			def min(&block)
+				block = lambda { |a, b| a <=> b } if block == nil
+				ret   = nil
+				first = true
+				foreach do |i|
+					if first
+						ret = i
+						first = false
+					elsif block.call(i, ret) < 0
+						ret = i
+					end
+				end
+				return ret
+			end
+			
+			# Coverts collection to array
+			# @return [Array] Array equivalent to collection
+			def to_array
+				ret = []
+				foreach { |item| ret.push(item) }
+				return ret
+			end
+			
+			# Merges two arrays in order using comparison function
+			# @param a [Array] First array
+			# @param b [Array] Second array
+			# @return [Array] Merged ordered array
+			def merge(a, b, &comp)
+				ret = []
+				while a.length > 0 or b.length > 0
+					if a.length > 0 and b.length > 0
+						c = comp.call(a[0], b[0])
+						if c <= 0
+							ret.push(a.shift)
+						else
+							ret.push(b.shift)
+						end
+					else
+						ret.push(a.length > 0 ? a.shift : b.shift)
+					end
+				end
+				return ret
+			end
+			
+			# Indicates whether collection can be altered
+			# @return [Bool] True if collection can be altered; otherwise false
+			def can_alter?
+				@locks == 0 and not @alter
+			end
+			
+			def lock(write = false)
+				if write
+					raise(KXI::Exceptions::CollectionException.new('Collection cannot be locked for writing!')) unless can_alter?
+					@alter = true
+					yield
+				else
+					raise(KXI::Exceptions::CollectionException.new('Collection cannot be locked for reading!')) if @alter
+					@locks += 1
+					yield
+				end
+			ensure
+				if write
+					@alter = false
+				else
+					@locks -= 1
+				end
+			end
+			
+			protected :lock, :create_enumerator
+			private :merge
+		end
+	end
+end

data/lib/kxi/collections/enumerator.rb

@@ -0,0 +1,32 @@
+# Created by Matyáš Pokorný on 2017-12-28.
+
+module KXI
+	module Collections
+		# Allows iteration over a collection
+		# @abstract
+		class Enumerator
+			# Selects first item in collection
+			# @return [Bool] True if collection contains elements; otherwise false
+			# @abstract
+			def rewind
+				raise(KXI::Exceptions::AbstractException.new(Enumerator))
+			end
+			
+			# Advances enumerator to next item
+			# @return [Bool] True if item is available; false otherwise
+			# @raise [KXI::Exceptions::AbstractException] When method is not implemented in superclass
+			# @abstract
+			def next
+				raise(KXI::Exceptions::AbstractException.new(Enumerator))
+			end
+			
+			# Returns current item
+			# @return [Object] Current item
+			# @raise [KXI::Exceptions::AbstractException] When method is not implemented in superclass
+			# @abstract
+			def current
+				raise(KXI::Exceptions::AbstractException.new(Enumerator))
+			end
+		end
+	end
+end