xqsr3 0.32.3 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5362a61770df81001025713c2465c5ed9bea6a49
-  data.tar.gz: 70f643bccc5e09b76acf3a4944e02dbe0e763d6a
+  metadata.gz: '048dfbb7beeff5b7e90df73f59be96e686611f91'
+  data.tar.gz: 815facf131a846b49eec30be5e45bf369383d52d
 SHA512:
-  metadata.gz: 8cc83e03876a54224a4f4a28ea3ebf4ff289b2a4f8b11d1c727c41716a3ef68e670d10dd0f796d5b3273124b9308a0e4701fae02a030856f1183a2dafae3b2cb
-  data.tar.gz: 3b12d249383fddfde861575e9ed42a329220aba5b47f22204afdf0b5a3317290460004071e3c2d3a4c9590231b5eb61a01c38e1ca6f093ed2cd696ea7095469f
+  metadata.gz: e77733d055c75114bcd38811e5af5f89726c563976d49b8d197246309ac6a2c92ade6cf66e812f81a02b17f682f530b870441fc9f8436b499179dee2165d539c
+  data.tar.gz: 38743b47b07c1b1876d680a759e6c9ec3e9aac7ef6482305a2dbe452fa5d1f28e0bb3b5921653778feb94b76a8f884f90eb03dbae7bad9dd6d5815fad9902308

data/lib/xqsr3/all_extensions.rb

@@ -0,0 +1,6 @@
+
+require File.join(File.dirname(__FILE__), 'extensions')
+
+require File.join(File.dirname(__FILE__), 'extensions', 'test', 'unit')
+
+

data/lib/xqsr3/array_utilities.rb

@@ -0,0 +1,10 @@
+
+%w{
+
+	join_with_or
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'array_utilities', name)
+end
+
+

data/lib/xqsr3/command_line_utilities.rb

@@ -0,0 +1,10 @@
+
+%w{
+
+	map_option_string
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'command_line_utilities', name)
+end
+
+

data/lib/xqsr3/command_line_utilities/map_option_string.rb

@@ -6,7 +6,7 @@
 #               ::Xqsr3::CommandLineUtilities::MapOptionString module
 #
 # Created:      15th April 2016
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -69,7 +69,8 @@ module MapOptionString
 	end
 
 	private
-	module MapOptionString_Helper_ # :nodoc:
+	# @!visibility private
+	module MapOptionString_Helper_ # :nodoc: all
 
 		def self.map_option_string_with_options_ s, option_strings, options
 

data/lib/xqsr3/containers.rb

@@ -0,0 +1,11 @@
+
+%w{
+
+	frequency_map
+	multi_map
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'containers', name)
+end
+
+

data/lib/xqsr3/containers/frequency_map.rb

@@ -5,7 +5,7 @@
 # Purpose:      FrequencyMap container
 #
 # Created:      28th January 2005
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -77,6 +77,7 @@ class FrequencyMap
 	#    fm[:z]    # => 0
 	ByElement = Class.new do
 
+		# Create an instance of Xqsr3::FrequencyMap from an array
 		def self.[] *args
 
 			fm = FrequencyMap.new
@@ -180,12 +181,16 @@ class FrequencyMap
 
 		case	rhs
 		when	::NilClass
+
 			return false
 		when	::Hash
+
 			return rhs.size == @elements.size && rhs == @elements
 		when	self.class
+
 			return rhs.count == self.count && rhs == @elements
 		else
+
 			raise TypeError, "can compare #{self.class} only to instances of #{self.class} and #{::Hash}, but #{rhs.class} given"
 		end
 
@@ -407,6 +412,12 @@ class FrequencyMap
 
 	# Returns +true+ if an element with a count of the given +value+ is in the
 	# map; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +value+ (Integer) The value of the count for which to search
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +value+ is not an Integer
 	def has_value? value
 
 		case	value
@@ -437,6 +448,8 @@ class FrequencyMap
 #
 #		@elements.keep_if
 #	end
+=begin
+=end
 
 	# Returns the element that has the given count, or +nil+ if none found
 	#
@@ -540,6 +553,8 @@ class FrequencyMap
 		self
 	end
 
+	# Removes a key-value pair from the instance and return as a two-item
+	# array
 	def shift
 
 		r = @elements.shift
@@ -589,11 +604,13 @@ class FrequencyMap
 		@elements.to_hash
 	end
 
+	# A string-form of the instance
 	def to_s
 
 		@elements.to_s
 	end
 
+	# An array of all frequencies (without element keys) in the instance
 	def values
 
 		@elements.values

data/lib/xqsr3/containers/multi_map.rb

@@ -5,7 +5,7 @@
 # Purpose:      multimap container
 #
 # Created:      21st March 2007
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -73,16 +73,16 @@ class MultiMap < ::Hash
 				return self.new
 			when	::Hash
 
-				fm = self.new
+				mm = self.new
 
 				arg.each do |k, v|
 
 					raise ArgumentError, "mapped elements in hashes must be arrays, #{v.class} given" unless v.kind_of? ::Array
 
