xqsr3 0.38.2 → 0.39.2

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

@@ -5,13 +5,13 @@
 # Purpose:  ::Enumerable#detect_map extension
 #
 # Created:  3rd December 2017
-# Updated:  11th December 2023
+# Updated:  29th March 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -50,46 +50,46 @@
 
 module Enumerable
 
-	# The +Enumerable+#+detect+ method provides a way to detect the presence
-	# of a particular value in a collection. The only constraint is that you
-	# get back the object unchanged.
-	#
-	# The +Enumerable+#+map+ method provides a way to transform the contents of
-	# a collection. The only constraint is that you get back another
-	# collection.
-	#
-	# This extension method, +Enumerable+#+detect_map+ combines the features
-	# of both, in that it detects the presence of a particular value in a
-	# collection and transform the detected value.
-	#
-	#  [ 1, 2, 3 ].detect_map { |v| -2 * v if v > 2 } # => -6
-	#
-	#  { :ab => 'cd', :ef => 'gh' }.detect_map { |k, v| v.upcase if k == :ef } # => 'GH'
-	#
-	# *Note:* The block is required (for technical reasons), and must have
-	# arity 1 for sequences or 2 for associations
-	def detect_map &block
+  # The +Enumerable+#+detect+ method provides a way to detect the presence
+  # of a particular value in a collection. The only constraint is that you
+  # get back the object unchanged.
+  #
+  # The +Enumerable+#+map+ method provides a way to transform the contents of
+  # a collection. The only constraint is that you get back another
+  # collection.
+  #
+  # This extension method, +Enumerable+#+detect_map+ combines the features
+  # of both, in that it detects the presence of a particular value in a
+  # collection and transform the detected value.
+  #
+  #  [ 1, 2, 3 ].detect_map { |v| -2 * v if v > 2 } # => -6
+  #
+  #  { :ab => 'cd', :ef => 'gh' }.detect_map { |k, v| v.upcase if k == :ef } # => 'GH'
+  #
+  # *Note:* The block is required (for technical reasons), and must have
+  # arity 1 for sequences or 2 for associations
+  def detect_map &block
 
-		case block.arity
-		when 1
+    case block.arity
+    when 1
 
-			self.each do |v|
+      self.each do |v|
 
-				r = yield(v) and return r
-			end
-		when 2
+        r = yield(v) and return r
+      end
+    when 2
 
-			self.each do |k, v|
+      self.each do |k, v|
 
-				r = yield(k, v) and return r
-			end
-		else
+        r = yield(k, v) and return r
+      end
+    else
 
-			raise ArgumentError, "detect_map requires block with arity of 1 (for sequences) or 2 (for associations); block with arity #{block.arity} given to instance of #{self.class}"
-		end
+      raise ArgumentError, "detect_map requires block with arity of 1 (for sequences) or 2 (for associations); block with arity #{block.arity} given to instance of #{self.class}"
+    end
 
-		nil
-	end
+    nil
+  end
 end # module Enumerable
 
 # ############################## end of file ############################# #

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

@@ -1,16 +1,17 @@
 
 # ######################################################################## #
-# File: 	    lib/xqsr3/extensions/enumerable/unique.rb
+# File:     lib/xqsr3/extensions/enumerable/unique.rb
 #
-# Purpose:	    Adds a unique() method to the Enumerable module
+# Purpose:  Adds a unique() method to the Enumerable module
 #
-# Created:	    5th March 2007
-# Updated:	    12th April 2019
+# Created:  5th March 2007
+# Updated:  29th March 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
 # Author:   Matthew Wilson
 #
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -52,40 +53,40 @@
 
 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)
+  # 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
+    if not block
 
-			return unique { |a, b| a == b }
-		else
+      return unique { |a, b| a == b }
+    else
 
-			raise ArgumentError, "block requires two parameters" unless block.arity == 2
+      raise ArgumentError, "block requires two parameters" unless block.arity == 2
 
-			ar	=	self.to_a
+      ar = self.to_a
 
