xqsr3 0.32.2 → 0.36.0

data/lib/xqsr3/string_utilities.rb

@@ -0,0 +1,16 @@
+
+%w{
+
+	ends_with
+	nil_if_empty
+	nil_if_whitespace
+	quote_if
+	starts_with
+	to_symbol
+	truncate
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'string_utilities', name)
+end
+
+

data/lib/xqsr3/string_utilities/ends_with.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      13th April 2016
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -54,12 +54,15 @@
 module Xqsr3
 module StringUtilities
 
+# +include+-able module that provides ::string_ends_with? and #ends_with?
+# methods
 module EndsWith
 
 	private
-	module EndsWith_Helper_ #:nodoc:
+	# @!visibility private
+	module EndsWith_Helper_ # :nodoc: all
 
-		def self.string_ends_with_helper_ s, prefix
+		def self.string_ends_with_helper_ s, prefix # :nodoc:
 
 			if prefix.nil? || prefix.empty?
 
@@ -78,7 +81,7 @@ module EndsWith
 			nil
 		end
 
-		def self.string_ends_with_array_ s, args
+		def self.string_ends_with_array_ s, args # :nodoc:
 
 			return '' if args.empty?
 
@@ -115,14 +118,20 @@ module EndsWith
 	# === Signature
 	#
 	# * *Parameters:*
-	#
-	# * *Required parameters*:
-	#   - +s+:: [String] The string to be evaluated
+	#   - +s+ (String) The string to be evaluated
+	#   - +args+ 0+ arguments against which +s+ will be evaluated
 	def self.string_ends_with? s, *args
 
 		EndsWith_Helper_.string_ends_with_array_ s, args
 	end
 
+	# Reports on whether the instance ends with a given prefix or set of
+	# prefixes (+args+)
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +args+ 0+ arguments against which the instance will be evaluated
 	def ends_with? *args
 
 		EndsWith_Helper_.string_ends_with_array_ self, args

data/lib/xqsr3/string_utilities/nil_if_empty.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      25th January 2018
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -54,12 +54,15 @@
 module Xqsr3
 module StringUtilities
 
+# +include+-able module that provides ::string_nil_if_empty and
+# #nil_if_empty methods
 module NilIfEmpty
 
 	private
-	module NilIfEmpty_Helper_ #:nodoc:
+	# @!visibility private
+	module NilIfEmpty_Helper_ # :nodoc: all
 
-		def self.string_nil_if_empty_array_ s
+		def self.string_nil_if_empty_array_ s # :nodoc:
 
 			return s if s && !s.empty?
 
@@ -76,12 +79,13 @@ module NilIfEmpty
 	# * *Parameters:*
 	#
 	# * *Required parameters*:
-	#   - +s+:: [String] The string to be evaluated
+	#   - +s+ (String) The string to be evaluated
 	def self.string_nil_if_empty s
 
 		NilIfEmpty_Helper_.string_nil_if_empty_array_ s
 	end
 
+	# Returns +nil+ if the instance is empty, otherwise returning self
 	def nil_if_empty
 
 		NilIfEmpty_Helper_.string_nil_if_empty_array_ self

data/lib/xqsr3/string_utilities/nil_if_whitespace.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      25th January 2018
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -54,12 +54,15 @@
 module Xqsr3
 module StringUtilities
 
+# +include+-able module that provides ::string_nil_if_whitespace and
+# #nil_if_whitespace methods
 module NilIfWhitespace
 
 	private
-	module NilIfWhitespace_Helper_ #:nodoc:
+	# @!visibility private
+	module NilIfWhitespace_Helper_ # :nodoc: all
 
-		def self.string_nil_if_whitespace_array_ s
+		def self.string_nil_if_whitespace_array_ s # :nodoc:
 
 			return nil if s.strip.empty?
 
@@ -76,12 +79,14 @@ module NilIfWhitespace
 	# * *Parameters:*
 	#
 	# * *Required parameters*:
