carray 1.5.1 → 1.5.6

data/ext/carray_loop.c

@@ -3,10 +3,8 @@
   carray_loop.c
 
   This file is part of Ruby/CArray extension library.
-  You can redistribute it and/or modify it under the terms of
-  the Ruby Licence.
 
-  Copyright (C) 2005 Hiroki Motoyoshi
+  Copyright (C) 2005-2020 Hiroki Motoyoshi
 
 ---------------------------------------------------------------------------- */
 
@@ -43,18 +41,14 @@ rb_ca_s_each_index_internal (int ndim, VALUE *dim, uint8_t indim, VALUE ridx)
   return ret;
 }
 
-/* rdoc:
-  #  Iterates with the multi-dimensional indeces for the given
-  #  dimension numbers.
-  #
-  #     CArray.each_index(3,2){|i,j| print "(#{i} #{j}) " }
-  #
-  #  produces:
-  #
-  #     (0 0) (0 1) (1 0) (1 1) (2 0) (2 1) (3 0) (3 1)
-  #
-  def CArray.each_index(*argv) # :yields: i0, i1, ...
-  end
+/* @overload each_index (*shape)
+
+(Iterator) Iterates with the multi-dimensional indeces for the given
+dimension numbers.
+
+      CArray.each_index(3,2){|i,j| print "(#{i} #{j}) " }
+      produces:
+      (0 0) (0 1) (1 0) (1 1) (2 0) (2 1) (3 0) (3 1)
 */
 
 static VALUE
@@ -69,12 +63,10 @@ rb_ca_s_each_index (int ndim, VALUE *dim, VALUE self)
 
 /* ------------------------------------------------------------------- */
 
-/* rdoc:
-  class CArray
-    #
-    def each # :yields: v
-    end
-  end
+/* @overload each () {|elem| ... }
+
+(Iterator) Iterates all the elements of the object.
+
 */
 
 static VALUE
@@ -92,12 +84,10 @@ rb_ca_each (VALUE self)
   return ret;
 }
 
-/* rdoc:
-  class CArray
-    #
-    def each_with_addr # :yields: v, addr
-    end
-  end
+/* @overload each_with_addr () {|elem, addr| ... }
+
+(Iterator) Iterates all the elements of the object.
+
 */
 
 static VALUE
@@ -115,12 +105,9 @@ rb_ca_each_with_addr (VALUE self)
   return ret;
 }
 
-/* rdoc:
-  class CArray
-    #
-    def each_addr() # :yields: addr
-    end
-  end
+/* @overload each_addr () {|addr| ... }
+
+(Iterator) Iterates all address of the object.
 */
 
 static VALUE
@@ -160,19 +147,16 @@ rb_ca_each_index_internal (VALUE self, int8_t level, VALUE ridx)
   return ret;
 }
 
-/* rdoc:
-  class CArray
-    # Iterates with the multi-dimensional indeces for the dimension of <i>ca</i>.
-    #
-    #    CArray.int(3,2).each_index(){|i,j| print "(#{i} #{j}) " }
-    #
-    #  <em>produces:</em>
-    #
-    #     (0 0) (0 1) (1 0) (1 1) (2 0) (2 1) (3 0) (3 1)
-    #
-    def each_index # :yields: i0, i1, ...
-    end
-  end
+/* @overload each_index () {|idx| ... }
+
+(Iterator) Iterates all index of the object.
+    
+        CArray.int(3,2).each_index(){|i,j| print "(#{i} #{j}) " }
+    
+      <em>produces:</em>
+    
+         (0 0) (0 1) (1 0) (1 1) (2 0) (2 1) (3 0) (3 1)
+    
 */
 
 static VALUE
@@ -187,12 +171,9 @@ rb_ca_each_index (VALUE self)
   return rb_ca_each_index_internal(self, 0, ridx);
 }
 
-/* rdoc:
-  class CArray
-    #
-    def map! # :yields: v
-    end
-  end
+/* @overload map! () {|elem| ... }
+
+(Iterator, Destructive) Iterates all elements of the object and stores the return from the block to the element.
 */
 
 static VALUE
