numru-misc 0.1.1 → 0.1.2

data/lib/numru/misc/md_iterators.rb

@@ -1,90 +1,64 @@
 =begin
-=module NumRu::Misc::MD_Iterators
 
-A Mixin.
-To be included in a class with multi-dimension indexing support
-(such as NArray).
-
-==Index
-
-* ((<each_subary_at_dims>))
-* ((<each_subary_at_dims_with_index>))
-
-==Methods
----each_subary_at_dims( *dims )
-
-    Iterator for each sub-array (not each element) specified by dimensions.
-
-    ARGUMENT
-    * ((|dims|)) (integers) : specifies subsets at dimensions 
-      specified here with the beginning-to-end selection. 
-      For example, [0, 1] to specify the first 2 dimensions 
-      (subsets will be 2D then), and [2] to specify the 3rd 
-      dimension (subsets will be 1D). Duplication has no effect, 
-      so [0,0] and [0] are the same. Also, its order has no effect.
-      See EXAMPLE below for more.
-
-    RETURN VALUE
-    * self
-
-    POSSIBLE EXCEPTIONS
-    * exception is raised if ( dims.min<0 || dims.max>=self.rank ).
-
-    EXAMPLE
-
-    * Suppose that you want to do something with 2D sub-arrays in a
-      multi-dimension NArray. First, you include this module as follows:
-
-        require "narray"
-        class NArray
-           include NumRu::Misc::MD_Iterators
-        end
-
-      And prepare the array if you have not (here, it is 4D):
-
-        na = NArray.int(10,2,5,2).indgen!
-
-      Then you do the job like this:
-
-        na.each_subary_at_dims(0,2){ |sub|
-          ...  # do whatever with sub
-        }
-
-      This is equivalent to the following:
-
-        (0...na.shape[3]).each{|j|
-          (0...na.shape[1]).each{|i|
-            sub = na[0..-1, i, 0..-1, j]
-            ...  # do whatever with sub
-          }
-        }
-
-      Note that the loop must be nested 3 times when (('na')) is a 5D array,
-      if the latter approach is used. On the other hand, it will still 
-      require the same single loop with the former.      
-
----each_subary_at_dims_with_index( *dims )
-    Like ((<each_subary_at_dims>)) but the block takes two arguments:
-    subset and the subset specifier (index).
-
-    EXAMPLE
-    * Suppose the example above in ((<each_subary_at_dims>)) (EXAMPLE).
-      And suppose that you want to overwrite (('na')) with the result
-      you get. You can do it like this:
-
-        na.each_subary_at_dims_with_index(0,2){ |sub,idx|
-          result = (sub + 10) / 2
-          na[*idx] = result
-        }
-
-      Here, (('idx')) is an Array to be fed in the []= or [] methods
-      with asterisk (ungrouping).
 =end
 
 module NumRu
   module Misc
+    # A Mixin.
+    # To be included in a class with multi-dimension indexing support
+    # (such as NArray).
     module MD_Iterators
 
+      # Iterator for each sub-array (not each element) specified by
+      # dimensions.  
+      # 
+      # ARGUMENT
+      # 
+      # <tt>*dims</tt> (integers) : specifies subsets
+      # at dimensions specified here with the beginning-to-end selection.
+      # For example, [0, 1] to specify the first 2 dimensions (subsets
+      # will be 2D then), and [2] to specify the 3rd dimension (subsets
+      # will be 1D). Duplication has no effect, so [0,0] and [0] are the
+      # same. Also, its order has no effect.  See EXAMPLE below for more.
+      # 
+      # RETURN VALUE
+      # * self
+      # 
+      # POSSIBLE EXCEPTIONS
+      # * exception is raised if ( dims.min<0 || dims.max>=self.rank ).
+      # 
+      # EXAMPLE
+      # 
+      # * Suppose that you want to do something with 2D sub-arrays in a
+      #   multi-dimension NArray. First, you include this module as follows:
+      # 
+      #     require "narray"
+      #     class NArray
+      #        include NumRu::Misc::MD_Iterators
+      #     end
+      # 
+      #   And prepare the array if you have not (here, it is 4D):
+      # 
+      #     na = NArray.int(10,2,5,2).indgen!
+      # 
+      #   Then you do the job like this:
+      # 
+      #     na.each_subary_at_dims(0,2){ |sub|
+      #       ...  # do whatever with sub
+      #     }
+      # 
+      #   This is equivalent to the following:
+      # 
+      #     (0...na.shape[3]).each{|j|
+      #       (0...na.shape[1]).each{|i|
+      #         sub = na[0..-1, i, 0..-1, j]
+      #         ...  # do whatever with sub
+      #       }
+      #     }
+      # 
+      #   Note that the loop must be nested 3 times when <tt>na>/tt> is a 5D array,
+      #   if the latter approach is used. On the other hand, it will still 
+      #   require the same single loop with the former.      
       def each_subary_at_dims( *dims )
 	if dims.min<0 || dims.max>=rank
 	  raise ArguemntError,"Invalid dims #{dims.inspect} for #{rank}D array"