-	#   - +s+:: [String] The string to be evaluated
+	#   - +s+ (String) The string to be evaluated
 	def self.string_nil_if_whitespace s
 
 		NilIfWhitespace_Helper_.string_nil_if_whitespace_array_ s
 	end
 
+	# Returns +nil+ if the instance is empty or contains only whitespace,
+	# otherwise returning self
 	def nil_if_whitespace
 
 		NilIfWhitespace_Helper_.string_nil_if_whitespace_array_ self

data/lib/xqsr3/string_utilities/quote_if.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -54,12 +54,14 @@
 module Xqsr3
 module StringUtilities
 
+# +include+-able module that provides ::quote_if and #quote_if methods
 module QuoteIf
 
 	private
-	module QuoteIf_Helper_ #:nodoc:
+	# @!visibility private
+	module QuoteIf_Helper_ # :nodoc: all
 
-		def self.string_quote_if_array_ s, options
+		def self.string_quote_if_array_ s, options # :nodoc:
 
 			s			=	s.to_s unless String === s
 
@@ -95,27 +97,23 @@ module QuoteIf
 	# * *Parameters:*
 	#
 	# * *Required parameters*:
-	#   - +s+:: [String] The string to be evaluated
+	#   - +s+ (String) The string to be evaluated
 	#
 	# * *Options parameters*:
-	#   - +options+:: [Hash] Options that control the behaviour of the
-	#       method
+	#   - +options+ (Hash) Options that control the behaviour of the method
 	#
 	# * *Options:*
 	#
-	#   - +:quotes+:: [String, Array] A string that is used as the opening
-	#       and closing quotes, or an array whose first two elements are
-	#       used as the opening and closing quotes. Defaults to '"'
-	#   - +:quotables+:: [String, Array, Regexp] A string representing the
-	#       quotable character, or an array containing the quotable
-	#       characters, or a regular expression that determines by match
-	#       whether the string should be quoted. Defaults to the regular
-	#       expression /\s/
+	#   - +:quotes+ (String, Array) A string that is used as the opening and closing quotes, or an array whose first two elements are used as the opening and closing quotes. Defaults to +'"'+
+	#   - +:quotables+ (String, Array, Regexp) A string representing the quotable character, or an array containing the quotable characters, or a regular expression that determines by match whether the string should be quoted. Defaults to the regular expression +/\s/+
 	def self.quote_if s, **options
 
 		QuoteIf_Helper_.string_quote_if_array_ s, options
 	end
 
+	# Converts the instance to a quoted form if necessary
+	#
+	# See Xqsr3::StringUtilities::QuoteIf::quite_if() for options
 	def quote_if **options
 
 		QuoteIf_Helper_.string_quote_if_array_ self, options

data/lib/xqsr3/string_utilities/starts_with.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      13th April 2016
-# Updated:      10th June 2016
+# Updated:      15th 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
@@ -54,12 +54,15 @@
 module Xqsr3
 module StringUtilities
 
+# +include+-able module that provides ::string_starts_with? and #starts_with?
+# methods
 module StartsWith
 
 	private
-	module StartsWith_Helper_ #:nodoc:
+	# @!visibility private
+	module StartsWith_Helper_ # :nodoc: all
 
-		def self.string_starts_with_helper_ s, prefix
+		def self.string_starts_with_helper_ s, prefix # :nodoc:
 
 			if prefix.nil? || prefix.empty?
 
@@ -78,7 +81,7 @@ module StartsWith
 			nil
 		end
 
-		def self.string_starts_with_array_ s, args
+		def self.string_starts_with_array_ s, args # :nodoc:
 
 			return '' if args.empty?
 
@@ -109,11 +112,26 @@ module StartsWith
 	end
 	public
 
+	# Reports on whether a string +s+ starts with a given prefix or set of
+	# prefixes (+args+)
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +s+ (String) The string to be evaluated
+	#   - +args+ 0+ arguments against which +s+ will be evaluated
 	def self.string_starts_with? s, *args
 
 		StartsWith_Helper_.string_starts_with_array_ s, args
 	end
 