-					fm.store k, *v
+					mm.store k, *v
 				end
 
-				return fm
+				return mm
 			when	::Array
 
 				# accepted forms:
@@ -133,6 +133,8 @@ class MultiMap < ::Hash
 	# Initialises an instance
 	def initialize
 
+		@merge_is_multi = true
+
 		@inner	=	Hash.new
 	end
 
@@ -143,6 +145,16 @@ class MultiMap < ::Hash
 		return @inner[key]
 	end
 
+	# Adds/assigns a new key+values pair. Equivalent to
+	#
+	#   store(key, *values)
+	#
+	# * *Parameters:*
+	#   - +key+ The element key
+	#   - +values+ (Array) The values to be associated with the key
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +values+ is not an array
 	def []= key, values
 
 		values = [] if values.nil?
@@ -203,9 +215,17 @@ class MultiMap < ::Hash
 		@inner.delete key
 	end
 
+	# Calls _block_ once for each key-value pair, passing the key and each
+	# of its values in turn. If the values for a given key are empty and
+	# +defaults+ is not empty, the block is invoked for that key (with
+	# +defaults[0]+) once
+	#
+	# * *Exceptions:*
+	#   - +ArgumentError+ if more than 1 +defaults+ is provided, or no block is given
 	def each *defaults
 
 		raise ArgumentError, "may only supply 0 or 1 defaults" if defaults.size > 1
+		raise ArgumentError, 'block is required' unless block_given?
 
 		@inner.each do |key, values|
 
@@ -220,8 +240,8 @@ class MultiMap < ::Hash
 		end
 	end
 
-	# Calls _block_ once for each element in the instance, passing the
-	# key. If no block is provided, an enumerator is returned
+	# Calls _block_ once for each key in the instance, passing the key. If no
+	# block is provided, an enumerator is returned
 	def each_key
 
 		return @inner.each_key unless block_given?
@@ -229,26 +249,46 @@ class MultiMap < ::Hash
 		@inner.each_key { |key| yield key }
 	end
 
+	# Calls _block_ once for each key-values pair, passing the key and its
+	# values array. If no block is provided, an enumerator is returned
 	def each_unflattened
 
+		return @inner.each unless block_given?
+
 		@inner.each { |key, value| yield key, value }
 	end
 
+	# Calls _block_ once for each key-values pair, passing the key and its
+	# values array and a key index. If no block is provided, an enumerator
+	# is returned
 	def each_unflattened_with_index
 
+		return @inner.each_with_index unless block_given?
+
 		@inner.each_with_index { |kv, index| yield kv, index }
 	end
 
+	# Calls _block_ once for each value in the instance, passing the value.
+	# If no block is provided, an enumerator is returned
 	def each_value
 
+		return @inner.each_value unless block_given?
+
 		@inner.each do |key, values|
 
 			values.each { |value| yield value }
 		end
 	end
 
+	# Calls _block_ once for each key-values, passing the key and each of its
+	# values and a value index
+	#
+	# * *Exceptions:*
+	#   - +ArgumentError+ if no block is given
 	def each_with_index
 
+		raise ArgumentError, 'block is required' unless block_given?
+
 		index = 0
 		self.each do |key, value|
 
@@ -276,18 +316,26 @@ class MultiMap < ::Hash
 		end
 	end
 
-	def fetch key, default = nil, &block
+	# Returns the values associated with the given key
+	#
+	# * *Parameters:*
+	#   - +key+ The key
+	#   - +default+ The default value
+	def fetch key, default = (default_parameter_defaulted_ = true; nil), &block
 
-		case	default
-		when	::NilClass, ::Array
-			;
-		else
-			raise TypeError, "default parameter ('#{default}') must be of type #{::Array}, but was of type #{default.class}"
+		unless default_parameter_defaulted_
+
+			case	default
+			when	::NilClass, ::Array
+				;
+			else
+				raise TypeError, "default parameter ('#{default}') must be of type #{::Array}, but was of type #{default.class}"
+			end
 		end
 
 		unless @inner.has_key? key
 
-			return default unless default.nil?
+			return default unless default_parameter_defaulted_
 
 			if block_given?
 
@@ -349,31 +397,127 @@ class MultiMap < ::Hash
 		@inner.has_key? key
 	end
 
+	# Returns +true+ if any key has the given +value+; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +value+ The value for which to search
 	def has_value? value
 
-		@inner.has_value? value
+		@inner.each do |k, vals|
+
+			return true if vals.include? value
+		end
+
+		false
+	end
+
+	# Returns +true+ if any key has the given +values+; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +values+ (Array) The values for which to search
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +value+ is not an Array
+	def has_values? values
+
+		raise TypeError, "'values' parameter must be of type #{::Array}" unless Array === values
+
+		@inner.has_value? values
 	end
 