@@ -243,12 +224,10 @@ rb_ca_each_with_index_internal (VALUE self,
   return ret;
 }
 
-/* rdoc:
-  class CArray
-    # 
-    def each_with_index # :yields: v, idx 
-    end
-  end
+/* @overload each_with_index () {|elem, idx| ... }
+
+[TBD]
+
 */
 
 static VALUE
@@ -293,12 +272,10 @@ rb_ca_map_with_index_bang_internal (VALUE self,
   }
 }
 
-/* rdoc:
-  class CArray
-    #
-    def map_with_index! # :yields: v, idx
-    end
-  end
+/* @overload map_with_index () {|elem, idx| ... }
+
+[TBD]
+
 */
 
 static VALUE
@@ -347,12 +324,10 @@ rb_ca_map_index_bang_internal (VALUE self,
   }
 }
 
-/* rdoc:
-  class CArray
-    #
-    def map_index! # :yields: i0, i1, ...
-    end
-  end
+/* @overload map_index! () {|idx| ... }
+
+[TBD]
+
 */
 
 static VALUE
@@ -375,12 +350,10 @@ rb_ca_map_index_bang (VALUE self)
   return self;
 }
 
-/* rdoc:
-  class CArray
-    #
-    def map_with_addr! # :yields: v, addr
-    end
-  end
+/* @overload map_with_addr! () {|elem, addr| ... }
+
+[TBD]
+
 */
 
 static VALUE
@@ -406,12 +379,10 @@ rb_ca_map_with_addr_bang (VALUE self)
 }
 
 
-/* rdoc:
-  class CArray
-    #
-    def map_addr! # :yields: addr
-    end
-  end
+/* @overload map_addr! () {|addr| ... }
+
+[TBD]
+
 */
 
 static VALUE

data/ext/carray_mask.c

@@ -3,10 +3,8 @@
   carray_mask.c
 
   This file is part of Ruby/CArray extension library.
-  You can redistribute it and/or modify it under the terms of
-  the Ruby Licence.
 
-  Copyright (C) 2005 Hiroki Motoyoshi
+  Copyright (C) 2005-2020 Hiroki Motoyoshi
 
 ---------------------------------------------------------------------------- */
 
@@ -565,12 +563,10 @@ ca_allocate_mask_iterator (int n, ...)
 
 /* ------------------------------------------------------------------- */
 
-/* rdoc:
-  class CArray 
-    # Returns true if self has the mask array.
-    def has_mask?() 
-    end 
-  end
+/* @overload has_mask?
+
+(Masking, Inquiry) 
+Returns true if self has the mask array.
 */
 
 VALUE
@@ -581,12 +577,10 @@ rb_ca_has_mask (VALUE self)
   return ( ca_has_mask(ca) ) ? Qtrue : Qfalse;
 }
 
-/* rdoc:
-  class CArray
-    # Returns true if self has at least one masked element.
-    def any_masked?
-    end
-  end
+/* @overload any_masked?
+
+(Masking, Inquiry) 
+Returns true if self has at least one masked element.
 */
 
 VALUE
@@ -597,12 +591,10 @@ rb_ca_is_any_masked (VALUE self)
   return ( ca_is_any_masked(ca) ) ? Qtrue : Qfalse;
 }
 
-/* rdoc:
-  class CArray
-    # Returns true if all elements of self are masked.
-    def all_masked?
-    end
-  end
+/* @overload all_masked?
+
+(Masking, Inquiry) 
+Returns true if all elements of self are masked.
 */
 
 VALUE
@@ -613,12 +605,10 @@ rb_ca_is_all_masked (VALUE self)
   return ( ca_is_all_masked(ca) ) ? Qtrue : Qfalse;
 }
 
-/* rdoc:
-  class CArray
-    private
-    def create_mask
-    end
-  end
+/* @overload create_mask
+
+(Masking) 
+Creates mask array internally (private method)
 */
 
 static VALUE