+	# Reports on whether the instance starts with a given prefix or set of
+	# prefixes (+args+)
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +args+ 0+ arguments against which the instance will be evaluated
 	def starts_with? *args
 
 		StartsWith_Helper_.string_starts_with_array_ self, args

data/lib/xqsr3/string_utilities/to_symbol.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      14th April 2016
-# Updated:      10th June 2016
+# Updated:      15th 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
@@ -59,15 +59,16 @@ module StringUtilities
 module ToSymbol
 
 	private
-	module ToSymbol_Helper_ #:nodoc:
+	# @!visibility private
+	module ToSymbol_Helper_ # :nodoc: all
 
-		module Constants #:nodoc:
+		module Constants # :nodoc:
 
 			SymbolCharacters0	=	'abcdefghijklmnopqrstuvwxyz_ABCDEFGHIJKLMNOPQRSTUVWXYZ'
 			SymbolCharactersN	=	'abcdefghijklmnopqrstuvwxyz_ABCDEFGHIJKLMNOPQRSTUVWXYZ_0123456789'
 		end
 
-		def self.string_to_symbol_with_options_ s, options
+		def self.string_to_symbol_with_options_ s, options # :nodoc:
 
 			case	s
 			when	::String
@@ -127,11 +128,29 @@ module ToSymbol
 	end
 	public
 
+	# Converts the given string +s+ to a symbol according to the given
+	# +options+
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +s+ (String) The string to convert
+	#   - +options+ (Hash) Options hash
+	#
+	# * *Options:*
+	#   - +:reject_hyphens+ (boolean)
+	#   - +:reject_spaces+ (boolean)
+	#   - +:reject_tabs+ (boolean)
+	#   - +:reject_whitespace+ (boolean)
+	#   - +:transform_characters+ (boolean)
 	def self.string_to_symbol s, options = {}
 
 		ToSymbol_Helper_.string_to_symbol_with_options_ s, options
 	end
 
+	# Converts the instance to a symbol, according to the given +options+
+	#
+	# See Xqsr3::StringUtilities::ToSymbol::string_to_symbol for options
 	def to_symbol options = {}
 
 		ToSymbol_Helper_.string_to_symbol_with_options_ self, options

data/lib/xqsr3/string_utilities/truncate.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      12th April 2018
-# Updated:      12th April 2018
+# Updated:      15th 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
@@ -59,9 +59,10 @@ module StringUtilities
 module Truncate
 
 	private
-	module Truncate_Helper_ #:nodoc:
+	# @!visibility private
+	module Truncate_Helper_ # :nodoc: all
 
-		def self.string_truncate_with_options_ s, width, options
+		def self.string_truncate_with_options_ s, width, options # :nodoc:
 
 			case	s
 			when	::String
@@ -102,11 +103,26 @@ module Truncate
 	end
 	public
 
+	# Truncates the given string +s+ to the given +width+ according to the
+	# given +options+
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +s+ (String) The string to convert
+	#   - +width+ (Integer) The truncation width
+	#   - +options+ (Hash) Options hash
+	#
+	# * *Options:*
+	#   - +:omission+ (String) Omission string. Defaults to "..."
 	def self.string_truncate s, width, options = {}
 
 		Truncate_Helper_.string_truncate_with_options_ s, width, options
 	end
 
+	# Truncates the instance, according to the given +width+ and +options+
+	#
+	# See Xqsr3::StringUtilities::ToSymbol::string_truncate for options
 	def truncate width, options = {}
 
 		Truncate_Helper_.string_truncate_with_options_ self, width, options

data/lib/xqsr3/version.rb

@@ -5,12 +5,13 @@
 # Purpose:      Version for Xqsr3 library
 #
 # Created:      3rd April 2016