-			return ar if ar.length < 2
+      return ar if ar.length < 2
 
-			r	=	[]
-			h	=	{}
+      r = []
+      h = {}
 
-			ar.each do |v|
+      ar.each do |v|
 
-				unless h.has_key?(v)
+        unless h.has_key?(v)
 
-					r << v
-					h[v] = nil
-				end
-			end
+          r << v
+          h[v] = nil
+        end
+      end
 
-			return r
-		end
-	end
+      return r
+    end
+  end
 end # module Enumerable
 
 # ############################## end of file ############################# #

data/lib/xqsr3/extensions/hash/deep_transform.rb

@@ -3,6 +3,6 @@ require 'xqsr3/hash_utilities/deep_transform'
 
 class Hash
 
-	include ::Xqsr3::HashUtilities::DeepTransform
+  include ::Xqsr3::HashUtilities::DeepTransform
 end # class Hash
 

data/lib/xqsr3/extensions/hash/except.rb

@@ -1,32 +1,32 @@
 
 unless Hash.instance_methods.include? :except!
 
-	class Hash
+  class Hash
 
-		# Removes from the instance any key-value pairs matching the
-		# keys specified in +keys_to_delete+
-		def except!(*keys_to_delete)
+    # Removes from the instance any key-value pairs matching the
+    # keys specified in +keys_to_delete+
+    def except!(*keys_to_delete)
 
-			keys_to_delete.each do |key|
+      keys_to_delete.each do |key|
 
-				self.delete key
-			end
+        self.delete key
+      end
 
-			self
-		end
+      self
     end
+  end
 end
 
 unless Hash.instance_methods.include? :except
 
-	class Hash
+  class Hash
 
-		# Obtains a copy of the instance wherein any key-value pairs
-		# matching the keys specified in +keys_to_delete+ are removed
-		def except(*keys_to_delete)
+    # Obtains a copy of the instance wherein any key-value pairs
+    # matching the keys specified in +keys_to_delete+ are removed
+    def except(*keys_to_delete)
 
-			self.dup.except!(*keys_to_delete)
-		end
-	end
+      self.dup.except!(*keys_to_delete)
+    end
+  end
 end
 

data/lib/xqsr3/extensions/hash/has_match.rb

@@ -3,16 +3,16 @@ require 'xqsr3/hash_utilities/key_matching'
 
 class Hash
 
-	# Extended method implemented by Xqsr3::HashUtilities::KeyMatching
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +re+ (Regexp) The regular expression
-	#   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
-	def has_match? re, **options
+  # Extended method implemented by Xqsr3::HashUtilities::KeyMatching
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +re+ (Regexp) The regular expression
+  #   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
+  def has_match? re, **options
 
-		return ::Xqsr3::HashUtilities::KeyMatching.has_match? self, re, **options
-	end
+    return ::Xqsr3::HashUtilities::KeyMatching.has_match? self, re, **options
+  end
 end
 

data/lib/xqsr3/extensions/hash/match.rb

@@ -3,16 +3,16 @@ require 'xqsr3/hash_utilities/key_matching'
 
 class Hash
 
-	# Extended method implemented by Xqsr3::HashUtilities::KeyMatching
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +re+ (Regexp) The regular expression
-	#   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
-	def match re, **options
+  # Extended method implemented by Xqsr3::HashUtilities::KeyMatching
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +re+ (Regexp) The regular expression
+  #   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
+  def match re, **options
 
-		return ::Xqsr3::HashUtilities::KeyMatching.match self, re, **options
-	end
+    return ::Xqsr3::HashUtilities::KeyMatching.match self, re, **options
+  end
 end
 

data/lib/xqsr3/extensions/hash/slice.rb

@@ -1,22 +1,22 @@
 
 unless Hash.instance_methods.include? :slice
 
-	class Hash
+  class Hash
 
-		def slice(*args)
+    def slice(*args)
 
-			r = {}
+      r = {}
 