@@ -117,6 +91,22 @@ module NumRu
 	self
       end
 
+    # Like #each_subary_at_dims but the block takes two arguments:
+    # subset and the subset specifier (index).
+    # 
+    # EXAMPLE
+    # * Suppose the example above in #each_subary_at_dims (EXAMPLE).
+    #   And suppose that you want to overwrite <tt>na</tt> with the result
+    #   you get. You can do it like this:
+    # 
+    #     na.each_subary_at_dims_with_index(0,2){ |sub,idx|
+    #       result = (sub + 10) / 2
+    #       na[*idx] = result
+    #     }
+    # 
+    #   Here, <tt>idx</tt> is an Array to be fed in the []= or [] methods
+    #   with asterisk (ungrouping).
+    #
       def each_subary_at_dims_with_index( *dims )
 	if dims.min<0 || dims.max>=rank
 	  raise ArguemntError,"Invalid dims #{dims.inspect} for #{rank}D array"
@@ -157,7 +147,7 @@ end
 
 if __FILE__ == $0
   require "narray"
-  class NArray
+  class NArray   # :nodoc:
     include NumRu::Misc::MD_Iterators
   end
   na = NArray.int(10,2,2,2).indgen!

data/lib/numru/misc/misc.rb

@@ -1,98 +1,87 @@
-=begin
-= module NumRu::Misc
-
-== Overview
-
-Miscellaneous functions and classes to facilitate programming.
-
-== Index
-
-CLASSES
-
-* ((<class KeywordOpt|URL:keywordopt.html>))
-  to support keyward arguments with default values.
-* ((<class NArray (enhancement of NArray made by M Tanaka)|URL:narray_ext.html>))
-
-MODULES
-
-* ((<module MD_Iterators|URL:md_iterators.html>)) A Mixin for classes with
-  multi-dimension indexing support (such as NArray).
-* ((<module EMath|URL:emath.html>)) 
-  To be included instead of the Math predefined module (or NMath in NArray).
-  Unlike Math and NMath, EMath handles unknown classes by calling its
-  native instance method (assuming the same name).
-
-
-MODULE FUNCTIONS
-
-* ((<check_shape_consistency>))
-
-== Module functions
----check_shape_consistency(cshapes, *args)
-     Check the consistency of array shapes (multi-dim such as NArray).
-     Exception is raised if inconsistent.
-
-     ARGUMENTS
-     * cshapes (String) : description of the shapes of the args.
-       Delimited by one-or-more spaces between arrays,
-       and the shape of each array is delimited by a comma. The lengths are 
-       expressed with string names as identifiers (in that case, length 
-       values are unquestioned) or specified as positive integers.
-       Use '..' or '...' for repetition of the last shape.
-       See EXAMPLES below.
-
-     * args (multi-dim arrays such as NArray): arrays to be checked
-
-     RETURN VALUE
-     * nil
-
-     POSSIBLE EXCEPTIONS
-     * exception is raised if cshapes and args are inconsistent:
-       
-       * RuntimeError, if the arrays do not have shapes specified by cshapes.
-
-       * ArgeumentError, if the number of args are inconsistent with cshapes. 
-         This is likely a coding error of the user.
-
-     EXAMPLES
-
-     *  to check whether three arrays u, v, and w are shaped as
-        u[nx], v[ny], and w[nx,ny], where nx and ny are any integer:
-
-           NumRu::Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
-
-        Or equivalently,
-
-           NumRu::Misc.check_shape_consistency('m  n  m,n',u,v,w)
-
-        because actual strings does not matter.
-
-     * To specify fixed lengths, use integers instead of names:
-
-           NumRu::Misc.check_shape_consistency('4  n  4,n',u,v,w)
-
-       In this case, u,v,w must have shapes [4], [ny], and [4,ny],
-       where ny is any length.
-
-     * Use '..' or '...' to repeat the same shape:
-
-           NumRu::Misc.check_shape_consistency('nx,ny ...',u,v,w)
-
-       This ensures that u, v, and w are 2D arrays with the same shape.
-       Note: '..' and '...' are the same, so you can use whichever you like.
-
-=end
-
 require "narray"
 
 module NumRu