-# Updated:      12th April 2019
+# Updated:      26th May 2020
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -50,7 +51,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.32.2'
+	VERSION				=	'0.36.0'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/containers/tc_multi_map.rb

@@ -481,7 +481,7 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 
 		assert_not mm.has_key? :abc
 
-		mm.push :abc
+		mm.push :abc, *[ :v1, :v2 ]
 
 		assert mm.has_key? :abc
 
@@ -494,15 +494,37 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 
 		mm = MultiMap.new
 
-		assert_not mm.has_value? []
+		assert_not mm.has_value? :abc
+
+		mm.push :abc, *[ :v1, :v2 ]
+
+		assert mm.has_value? :v1
+		assert mm.has_value? :v2
+		assert_not mm.has_value? :v3
+
+		mm.delete :abc
+
+		assert_not mm.has_value? :abc
+	end
+
+	def test_has_values?
+
+		mm = MultiMap.new
+
+		assert_not mm.has_values? []
 
 		mm.push :abc
 
-		assert mm.has_value? []
+		assert mm.has_values? []
+
+		mm.push :abc, * [ :v1, :v2 ]
+
+		assert_not mm.has_values? []
+		assert mm.has_values? [ :v1, :v2 ]
 
 		mm.delete :abc
 
-		assert_not mm.has_value? []
+		assert_not mm.has_values? []
 	end
 
 	def test_key
@@ -512,13 +534,43 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 		assert_nil mm.key []
 		assert_nil mm.key :not_defined
 
-		mm.push :abc
+		mm.push :abc, :v1
 
-		assert_equal :abc, mm.key([])
+		assert_equal :abc, mm.key(:v1)
+		assert_nil mm.key(:v2)
 
-		mm.push :abc, 1
+		mm.push :abc, :v2
+
+		assert_equal :abc, mm.key(:v1)
+		assert_equal :abc, mm.key(:v2)
+		assert_equal :abc, mm.key(:v1, :v2)
+		assert_nil mm.key(:v2, :v1)
+		assert_nil mm.key([:v1, :v2])
+
+		mm.delete :abc
+
+		mm.push :def, :v2, :v1
+
+		assert_equal :def, mm.key(:v2, :v1)
+		assert_nil mm.key(:v1, :v2)
+		assert_equal :def, mm.key(:v1)
+		assert_equal :def, mm.key(:v2)
+
+		mm.delete :def
+
+		mm.push :ghi, [ :v2, :v1 ]
+
+		assert_equal :ghi, mm.key([:v2, :v1])
+		assert_nil mm.key([:v1, :v2])
+		assert_nil mm.key(:v1)
+		assert_nil mm.key(:v2)
+
+		mm.push :ghi, :v1
 
-		assert_equal :abc, mm.key([ 1 ])
+		assert_equal :ghi, mm.key([:v2, :v1])
+		assert_nil mm.key([:v1, :v2])
+		assert_equal :ghi, mm.key(:v1)
+		assert_nil mm.key(:v2)
 	end
 
 	def test_length_and_size
@@ -549,7 +601,7 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 		test_length_and_size
 	end
 
-	def test_merge
+	def test_multi_merge
 
 		mm1 = MultiMap.new
 
@@ -562,12 +614,42 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 		mm2.push :abc, 4, 5
 		mm2.push :def, 'a'
 
-		mm3 = mm1.merge mm2
+		mm3 = mm1.multi_merge mm2
 
-		assert_equal [ :abc, 1, :abc, 2, :abc, 3, :abc, 4, :abc, 5, :def, 'a' ], mm3.flatten
+		h = Hash.new
+
+		h.store :ghi, 'x'
+
+		mm4 = mm3.multi_merge h
+
+		assert_equal [ :abc, 1, :abc, 2, :abc, 3, :abc, 4, :abc, 5, :def, 'a', :ghi, 'x' ], mm4.flatten
+	end
+
+	def test_multi_merge!
+
+		mm1 = MultiMap.new
+
+		mm1.push :abc, 1, 2, 3
+
+		assert_equal [ :abc, 1, :abc, 2, :abc, 3 ], mm1.flatten
+
+		mm2 = MultiMap.new
+
+		mm2.push :abc, 4, 5
+		mm2.push :def, 'a'
+
+		mm1.multi_merge! mm2
+
+		h = Hash.new
+
+		h.store :ghi, 'x'
+
+		mm1.multi_merge! h
+
+		assert_equal [ :abc, 1, :abc, 2, :abc, 3, :abc, 4, :abc, 5, :def, 'a', :ghi, 'x' ], mm1.flatten
 	end
 