-			args.each do |arg|
+      args.each do |arg|
 
-				if self.has_key? arg
+        if self.has_key? arg
 
-					r[arg] = self[arg]
-				end
-			end
+          r[arg] = self[arg]
+        end
+      end
 
-			r
-		end
-	end
+      r
+    end
+  end
 end
 

data/lib/xqsr3/extensions/hash.rb

@@ -6,6 +6,6 @@ require 'xqsr3/extensions/hash/match'
 
 unless (RUBY_VERSION.split('.').map { |v| v.to_i } <=> [ 2, 5, 0 ]) > 0
 
-	require 'xqsr3/extensions/hash/slice'
+  require 'xqsr3/extensions/hash/slice'
 end
 

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

@@ -0,0 +1,118 @@
+
+# ######################################################################## #
+# File:     lib/xqsr3/extensions/integer/to_s_grp.rb
+#
+# Purpose:  Adds a to_s_grp() method to the Integer class
+#
+# Created:  29th March 2024
+# Updated:  29th March 2024
+#
+# Home:     http://github.com/synesissoftware/xqsr3
+#
+# Author:   Matthew Wilson
+#
+# Copyright (c) 2024, Matthew Wilson and Synesis Information Systems
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR 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.
+#
+# ######################################################################## #
+
+
+# ##########################################################
+# ::Integer
+
+=begin
+=end
+
+class Integer
+
+  # Extends +Integer+ type with the +#to_s_grp()+ method
+  def to_s_grp *args, **options
+
+    separator = options[:separator] || ','
+
+    numbers =
+    case args.size
+    when 0
+
+      []
+    when 1
+      case args[0]
+      when ::Array
+
+        args[0]
+      when ::Integer
+
+        [ args[0] ]
+      else
+
+        raise TypeError, "parameter 'args[0]' (#{args[0].class}) must be an instance of Integer, or an array containing instance(s) of Integer"
+      end
+    else
+
+      args
+    end
+
+
+    case numbers.size
+    when 0
+
+      return self.to_s
+    when 1
+
+      return self.to_s.chars.to_a.reverse.each_slice(numbers[0]).map(&:join).join(',').reverse
+    else
+
+      reversed_chars = self.to_s.chars.to_a#.reverse
+
+      r = []
+
+      last_n = nil
+
+      numbers.each do |n|
+
+        r << separator unless r.empty?
+        r << reversed_chars.pop(n).reverse
+
+        last_n = n
+      end
+
+      until reversed_chars.empty?
+
+        r << separator unless r.empty?
+        r << reversed_chars.pop(last_n).reverse
+      end
+
+      r.flatten.join('').reverse
+    end
+  end
+end # module Kernel
+
+# ############################## end of file ############################# #
+

data/lib/xqsr3/extensions/integer.rb

@@ -0,0 +1,3 @@
+
+require 'xqsr3/extensions/integer/to_s_grp'
+

data/lib/xqsr3/extensions/io/writelines.rb

@@ -5,13 +5,13 @@
 # Purpose:  Adds a writelines() method to the IO class
 #
 # Created:  13th April 2007
-# Updated:  11th December 2023
+# Updated:  12th April 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -55,43 +55,43 @@ require 'xqsr3/io/writelines'
 
 class IO
 
-	# Extends +IO+ class with the +::Xqsr3::IO::write_lines+ method
-	#
-	#
-	#def self.writelines(path, contents, lineSep = nil, columnSep = nil)
-	def self.writelines(path, contents, *args)
+  # Extends +IO+ class with the +::Xqsr3::IO::write_lines+ method
+  #
+  #
+  #def self.writelines(path, contents, lineSep = nil, columnSep = nil)
+  def self.writelines(path, contents, *args)
 
-		options = {}
+    options = {}
 
-		case args.size
-		when 0
+    case args.size
+    when 0
 
-			;
-		when 1
+      ;
+    when 1
 
-			arg3 = args[0]
+      arg3 = args[0]
 
