xqsr3 0.31.2 → 0.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ee411febd1aacd76190a4d3032cd5a8ed0e5376
-  data.tar.gz: 4fe4ff7827e9c0aa08c2e036a02db5c1ea197601
+  metadata.gz: d08b7ea53bfd21226d79bb36506890a7868ba93b
+  data.tar.gz: c4d23e493010555d8c3cfb27c515b469a47dd29f
 SHA512:
-  metadata.gz: fbb6ff8feb168e0c7f28d1d32fccd4933dd96943c583f897a58e40a31b7bcd3cee62734e6f08a8471901f151c4a1a5cbcf8e730377f36579d42f11573d6210ed
-  data.tar.gz: 567578a5041f37710becf55c78857526e88e0c7720c9c8be3fe82c7da366a57521b1d2642e5c31443d676e9261695a8d1b2d2599496a927772c7bc56ac7d5d54
+  metadata.gz: 34a1d293c2de8559801ec22e038a4e7fc33a7d6da5901411d84f1aa6ca67cd22295f690ecc501b166e9aa8777f5b00408473b467782ff129ebade29e0a0e15e0
+  data.tar.gz: 9e9a153905629a84437e69ea297ca7bbc843542a3ab90b35997d1e79d816ded0d90d2c2e8381c9db13ca6ffe6a4a8ae0691c2db5a7b4478a58efef4dc2e52ee4

data/LICENSE

@@ -1,6 +1,6 @@
 xqsr3
 
-Copyright (c) 2005-2016, Matthew Wilson and Synesis Software
+Copyright (c) 2005-2019, Matthew Wilson and Synesis Software
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -27,3 +27,4 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.md

@@ -20,7 +20,29 @@ It may be pronounced (lamely) as "excusers".
 
 ## Installation
 
-Install using `gem install xqsr3` or add it to your `Gemfile`.
+Install via **gem** as in:
+
+```
+	gem install libclimate-ruby
+```
+
+or add it to your `Gemfile`.
+
+Use is via specific APIs or groups. For example, in order to use the
+``FrequencyMap`` class you would ``require`` the source file, as in:
+
+```Ruby
+require 'xqsr3/containers/frequency_map'
+```
+
+Alternatively, to use all **test/unit** extensions you would ``require`` all
+relatived via the file:
+
+```Ruby
+require 'xqsr3/extensions/test/unit'
+```
+
+which brings in nine extensions.
 
 ## Components
 
@@ -49,6 +71,10 @@ and extensions to the following standard library components:
 * String extensions
 * test/unit extensions
 
+## Examples
+
+Examples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
+
 ## Project Information
 
 ### Where to get help
@@ -61,17 +87,20 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 
 ### Related projects
 