+
+  # == Overview
+  # 
+  # Miscellaneous functions and classes to facilitate programming.
+  # 
+  # == Index
+  # 
+  # CLASSES
+  # 
+  # * class KeywordOpt : supports keyword arguments with default values.
+  # * class NArray (http://masa16.github.io/narray/index.ja.html) : used in EMath
+  # 
+  # MODULES
+  # 
+  # * module MD_Iterators : A Mixin for classes with
+  #   multi-dimension indexing support (such as NArray).
+  # * module EMath :
+  #   To be included instead of the Math predefined module (or NMath in NArray).
+  #   Unlike Math and NMath, EMath handles unknown classes by calling its
+  #   native instance method (assuming the same name).
+  # 
+  # 
+
    module Misc
       module_function
 
+      #  Check the consistency of array shapes (multi-dim such as NArray).
+      #  Exception is raised if inconsistent.
+      # 
+      #  ARGUMENTS
+      #  * cshapes (String) : description of the shapes of the args.
+      #    Delimited by one-or-more spaces between arrays,
+      #    and the shape of each array is delimited by a comma. The lengths are 
+      #    expressed with string names as identifiers (in that case, length 
+      #    values are unquestioned) or specified as positive integers.
+      #    Use '..' or '...' for repetition of the last shape.
+      #    See EXAMPLES below.
+      # 
+      #  * args (multi-dim arrays such as NArray): arrays to be checked
+      # 
+      #  RETURN VALUE
+      #  * nil
+      # 
+      #  POSSIBLE EXCEPTIONS
+      #  * exception is raised if cshapes and args are inconsistent:
+      #    
+      #    * RuntimeError, if the arrays do not have shapes specified by cshapes.
+      # 
+      #    * ArgeumentError, if the number of args are inconsistent with cshapes. 
+      #      This is likely a coding error of the user.
+      # 
+      #  EXAMPLES
+      # 
+      #  *  to check whether three arrays u, v, and w are shaped as
+      #     u[nx], v[ny], and w[nx,ny], where nx and ny are any integer:
+      # 
+      #        NumRu::Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
+      # 
+      #     Or equivalently,
+      # 
+      #        NumRu::Misc.check_shape_consistency('m  n  m,n',u,v,w)
+      # 
+      #     because actual strings does not matter.
+      # 
+      #  * To specify fixed lengths, use integers instead of names:
+      # 
+      #        NumRu::Misc.check_shape_consistency('4  n  4,n',u,v,w)
+      # 
+      #    In this case, u,v,w must have shapes [4], [ny], and [4,ny],
+      #    where ny is any length.
+      # 
+      #  * Use '..' or '...' to repeat the same shape:
+      # 
+      #        NumRu::Misc.check_shape_consistency('nx,ny ...',u,v,w)
+      # 
+      #    This ensures that u, v, and w are 2D arrays with the same shape.
+      #    Note: '..' and '...' are the same, so you can use whichever you like.
       def check_shape_consistency(cshapes, *args)
 	 ranks = Array.new
 	 elm2idx = Hash.new