-			if arg3.respond_to?(:to_hash)
+      if arg3.respond_to?(:to_hash)
 
-				options.merge! arg3.to_hash
-			else
+        options.merge! arg3.to_hash
+      else
 
-				options[:line_separator] = arg3
-			end
-		when 2
+        options[:line_separator] = arg3
+      end
+    when 2
 
-			arg3 = args[0]
-			arg4 = args[1]
+      arg3 = args[0]
+      arg4 = args[1]
 
-			options[:line_separator] = arg2
-			options[:column_separator] = arg2
-		else
+      options[:line_separator] = arg3
+      options[:column_separator] = arg4
+    else
 
-			raise ArgumentError, "wrong number of arguments (given #{2 + args.size}, expected 2..4)"
-		end
+      raise ArgumentError, "wrong number of arguments (given #{2 + args.size}, expected 2..4)"
+    end
 
-		::Xqsr3::IO.writelines path, contents, **options
-	end
+    ::Xqsr3::IO.writelines path, contents, **options
+  end
 end # class IO
 
 # ############################## end of file ############################# #

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:  11th December 2023
+# Updated:  29th March 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -55,27 +55,27 @@ require 'xqsr3/conversion/integer_parser'
 
 module Kernel
 
-	alias xqsr3_Integer_original_method Integer
+  alias xqsr3_Integer_original_method Integer
 
-	# A monkey-patch extension of +Kernel#Integer+ with +options+
-	#
-	# === Signature
-	#
-	# * *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 options
-	#   - +block+ An optional caller-supplied block that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
-	#
-	# * *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 converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
-	def Integer(arg, base = 0, **options, &block)
+  # A monkey-patch extension of +Kernel#Integer+ with +options+
+  #
+  # === Signature
+  #
+  # * *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 options
+  #   - +block+ An optional caller-supplied block that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
+  #
+  # * *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 converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
+  def Integer(arg, base = 0, **options, &block)
 
-		::Xqsr3::Conversion::IntegerParser.to_integer arg, base = 0, **options, &block
-	end
+    ::Xqsr3::Conversion::IntegerParser.to_integer arg, base = 0, **options, &block
+  end
 
-	private :xqsr3_Integer_original_method
+  private :xqsr3_Integer_original_method
 end # module Kernel
 
 # ############################## end of file ############################# #

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

@@ -5,13 +5,13 @@
 # Purpose:  Adds a raise_with_options() method to the Kernel module
 #
 # Created:  12th February 2015
-# Updated:  11th December 2023
+# Updated:  29th March 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2015-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -55,14 +55,14 @@ require 'xqsr3/diagnostics/exception_utilities'
 
 module Kernel
 
-	# Extends +Kernel+ module with the ::Xqsr3::Diagnostics::ExceptionUtilities::raise_with_options
-	# method
-	def raise_with_options *args, **options
+  # Extends +Kernel+ module with the ::Xqsr3::Diagnostics::ExceptionUtilities::raise_with_options
+  # method
+  def raise_with_options *args, **options
 
-		options	||=	{}
+    options ||= {}
 
-		::Xqsr3::Diagnostics::ExceptionUtilities.raise_with_options(*args, **(options.merge({ :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 => 1})))
-	end
+    ::Xqsr3::Diagnostics::ExceptionUtilities.raise_with_options(*args, **(options.merge({ :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 => 1})))
+  end
 end # module Kernel
 
 # ############################## end of file ############################# #

data/lib/xqsr3/extensions/kernel.rb

@@ -1,3 +1,4 @@
 
+require 'xqsr3/extensions/kernel/integer'
 require 'xqsr3/extensions/kernel/raise_with_options'
 

data/lib/xqsr3/extensions/string/ends_with.rb

@@ -3,6 +3,6 @@ require 'xqsr3/string_utilities/ends_with'
 
 class String
 
-	include ::Xqsr3::StringUtilities::EndsWith
+  include ::Xqsr3::StringUtilities::EndsWith
 end # class String