@@ -631,12 +621,10 @@ rb_ca_create_mask (VALUE self)
   return Qnil;
 }
 
-/* rdoc:
-  class CArray
-    private
-    def update_mask
-    end
-  end
+/* @overload update_mask
+
+(Masking) 
+Update mask array internally (private method)
 */
 
 /*
@@ -650,14 +638,12 @@ rb_ca_update_mask (VALUE self)
 }
 */
 
-/* rdoc:
-  class CArray
-    # Returns new array which refers the data of <code>self</code>.
-    # The data of masked elements of <code>self</code> can be accessed
-    # via the returned array. The value array can't be set mask.
-    def value ()
-    end
-  end
+/* @overload value
+
+(Masking, Inquiry) 
+Returns new array which refers the data of <code>self</code>.
+The data of masked elements of <code>self</code> can be accessed
+via the returned array. The value array can't be set mask.
 */
 
 VALUE
@@ -676,13 +662,11 @@ rb_ca_value_array (VALUE self)
   return obj;
 }
 
-/* rdoc:
-  class CArray
-    # Returns new array which refers the mask state of <code>self</code>.
-    # The mask array can't be set mask.
-    def mask ()
-    end
-  end
+/* @overload mask
+
+(Masking, Inquiry) 
+Returns new array which refers the mask state of <code>self</code>.
+The mask array can't be set mask.
 */
 
 VALUE
@@ -707,14 +691,12 @@ rb_ca_mask_array (VALUE self)
   }
 }
 
-/* rdoc:
-  class CArray
-    # Asigns <code>new_mask</code> to the mask array of <code>self</code>.
-    # If <code>self</code> doesn't have a mask array, it will be created
-    # before asignment.
-    def mask= (new_mask)
-    end
-  end
+/* @overload mask= (new_mask)
+
+(Mask, Modification) 
+Asigns <code>new_mask</code> to the mask array of <code>self</code>.
+If <code>self</code> doesn't have a mask array, it will be created
+before asignment.
 */    
 
 VALUE
@@ -756,14 +738,12 @@ rb_ca_set_mask (VALUE self, VALUE rval)
   }
 }
 
-/* rdoc:
-  class CArray
-    # Returns new boolean type array of same shape with <code>self</code>.
-    # The returned array has 1 for the masked elements and
-    # 0 for not-masked elements.
-    def is_masked ()
-    end
-  end
+/* @overload is_masked
+
+(Masking, Element-Wise Inquiry) 
+Returns new boolean type array of same shape 
+with <code>self</code>. The returned array has 1 for the masked elements and
+0 for not-masked elements.
 */
 
 VALUE
@@ -777,7 +757,12 @@ rb_ca_is_masked (VALUE self)
 
   Data_Get_Struct(self, CArray, ca);
 
-  co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);
+  if ( ca_is_scalar(ca) ) {
+    co = cscalar_new(CA_BOOLEAN, ca->bytes, NULL);        
+  }
+  else {
+    co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);    
+  }
 
   ca_update_mask(ca);
   if ( ! ca->mask ) {
@@ -799,14 +784,12 @@ rb_ca_is_masked (VALUE self)
   return ca_wrap_struct(co);
 }
 
-/* rdoc:
-  class CArray
-    # Returns new boolean type array of same shape with <code>self</code>.
-    # The returned array has 0 for the masked elements and
-    # 1 for not-masked elements.
-    def is_not_masked ()
-    end
-  end
+/* @overload is_not_masked
+
+(Masking, Element-Wise Inquiry) 
+Returns new boolean type array of same shape with <code>self</code>.
+The returned array has 0 for the masked elements and
+1 for not-masked elements.
 */
 
 VALUE
@@ -820,7 +803,12 @@ rb_ca_is_not_masked (VALUE self)
 
   Data_Get_Struct(self, CArray, ca);
 
-  co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);
+  if ( ca_is_scalar(ca) ) {
+    co = cscalar_new(CA_BOOLEAN, ca->bytes, NULL);        
+  }
+  else {
+    co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);    
+  }
 
   ca_update_mask(ca);
   if ( ! ca->mask ) {
@@ -842,12 +830,10 @@ rb_ca_is_not_masked (VALUE self)
   return ca_wrap_struct(co);
 }
 