-	 spl = cshapes.split(' +')
+	 spl = cshapes.split(' ')
 	 if spl.length >= 2 && /^\.\.\.?$/ =~ spl[-1]  # '..' or '...'
             ((spl.length-1)...args.length).each{|i|
 	       spl[i]=spl[i-1]
@@ -156,7 +145,7 @@ if __FILE__ == $0
    begin
       Misc.check_shape_consistency('6 ny 6,ny',u,v,w)
    rescue
-      puts "  exception raised as expected\n"+$!
+      puts "  exception raised as expected\n#{$!}"
       puts ' OK'
    end
 
@@ -171,7 +160,7 @@ if __FILE__ == $0
       w = NArray.float(3,5)
       Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
    rescue
-      puts "  exception raised as expected\n"+$!
+      puts "  exception raised as expected\n#{$!}"
       puts ' OK'
    end
 
@@ -182,7 +171,7 @@ if __FILE__ == $0
       w = NArray.float(3,5)
       Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
    rescue
-      puts "  exception raised as expected\n"+$!
+      puts "  exception raised as expected\n#{$!}"
       puts ' OK'
    end
 

data/lib/numru/misc/version.rb

@@ -0,0 +1,5 @@
+module NumRu
+   module Misc
+     VERSION =  "0.1.2"
+   end
+end

data/numru-misc.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+require "rubygems" unless defined?(Gem)
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "numru/misc"
+
+Gem::Specification.new do |spec|
+  spec.name          = "numru-misc"
+  spec.version       = NumRu::Misc::VERSION
+  spec.authors     = ["Takeshi Horinouchi"]
+  spec.email       = ["horinout@gfd-dennou.org"]
+
+  spec.summary     = %q{Collection of miscellaneous functions and classes to facilitate programming.}
+  spec.description = %q{Miscellaneous functions and classes to help Ruby programming. To be used in other NumRu libraries.}
+  spec.homepage    = 'http://www.gfd-dennou.org/arch/ruby/products/numru-misc/' 
+  spec.licenses       = ["BSD-2-Clause"]
+
+  spec.files         = `git ls-files -z`.split("\x0") + ["ChangeLog"]
+  #spec.test_files    = spec.files.grep(%r{^demo/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 1.6")
+  spec.add_runtime_dependency(%q<narray>, [">= 0.5.5"])
+end

metadata

@@ -1,97 +1,83 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: numru-misc
-version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Takeshi Horinouchi
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-02-20 00:00:00 +09:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2015-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: narray
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.5
   type: :runtime
-  version_requirements: *id001
-description: Miscellaneous functions and classes to help Ruby programming. To be used in other NumRu libraries.
-email: 
-- eriko@gfd-dennou.org
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.5
+description: Miscellaneous functions and classes to help Ruby programming. To be used
+  in other NumRu libraries.
+email:
+- horinout@gfd-dennou.org
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
+- .ChangeLog.until201414
+- .gitignore
+- Gemfile
+- LICENSE.txt
 - Rakefile
+- doc/emath.html
+- doc/index.html
+- doc/keywordopt.html
+- doc/md_iterators.html
+- doc/misc.html
 - install.rb
-- LICENSE.txt
-- ChangeLog
-- makedoc.csh
+- lib/numru/misc.rb
+- lib/numru/misc/emath.rb
 - lib/numru/misc/keywordopt.rb
 - lib/numru/misc/md_iterators.rb
 - lib/numru/misc/misc.rb
-- lib/numru/misc/emath.rb
-- lib/numru/misc.rb
-- doc/emath.html
-- doc/md_iterators.html
-- doc/keywordopt.html
-- doc/misc.html
-- doc/index.html
-has_rdoc: true
+- lib/numru/misc/version.rb
+- makedoc.csh
+- numru-misc.gemspec
+- ChangeLog
 homepage: http://www.gfd-dennou.org/arch/ruby/products/numru-misc/
-licenses: 
-- Takeshi Horinouchi
-- GFD Dennou Club
+licenses:
+- BSD-2-Clause
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 1
-      - 6
-      version: "1.6"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '1.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Collection of miscellaneous functions and classes to facilitate programming.
 test_files: []
-