-	def test_merge!
+	def test_strict_merge
 
 		mm1 = MultiMap.new
 
@@ -580,9 +662,39 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 		mm2.push :abc, 4, 5
 		mm2.push :def, 'a'
 
-		mm1.merge! mm2
+		mm3 = mm1.strict_merge mm2
+
+		h = Hash.new
+
+		h.store :ghi, 'x'
+
+		mm4 = mm3.strict_merge h
 
-		assert_equal [ :abc, 1, :abc, 2, :abc, 3, :abc, 4, :abc, 5, :def, 'a' ], mm1.flatten
+		assert_equal [ :abc, 4, :abc, 5, :def, 'a', :ghi, 'x' ], mm4.flatten
+	end
+
+	def test_strict_merge!
+
+		mm1 = MultiMap.new
+
+		mm1.push :abc, 1, 2, 3
+
+		assert_equal [ :abc, 1, :abc, 2, :abc, 3 ], mm1.flatten
+
+		mm2 = MultiMap.new
+
+		mm2.push :abc, 4, 5
+		mm2.push :def, 'a'
+
+		mm1.strict_merge! mm2
+
+		h = Hash.new
+
+		h.store :ghi, 'x'
+
+		mm1.strict_merge! h
+
+		assert_equal [ :abc, 4, :abc, 5, :def, 'a', :ghi, 'x' ], mm1.flatten
 	end
 
 	def test_push
@@ -698,6 +810,25 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 		assert_equal ({ abc: [ 1, 2, 3, 4, 5 ], def: [] }), mm.to_h
 	end
 
+	def test_values_unflattened
+
+		mm = MultiMap.new
+
+		assert_equal [], mm.values_unflattened
+
+		mm.store :abc
+
+		assert_equal [ [] ], mm.values_unflattened
+
+		mm.store :abc, 1, 2, '3', nil, false
+
+		assert_equal [ [ 1, 2, '3', nil, false ] ], mm.values_unflattened
+
+		mm.store :def, true
+
+		assert_equal [ [ 1, 2, '3', nil, false ], [ true ] ], mm.values_unflattened
+	end
+
 	def test_values
 
 		mm = MultiMap.new
@@ -706,11 +837,38 @@ class Test_Xqsr3_Containers_MultiMap < Test::Unit::TestCase
 
 		mm.store :abc
 
-		assert_equal [ [] ], mm.values
+		assert_equal [], mm.values
 
 		mm.store :abc, 1, 2, '3', nil, false
 
-		assert_equal [ [ 1, 2, '3', nil, false ] ], mm.values
+		assert_equal [ 1, 2, '3', nil, false ], mm.values
+
+		mm.store :def, true
+
+		assert_equal [ 1, 2, '3', nil, false, true ], mm.values
+	end
+
+	def test_to_s
+
+		mm = MultiMap[]
+
+		assert_equal "{}", mm.to_s
+
+		mm.store :abc
+
+		assert_equal "{:abc=>[]}", mm.to_s
+
+		mm.store :abc, 1
+
+		assert_equal "{:abc=>[1]}", mm.to_s
+
+		mm.store :abc, 1, 23
+
+		assert_equal "{:abc=>[1, 23]}", mm.to_s
+
+		mm.store :def, *(0...10).to_a
+
+		assert_equal "{:abc=>[1, 23], :def=>[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}", mm.to_s
 	end
 end