-**xqsr3** is a runtime dependency in:
+**xqsr3** is a runtime dependency of:
 
 * the **[libCLImate.Ruby](https://github.com/synesissoftware/libCLImate.Ruby)** library;
 * the [**xqsr3-xml**](https://github.com/synesissoftware.com/xqsr3-xml/) library.
 
-and a development dependency in:
+and a development dependency of:
 
 * the **[CLASP.Ruby](https://github.com/synesissoftware/CLASP.Ruby)** library;
 * the **[cmpfs.Ruby](https://github.com/synesissoftware/cmpfs.Ruby)** library;
+* the **[libpath.Ruby](https://github.com/synesissoftware/libpath.Ruby)** library;
 * the **[Pantheios.Ruby](https://github.com/synesissoftware/Pantheios.Ruby)** library.
+* the **[Quench.Ruby](https://github.com/synesissoftware/Quench.Ruby)** library.
 
 ### License
 
 **xqsr3** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.
+

data/examples/count_word_frequencies.md

@@ -0,0 +1,82 @@
+# xqsr3 Example - **count_word_frequencies**
+
+## Summary
+
+Simple example illustrating use of ``FrequencyMap`` class.
+
+## Source
+
+```ruby
+
+#!/usr/bin/env ruby
+
+# examples/count_word_frequencies.rb
+
+require 'xqsr3/containers/frequency_map'
+
+include Xqsr3::Containers
+
+puts "Analyse DATA words via FrequencyMap"
+puts
+
+data = DATA.read
+data = data.gsub(/\n/, ' ')
+words = data.split
+
+
+puts "1. Manually (showing items with 2+ occurrences):"
+
+fm = FrequencyMap.new
+
+words.each { |word| fm << word }
+
+fm.each_by_frequency do |word, frequency|
+
+	next if 1 == frequency
+
+	$stdout.puts "\t#{word}\t#{frequency}"
+end
+puts
+
+
+puts "2. Via ByElement (showing items with 2+ occurrences):"
+
+fm = FrequencyMap::ByElement[*words]
+
+fm.each_by_frequency do |word, frequency|
+
+	next if 1 == frequency
+
+	$stdout.puts "\t#{word}\t#{frequency}"
+end
+puts
+
+
+
+__END__
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+```
+
+The code is pretty self-explanatory. I've grabbed some **Lorem Ipsum** and placed into an ``__END__`` section, which is then read (via ``DATA``) and ``split`` into ``words``. These words are then pushed into ``FrequencyMap`` instances in two ways: manually; and via ``FrequencyMap::ByElement``. Each list is written out, omitting single occurrences, inside an ``each_by_frequency`` loop.
+
+## Usage
+
+When run, this produces the following output:
+
+```
+Analyse DATA words via FrequencyMap
+
+1. Manually (showing items with 2+ occurrences):
+	in	3
+	dolor	2
+	dolore	2
+	ut	2
+
+2. Via ByElement (showing items with 2+ occurrences):
+	in	3
+	dolor	2
+	dolore	2
+	ut	2
+```
+
+

data/examples/count_word_frequencies.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+# examples/count_word_frequencies.rb
+
+require 'xqsr3/containers/frequency_map'
+
+include Xqsr3::Containers
+
+
+puts "Analyse DATA words via FrequencyMap"
+puts
+
+data = DATA.read
+data = data.gsub(/\n/, ' ')
+words = data.split
+
+
+puts "1. Manually (showing items with 2+ occurrences):"
+
+fm = FrequencyMap.new
+
+words.each { |word| fm << word }
+
+fm.each_by_frequency do |word, frequency|
+
+	next if 1 == frequency
+
+	$stdout.puts "\t#{word}\t#{frequency}"
+end
+puts
+
+
+puts "2. Via ByElement (showing items with 2+ occurrences):"
+
+fm = FrequencyMap::ByElement[*words]
+
+fm.each_by_frequency do |word, frequency|
+
+	next if 1 == frequency
+
+	$stdout.puts "\t#{word}\t#{frequency}"
+end
+puts
+
+
+
+__END__
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+

data/lib/xqsr3/array_utilities/join_with_or.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      7th December 2017
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -64,7 +64,7 @@ module JoinWithOr
 	#
 	# === Signature
 	#
-	# * *Parameters*
+	# * *Parameters:*
 	#
 	# * *Required parameters*:
 	#   - +ar+:: [Array] The array whose contents are to be joined
@@ -73,7 +73,7 @@ module JoinWithOr
 	#   - +options+:: [Hash] Options that control the behaviour of the
 	#       method
 	#
-	# * *Options*:
+	# * *Options:*
 	#
 	#   - +:or+:: [String] A string that is used instead of 'or'
 	#   - +:oxford_comma+:: [boolean] Determines whether an Oxford comma

data/lib/xqsr3/containers/frequency_map.rb

@@ -5,13 +5,13 @@
 # Purpose:      FrequencyMap container
 #
 # Created:      28th January 2005
-# Updated:      13th October 2018
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2005-2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2005-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -44,8 +44,7 @@
 # ######################################################################## #
 
 
-# ##########################################################
-# ::Xqsr3::Containers::FrequencyMap
+require 'xqsr3/diagnostics/inspect_builder'
 
 =begin
 =end
@@ -53,10 +52,29 @@
 module Xqsr3
 module Containers
 
+# Hash-like class that counts, as the map's values, the frequencies of
+# elements, as the map's keys
 class FrequencyMap
 
 	include Enumerable
+	include ::Xqsr3::Diagnostics::InspectBuilder
 
+	# Class that provides a Hash[]-like syntax as follows:
+	#
+	#    fm = FrequencyMap::ByElement[ 'abc', 'def', 'abc', :x, 'x', :y ]
+	#
+	#    fm.empty? # => false
+	#    fm.size   # => 5
+	#    fm.count  # => 6
+	#    fm['abc'] # => 2
+	#    fm['def'] # => 1
+	#    fm['ghi'] # => 0
+	#    fm['x']   # => 1
+	#    fm['y']   # => 0
+	#    fm['z']   # => 0
+	#    fm[:x]    # => 1
+	#    fm[:y]    # => 1
+	#    fm[:z]    # => 0
 	ByElement = Class.new do
 
 		def self.[] *args
@@ -71,6 +89,7 @@ class FrequencyMap
 		private_class_method :new
 	end
 
+	# Creates an instance from the given arguments
 	def self.[] *args
 
 		return self.new if 0 == args.length
@@ -134,26 +153,38 @@ class FrequencyMap
 		end
 	end
 
+	# Initialises an instance
 	def initialize
 
-		@counts	=   {}
+		@elements	=   {}
 		@count	=	0
 	end
 
+	# Pushes an element into the map, assigning it an initial count of 1
+	#
+	# * *Parameters:*
+	#   - +key+:: The element to insert
 	def << key
 
 		push key, 1
 	end
 
+	# Compares the instance for equality against +rhs+
+	#
+	# * *Parameters:*
+	#   - +rhs+ (+nil+, +::Hash+, +FrequencyMap+) The instance to compare against
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +rhs+ is not of the required type(s)
 	def == rhs
 
 		case	rhs
 		when	::NilClass
 			return false
 		when	::Hash
-			return rhs.size == @counts.size && rhs == @counts
+			return rhs.size == @elements.size && rhs == @elements
 		when	self.class
-			return rhs.count == self.count && rhs == @counts
+			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
@@ -161,24 +192,41 @@ class FrequencyMap
 		false
 	end
 
+	# Obtains the count for a given key, or +nil+ if the key does not exist
+	#
+	# * *Parameters:*
+	#   - +key+ The key to lookup
 	def [] key
 
-		@counts[key]
+		@elements[key] || 0
 	end
 
+	# Assigns a key and a count
+	#
+	# * *Parameters:*
+	#   - +key+ The key to lookup
+	#   - +count+ (::Integer) The count to lookup
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +count+ is not an +::Integer+
 	def []= key, count
 
+		raise TypeError, "'count' parameter must be of type #{::Integer}, but was of type #{count.class}" unless Integer === count
+
 		store key, count
 	end
 
+	# Searches the instance comparing each element with +key+, returning the
+	# count if found, or +nil+ if not
 	def assoc key
 
-		@counts.assoc key
+		@elements.assoc key
 	end
 
+	# Removes all elements from the instance
 	def clear
 
-		@counts.clear
+		@elements.clear
 		@count = 0
 	end
 
@@ -188,18 +236,24 @@ class FrequencyMap
 		@count
 	end
 
+	# Obtains the default value of the instance, which will always be +nil+
 	def default
 
-		@counts.default
+		@elements.default
 	end
 
+	# Deletes the element with the given +key+ and its counts
+	#
+	# * *Parameters:*
+	#   - +key+ The key to delete
 	def delete key
 
-		key_count = @counts.delete key
+		key_count = @elements.delete key
 
 		@count -= key_count if key_count
 	end
 
+	# Duplicates the instance
 	def dup
 
 		fm = self.class.new
@@ -207,9 +261,14 @@ class FrequencyMap
 		fm.merge! self
 	end
 
+	# Calls _block_ once for each element in the instance, passing the element
+	# and its frequency as parameters. If no block is provided, an enumerator
+	# is returned
 	def each
 
-		@counts.each do |k, v|
+		return @elements.each unless block_given?
+
+		@elements.each do |k, v|
 
 			yield k, v
 		end
@@ -221,9 +280,9 @@ class FrequencyMap
 	# keys must be created and sorted from which enumeration is directed
 	def each_by_key
 
-		@counts.keys.sort.each do |key|
+		@elements.keys.sort.each do |key|
 
-			yield key, @counts[key]
+			yield key, @elements[key]
 		end
 	end
 
@@ -235,7 +294,7 @@ class FrequencyMap
 	def each_by_frequency
 
 		tm = {}
-		@counts.each do |element, frequency|
+		@elements.each do |element, frequency|
 
 			tm[frequency]	=	[]	unless tm.has_key?(frequency)
 
@@ -253,8 +312,12 @@ class FrequencyMap
 		end
 	end
 
+	# Calls _block_ once for each element in the instance, passing the
+	# element. If no block is provided, an enumerator is returned
 	def each_key
 
+		return @elements.each_key unless block_given?
+
 		keys.each do |element|
 
 			yield element
@@ -263,19 +326,26 @@ class FrequencyMap
 
 	alias each_pair each
 
+	# Calls _block_ once for each element in the instance, passing the
+	# count. If no block is provided, an enumerator is returned
 	def each_value
 
+		return @elements.each_value unless block_given?
+
 		keys.each do |element|
 
-			yield @counts[element]
+			yield @elements[element]
 		end
 	end
 
+	# Returns +true+ if instance contains no elements; +false+ otherwise
 	def empty?
 
 		0 == size
 	end
 
+	# Returns +true+ if +rhs+ is an instance of +FrequencyMap+ and contains
+	# the same elements and their counts; +false+ otherwise
 	def eql? rhs
 
 		case	rhs
@@ -286,6 +356,11 @@ class FrequencyMap
 		end
 	end
 
+	# Returns the count from the instance for the given element +key+. If
+	# +key+ cannot be found, there are several options: with no other
+	# arguments, it will raise a +::KeyError+ exception; if +default+ is
+	# given, then that will be returned; if the optional code block is
+	# specified, then that will be run and its result returned
 	def fetch key, default = nil, &block
 
 		case	default
@@ -295,7 +370,7 @@ class FrequencyMap
 			raise TypeError, "default parameter ('#{default}') must be of type #{::Integer}, but was of type #{default.class}"
 		end
 
-		unless @counts.has_key? key
+		unless @elements.has_key? key
 
 			return default unless default.nil?
 
@@ -314,19 +389,24 @@ class FrequencyMap
 			raise KeyError, "given key '#{key}' (#{key.class}) does not exist"
 		end
 
-		@counts[key]
+		@elements[key]
 	end
 
+	# Returns the equivalent flattened form of the instance
 	def flatten
 
-		@counts.flatten
+		@elements.flatten
 	end
 
+	# Returns +true+ if an element with the given +key+ is in the map; +false+
+	# otherwise
 	def has_key? key
 
-		@counts.has_key? key
+		@elements.has_key? key
 	end
 
+	# Returns +true+ if an element with a count of the given +value+ is in the
+	# map; +false+ otherwise
 	def has_value? value
 
 		case	value
@@ -336,52 +416,63 @@ class FrequencyMap
 			raise TypeError, "parameter ('#{value}') must be of type #{::Integer}, but was of type #{value.class}"
 		end
 
-		@counts.has_value? value
+		@elements.has_value? value
 	end
 
+	# A hash-code for this instance
 	def hash
 
-		@counts.hash
+		@elements.hash
 	end
 
 	alias include? has_key?
 
+	# A diagnostics string form of the instance
 	def inspect
 
-		@counts.inspect
+		make_inspect show_fields: true
 	end
 
 #	def keep_if
 #
-#		@counts.keep_if
+#		@elements.keep_if
 #	end
 
-	def key value
+	# Returns the element that has the given count, or +nil+ if none found
+	#
+	# * *Parameters:*
+	#   - +count+ (::Integer) The count to lookup
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +count+ is not of the required type(s)
+	def key count
 
-		case	value
-		when	::NilClass, ::Integer
-			;
-		else
-			raise TypeError, "parameter ('#{value}') must be of type #{::Integer}, but was of type #{value.class}"
-		end
+		raise TypeError, "'count' parameter must be of type #{::Integer}, but was of type #{count.class}" unless Integer === count
 
-		@counts.key value
+		@elements.key count
 	end
 
 	alias key? has_key?
 
+	# An array of the elements only
 	def keys
 
-		@counts.keys
+		@elements.keys
 	end
 
+	# The number of elements in the map
 	def length
 
-		@counts.length
+		@elements.length
 	end
 
 	alias member? has_key?
 
+	# Returns a new instance containing a merging of the current instance and
+	# the +fm+ instance
+	#
+	# NOTE: where any element is found in both merging instances the count
+	# will be a combination of the two counts
 	def merge fm
 
 		raise TypeError, "parameter must be an instance of type #{self.class}" unless fm.instance_of? self.class
@@ -394,16 +485,20 @@ class FrequencyMap
 		fm_new
 	end
 
+	# Merges the contents of +fm+ into the current instance
+	#
+	# NOTE: where any element is found in both merging instances the count
+	# will be a combination of the two counts
 	def merge! fm
 
 		fm.each do |k, v|
 
-			if not @counts.has_key? k
+			if not @elements.has_key? k
 
-				@counts[k]	=	v
+				@elements[k]	=	v
 			else
 
-				@counts[k]	+=	v
+				@elements[k]	+=	v
 			end
 			@count += v
 		end
@@ -411,16 +506,34 @@ class FrequencyMap
 		self
 	end
 
-	def push element, count = 1
+	# Pushes the +element+ and +count+. If the +element+ already exists,
+	# +count+ will be added to the existing count; otherwise it will be
+	# +count+
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +key+ The element key
+	#   - +count+ (Integer) The count by which to adjust
+	#
+	# === 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, count = 1
+
+		raise TypeError, "'count' parameter must be of type #{::Integer}, but was of type #{count.class}" unless Integer === count
+
+		initial_count	=	@elements[key] || 0
+		resulting_count	=	initial_count + count
 
-		raise TypeError, "count ('#{count}') must in an instance of #{::Integer}, but #{count.class} provided" unless count.kind_of? ::Integer
+		raise RangeError, "count for element '#{key}' cannot be made negative" if resulting_count < 0
 
-		if not @counts.has_key? element
+		if 0 == resulting_count
 
-			@counts[element]	=	count
+			@elements.delete key
 		else
 
-			@counts[element]	+=	count
+			@elements[key] = resulting_count
 		end
 		@count += count
 
@@ -429,7 +542,7 @@ class FrequencyMap
 
 	def shift
 
-		r = @counts.shift
+		r = @elements.shift
 
 		@count -= r[1] if ::Array === r
 
@@ -438,42 +551,52 @@ class FrequencyMap
 
 	alias size length
 
-	def store key, value
+	# Causes an element with the given +key+ and +count+ to be stored. If an
+	# element with the given +key+ already exists, its count will be adjusted,
+	# as will the total count
+	#
+	# === Return
+	#  +true+ if the element was inserted; +false+ if the element was
+	#  overwritten
+	def store key, count
 
-		case	value
-		when	::NilClass, ::Integer
-			;
-		else
-			raise TypeError, "value ('#{value}') must be of type #{::Integer}, but was of type #{value.class}"
-		end
+		raise TypeError, "'count' parameter must be of type #{::Integer}, but was of type #{count.class}" unless Integer === count
+
+		old_count = @elements[key] || 0
 
-		key_count = @counts[key] || 0
+		@elements.store key, count
 
-		@counts.store key, value
+		@count += count - old_count
 
-		@count += value - key_count
+		old_count == 0
 	end
 
+	# Converts instance to an array of +[key,value]+ pairs
 	def to_a
 
-		@counts.to_a
+		@elements.to_a
 	end
 
+	# Obtains reference to internal hash instance (which must *not* be modified)
 	def to_h
 
-		@counts.to_h
+		@elements.to_h
 	end
 
+	# Obtains equivalent hash to instance
 	def to_hash
 
-		@counts.to_hash
+		@elements.to_hash
 	end
 
-	alias to_s inspect
+	def to_s
+
+		@elements.to_s
+	end
 
 	def values
 
-		@counts.values
+		@elements.values
 	end
 end # class FrequencyMap
 

data/lib/xqsr3/containers/multi_map.rb

@@ -5,13 +5,13 @@
 # Purpose:      multimap container
 #
 # Created:      21st March 2007
-# Updated:      30th July 2017
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -202,6 +202,8 @@ class MultiMap < ::Hash
 
 	def each_key
 
+		return @inner.each_key unless block_given?
+
 		@inner.each_key { |key| yield key }
 	end
 

data/lib/xqsr3/conversion/bool_parser.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      28th July 2017
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -77,10 +77,10 @@ module BoolParser
 	#
 	# === Signature
 	#
-	# * *Parameters*:
+	# * *Parameters:*
 	#   - +options+:: An options hash, containing any of the following options
 	#
-	# * *Options*:
+	# * *Options:*
 	#   - +:false_values+:: [::Array] An array of strings or regular
 	#     expressions against which to match for false value. Defaults to
 	#     +DEFAULT_FALSE_VALUES+

data/lib/xqsr3/conversion/integer_parser.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      21st November 2017
-# Updated:      1st August 2018
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -155,7 +155,7 @@ module IntegerParser
 	#
 	# === Signature
 	#
-	# * *Parameters*:
+	# * *Parameters:*
 	#   - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
 	#   - +base+:: A value of 0, or between 2 and 36. Defaults to 0
 	#   - +options+:: An options hash, containing any of the following
@@ -166,7 +166,7 @@ module IntegerParser
 	#     take additional action. If the block returns then its return value
 	#     will be returned to the caller
 	#
-	# * *Options*:
+	# * *Options:*
 	#   - +:default+:: A default value to be used when +arg+ is +nil+ or
 	#     cannot be converted by (the original) +Kernel#Integer+
 	#   - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be

data/lib/xqsr3/extensions/enumerable/unique.rb

@@ -5,13 +5,13 @@
 # Purpose:	    Adds a unique() method to the Enumerable module
 #
 # Created:	    5th March 2007
-# Updated:	    4th April 2016
+# Updated:	    12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -55,6 +55,9 @@ module Enumerable
 	# Removes all duplicate elements in a sequence subject to an optional
 	# two-parameter block in order to return an array containing unique
 	# elements
+	#
+	#  [ 1, 2, 3 ].unique # => [ 1, 2, 3 ]
+	#  [ 1, 2, 1, 3 ].unique # => [ 1, 2, 3 ]
 	def unique(&block)
 
 		if not block
@@ -62,38 +65,25 @@ module Enumerable
 			return unique { |a, b| a == b }
 		else
 
-			if block.arity != 2
-
-				raise ArgumentError, "block requires two parameters"
-			end
+			raise ArgumentError, "block requires two parameters" unless block.arity == 2
 
 			ar	=	self.to_a
 
 			return ar if ar.length < 2
 
-			ar	=	ar.clone
-
-			i	=	0
-
-			while i < ar.length do
+			r	=	[]
+			h	=	{}
 
-				j = i + 1
+			ar.each do |v|
 
-				while j < ar.length do
+				unless h.has_key?(v)
 
-					if yield ar[i], ar[j]
-
-						ar.delete_at(j)
-					else
-
-						j = j + 1
-					end
+					r << v
+					h[v] = nil
 				end
-
-				i = i + 1
 			end
 
-			return ar
+			return r
 		end
 	end
 end # module Enumerable

data/lib/xqsr3/extensions/kernel/integer.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a Integer 'overload' to the Kernel module
 #
 # Created:      21st November 2017
-# Updated:      18th May 2018
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -60,7 +60,7 @@ module Kernel
 	#
 	# === Signature
 	#
-	# * *Parameters*:
+	# * *Parameters:*
 	#   - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
 	#   - +base+:: A value of 0, or between 2 and 36. Defaults to 0
 	#   - +options+:: An options hash, containing any of the following
@@ -70,7 +70,7 @@ module Kernel
 	#     additional action. If the block returns then its return value will
 	#     be returned to the caller
 	#
-	# * *Options*:
+	# * *Options:*
 	#   - +:default+:: A default value to be used when +arg+ is +nil+ or
 	#     cannot be converted by (the original) +Kernel#Integer+
 	#   - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be

data/lib/xqsr3/extensions/test/unit/assert_not.rb

@@ -6,9 +6,9 @@ module Assertions
 
 	unless respond_to? :assert_not
 
-		def assert_not(test, failure_message = '')
+		def assert_not(expression, failure_message = '')
 
-			assert !(test), failure_message
+			assert !(expression), failure_message
 		end
 	end
 

data/lib/xqsr3/extensions/test/unit/assert_type_has_instance_methods.rb

@@ -11,7 +11,7 @@ module Assertions
 		#
 		# === Signature
 		#
-		# * *Parameters*
+		# * *Parameters:*
 		#   - +type+:: [::Class] The type
 		#   - +message_spec+:: [::Symbol, ::Array, ::Hash] A specification
 		#     of message(s) received by the instances of +type+. If a

data/lib/xqsr3/io/writelines.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a writelines() method to the IO module
 #
 # Created:      13th April 2007
-# Updated:      2nd August 2017
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -125,12 +125,12 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 	#
 	# === Signature
 	#
-	# * *Parameters*:
+	# * *Parameters:*
 	#   - +target+:: The target of the write, which may be a string containing the path or a stream instance that supports write
 	#   - +contents+:: The contents to be write, which may be a +Hash+, or an +Array+, or a +String+ containing delimited fields
 	#   - +options+:: An options hash, containing any of the following options
 	#
-	# * *Options*:
+	# * *Options:*
 	#   - +:column_separator+:: {optional} The column separator, to be applied between each field in the case where +contents+ is a +Hash+.
 	#   - +:eol_lookahead_limit+:: {optional} The number of content elements (line/pair) to inspect to determine whether element has a terminating end-of-line sequence. Defaults to 20. If 0, and +:line_separator+ is not specified, then will default to <tt>"\n"</tt>. If +nil+, then every line will be inspected.
 	#   - +:line_separator+:: {optional} The line separator, to be applied to the end of line created from each entry. When not specified, it will be deduced by inspecting +contents+ (according to +eol_lookahead_limit+).

data/lib/xqsr3/string_utilities/ends_with.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      13th April 2016
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -114,7 +114,7 @@ module EndsWith
 	#
 	# === Signature
 	#
-	# * *Parameters*
+	# * *Parameters:*
 	#
 	# * *Required parameters*:
 	#   - +s+:: [String] The string to be evaluated

data/lib/xqsr3/string_utilities/nil_if_empty.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      25th January 2018
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2018-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -73,7 +73,7 @@ module NilIfEmpty
 	#
 	# === Signature
 	#
-	# * *Parameters*
+	# * *Parameters:*
 	#
 	# * *Required parameters*:
 	#   - +s+:: [String] The string to be evaluated

data/lib/xqsr3/string_utilities/nil_if_whitespace.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      25th January 2018
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2018-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -73,7 +73,7 @@ module NilIfWhitespace
 	#
 	# === Signature
 	#
-	# * *Parameters*
+	# * *Parameters:*
 	#
 	# * *Required parameters*:
 	#   - +s+:: [String] The string to be evaluated

data/lib/xqsr3/string_utilities/quote_if.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -92,7 +92,7 @@ module QuoteIf
 	#
 	# === Signature
 	#
-	# * *Parameters*
+	# * *Parameters:*
 	#
 	# * *Required parameters*:
 	#   - +s+:: [String] The string to be evaluated
@@ -101,7 +101,7 @@ module QuoteIf
 	#   - +options+:: [Hash] Options that control the behaviour of the
 	#       method
 	#
-	# * *Options*:
+	# * *Options:*
 	#
 	#   - +:quotes+:: [String, Array] A string that is used as the opening
 	#       and closing quotes, or an array whose first two elements are

data/lib/xqsr3/version.rb

@@ -5,7 +5,7 @@
 # Purpose:      Version for Xqsr3 library
 #
 # Created:      3rd April 2016
-# Updated:      10th April 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.31.2'
+	VERSION				=	'0.32.2'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/containers/tc_frequency_map.rb

@@ -18,6 +18,10 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 		assert_equal 0, fm1.count
 		assert fm1.empty?
 		assert_equal 0, fm1.size
+
+		assert_nil fm1.default
+
+		assert_match /^#<Xqsr3::Containers::FrequencyMap:0x\d+:\s*@count\(\w+\)=0; @elements\(Hash\)={}\s*>$/, fm1.inspect
 	end
 
 	def test_class_operator_subscript_2
@@ -27,6 +31,8 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 		assert_equal 3, fm2.count
 		assert_not fm2.empty?
 		assert_equal 2, fm2.size
+
+		assert_match /^#<Xqsr3::Containers::FrequencyMap:0x\d+:\s*@count\(\w+\)=3; @elements\(Hash\)={.*abc.*def.*}\s*>$/, fm2.inspect
 	end
 
 	def test_class_operator_subscript_3
@@ -102,6 +108,52 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 		assert_equal 2, fm['jkl']
 	end
 
+	def test_class_operator_subscript_9
+
+		fm = FrequencyMap::ByElement[ 'abc', 'def', 'abc', :x, 'x', :y ]
+
+		assert_false fm.empty? # => false
+		assert_equal 5, fm.size   # => 5
+		assert_equal 6, fm.count  # => 6
+		assert_equal 2, fm['abc'] # => 2
+		assert_equal 1, fm['def'] # => 1
+		assert_equal 0, fm['ghi'] # => 0
+		assert_equal 1, fm['x']   # => 1
+		assert_equal 0, fm['y']   # => 0
+		assert_equal 0, fm['z']   # => 0
+		assert_equal 1, fm[:x]    # => 1
+		assert_equal 1, fm[:y]    # => 1
+		assert_equal 0, fm[:z]    # => 0
+
+		fm.push 'abc'
+
+		assert_false fm.empty?
+		assert_equal 5, fm.size
+		assert_equal 7, fm.count
+		assert_equal 3, fm['abc']
+
+		fm.push 'abc', 2
+
+		assert_false fm.empty?
+		assert_equal 5, fm.size
+		assert_equal 9, fm.count
+		assert_equal 5, fm['abc']
+
+		fm.push 'abc', -4
+
+		assert_false fm.empty?
+		assert_equal 5, fm.size
+		assert_equal 5, fm.count
+		assert_equal 1, fm['abc']
+
+		fm.push 'abc', -1
+
+		assert_false fm.empty?
+		assert_equal 4, fm.size
+		assert_equal 4, fm.count
+		assert_equal 0, fm['abc']
+	end
+
 	def test_instance_operator_equals
 
 		fm1 = FrequencyMap.new
@@ -150,13 +202,13 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 
 		fm = FrequencyMap.new
 
-		assert_nil fm[:abc]
-		assert_nil fm[:def]
+		assert_equal 0, fm[:abc]
+		assert_equal 0, fm[:def]
 
 		fm << :abc
 
 		assert_equal 1, fm[:abc]
-		assert_nil fm[:def]
+		assert_equal 0, fm[:def]
 
 		fm << :def << :def << :def
 
@@ -200,7 +252,7 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 
 		fm = FrequencyMap.new
 
-		assert_nil fm['abc']
+		assert_equal 0, fm['abc']
 		assert_equal 0, fm.count
 		assert fm.empty?
 		assert_equal 0, fm.size
@@ -214,7 +266,7 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 
 		fm.clear
 
-		assert_nil fm['abc']
+		assert_equal 0, fm['abc']
 		assert_equal 0, fm.count
 		assert fm.empty?
 		assert_equal 0, fm.size
@@ -757,3 +809,4 @@ class Test_Xqsr3_Containers_FrequencyMap < Test::Unit::TestCase
 	end
 end
 
+

data/test/unit/extensions/enumerable/tc_unique.rb

@@ -43,5 +43,29 @@ class Test_Enumerable_unique_test < Test::Unit::TestCase
 
 		assert_equal [ 1, 2, 3, 4], dest
 	end
+
+	def test_unique_very_large_sorted
+
+		max = 100000
+
+		src = (0...max).to_a * 2
+		exp = (0...max).to_a
+
+		dest = src.unique
+
+		assert_equal exp, dest
+	end
+
+	def test_unique_very_large_unsorted
+
+		max = 100000
+
+		src = ((0...max).to_a * 2).sort
+		exp = (0...max).to_a
+
+		dest = src.unique
+
+		assert_equal exp, dest
+	end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.31.2
+  version: 0.32.2
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-11 00:00:00.000000000 Z
+date: 2019-04-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -21,6 +21,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- examples/count_word_frequencies.md
+- examples/count_word_frequencies.rb
 - lib/xqsr3/array_utilities/join_with_or.rb
 - lib/xqsr3/command_line_utilities/map_option_string.rb
 - lib/xqsr3/containers/frequency_map.rb