-/* rdoc:
-  class CArray
-    # Returns the number of masked elements.
-    def count_masked ()
-    end
-  end
+/* @overload count_masked
+
+(Masking, Statistics)
+Returns the number of masked elements.
 */
 
 VALUE
@@ -858,12 +844,10 @@ rb_ca_count_masked (VALUE self)
   return SIZE2NUM(ca_count_masked(ca));
 }
 
-/* rdoc:
-  class CArray
-    # Returns the number of not-masked elements.
-    def count_not_masked ()
-    end
-  end
+/* @overload count_not_masked
+
+(Masking, Statistics)
+Returns the number of not-masked elements.
 */
 
 VALUE
@@ -874,15 +858,13 @@ rb_ca_count_not_masked (VALUE self)
   return SIZE2NUM(ca_count_not_masked(ca));
 }
 
-/* rdoc:
-  class CArray  
-    # Unmask all elements of the object.
-    # If the optional argument <code>fill_value</code> is given,
-    # the masked elements are filled by <code>fill_value</code>.
-    # The returned array doesn't have the mask array.
-    def unmask (fill_value=nil)
-    end
-  end
+/* @overload unmask (fill_value = nil)
+
+(Masking, Destructive)
+Unmask all elements of the object.
+If the optional argument <code>fill_value</code> is given,
+the masked elements are filled by <code>fill_value</code>.
+The returned array doesn't have the mask array.
 */
 
 static VALUE
@@ -928,15 +910,13 @@ rb_ca_mask_fill (VALUE self, VALUE fval)
   return rb_ca_unmask_method(1, &fval, self);
 }
 
-/* rdoc:
-  class CArray  
-    # Returns new unmasked array.
-    # If the optional argument <code>fill_value</code> is given,
-    # the masked elements are filled by <code>fill_value</code>.
-    # The returned array doesn't have the mask array.
-    def unmask_copy (fill_value=nil)
-    end
-  end
+/* @overload unmask_copy (fill_value = nil)
+
+(Masking, Conversion)
+Returns new unmasked array.
+If the optional argument <code>fill_value</code> is given,
+the masked elements are filled by <code>fill_value</code>.
+The returned array doesn't have the mask array.
 */
 
 static VALUE
@@ -981,7 +961,11 @@ rb_ca_mask_fill_copy (VALUE self, VALUE fval)
   return rb_ca_unmask_copy_method(1, &fval, self);
 }
 
-/* CArray#invert_mask */
+/* @overload invert_mask
+
+(Masking, Destructive)
+Inverts mask state.
+*/
 
 VALUE
 rb_ca_invert_mask (VALUE self)
@@ -992,13 +976,11 @@ rb_ca_invert_mask (VALUE self)
   return self;
 }
 
-/* rdoc:
-  class CArray
-    # Sets the mask array of <code>self</code> by the logical sum of
-    # the mask states of <code>self</code> and arrays given in arguments.
-    def inherit_mask (*argv)
-    end
-  end
+/* @overload inherit_mask (*others):
+
+(Masking, Destructive)
+Sets the mask array of <code>self</code> by the logical sum of
+the mask states of <code>self</code> and arrays given in arguments.
 */
 
 static VALUE
@@ -1073,13 +1055,11 @@ rb_ca_inherit_mask (VALUE self, int n, ...)
   return self;
 }
 
-/* rdoc: 
-  class CArray
-    # Sets the mask array of <code>self</code> by the logical sum of
-    # the mask states of arrays given in arguments.
-    def inherit_mask_replace (*argv)
-    end
-  end
+/* @overload inherit_mask_replace (*others)
+Sets the mask array of <code>self</code> by the logical sum of
+the mask states of arrays given in arguments.
+This method does not inherit the mask states of itself (different point 
+from `CArray#inherit_mask`)
 */
 
 static VALUE