-	def key value
+	# Returns the key for the given value(s)
+	#
+	# * *Parameters:*
+	#   - +values+ (Array) The value(s) for which to search
+	#
+	# If a single value is specified, the entries in the instance are
+	# searched first for an exact match to all (1) value(s); if that fails,
+	# then the first key with a values containing the given value is
+	# returned
+	def key *values
+
+		case values.size
+		when 0
+
+			return nil
+		when 1
+
+			i = nil
+
+			@inner.each do |k, vals|
+
+				return k if vals == values
+
+				if i.nil?
+
+					i = k if vals.include? values[0]
+				end
+			end
+
+			return i
+		else
+
+			@inner.each do |key, vals|
+
+				return key if vals == values
+			end
 
-		@inner.key value
+			return nil
+		end
 	end
 
-	def merge fm
+	# The number of elements in the map
+	def length
 
-		raise TypeError, "parameter must be an instance of type #{self.class}" unless fm.instance_of? self.class
+		@inner.size
+	end
 
-		fm_new = self.class.new
+	# Returns a new instance containing a merging of the current instance and
+	# the +other+ instance
+	#
+	# NOTE: where any key is found in both merging instances the values
+	# resulting will be a concatenation of the sets of values
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def multi_merge other
 
-		fm_new.merge! self
-		fm_new.merge! fm
+		mm = self.class.new
 
-		fm_new
+		mm.merge! self
+		mm.merge! other
+
+		mm
 	end
 
-	def merge! fm
+	# Merges the contents of +other+ into the current instance
+	#
+	# NOTE: where any key is found in both merging instances the values
+	# resulting will be a concatenation of the sets of values
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def multi_merge! other
+
+		case other
+		when self.class
+
+			;
+		when ::Hash
 
-		fm.each do |k, v|
+			;
+		else
+
+			raise TypeError, "parameter must be an instance of #{self.class} or #{Hash}"
+		end
+
+		other.each do |k, v|
 
 			self.push k, v
 		end
@@ -381,6 +525,96 @@ class MultiMap < ::Hash
 		self
 	end
 
+	# Returns a new instance containing a merging of the current instance and
+	# the +other+ instance
+	#
+	# NOTE: where any key is found in both merging instances the values from
+	# +other+ will be used
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def strict_merge other
+
+		mm = self.class.new
+
+		mm.strict_merge! self
+		mm.strict_merge! other
+
+		mm
+	end
+
+	# Merges the contents of +other+ into the current instance
+	#
+	# NOTE: where any key is found in both merging instances the values from
+	# +other+ will be used
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def strict_merge! other
+
+		case other
+		when self.class
+
+			other.each_unflattened do |k, vals|
+
+				self.store k, *vals
+			end
+		when ::Hash
+
+			other.each do |k, v|
+
+				self.store k, v
+			end
+		else
+
+			raise TypeError, "parameter must be an instance of #{self.class} or #{Hash}"
+		end
+
+		self
+	end
+
+	# See #merge
+	def merge other
+
+		if @merge_is_multi
+
+			multi_merge other
+		else
+
+			strict_merge other
+		end
+	end
+
+	# See #merge!
+	def merge! other
+
+		if @merge_is_multi
+
+			multi_merge! other
+		else
+
+			strict_merge! other
+		end
+	end
+
+	# Pushes the given +key+ and +values+. If the +key+ is already in the
+	# map then the +values+ will be concatenated with those already present
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +key+ The element key
+	#   - +values+ (*Array) The value(s) to be pushed
+	#
+	# === Exceptions
+	#  - +::RangeError+ raised if the value of +count+ results in a negative count for the given element
+	#  - +::TypeError+ if +count+ is not an +::Integer+
 	def push key, *values
 
 		@inner[key] = [] unless @inner.has_key? key
@@ -388,33 +622,60 @@ class MultiMap < ::Hash
 		@inner[key].push(*values)
 	end
 
+	# Removes a key-value pair from the instance and return as a two-item
+	# array
 	def shift
 
 		@inner.shift
 	end
 
-	def size
-
-		@inner.size
-	end
+	alias size length
 
+	# Causes an element with the given +key+ and +values+ to be stored. If an
+	# element with the given +key+ already exists, its values will b
+	# replaced
 	def store key, *values
 
 		@inner[key] = values
 	end
 
+	# Converts instance to an array of +[key,value]+ pairs
 	def to_a
 
 		self.flatten
 	end
 
+	# Obtains reference to internal hash instance (which must *not* be modified)
 	def to_h
 
-		@inner.dup
+		@inner.to_h
 	end
 
+	# Obtains equivalent hash to instance
+	def to_hash
+
+		@elements.to_hash
+	end
+
+	# A string-form of the instance
+	def to_s
+
+		@inner.to_s
+	end
+
+	# An array of all values in the instance
 	def values
 
+		r	=	[]
+
+		@inner.values.each  { |vals| r += vals }
+
+		r
+	end
+
+	# An array of all sets of values in the instance
+	def values_unflattened
+
 		@inner.values
 	end
 end # class MultiMap