carray 1.3.6 → 1.5.3

data/{carray_loop.c → ext/carray_loop.c}

@@ -3,39 +3,37 @@
   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
 
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
 
 static VALUE
-rb_ca_s_each_index_internal (int rank, VALUE *dim, uint8_t irank, VALUE ridx)
+rb_ca_s_each_index_internal (int ndim, VALUE *dim, uint8_t indim, VALUE ridx)
 {
   volatile VALUE ret = Qnil;
-  int32_t is_leaf = (irank == rank - 1);
+  int32_t is_leaf = (indim == ndim - 1);
   ca_size_t i;
 
-  if ( NIL_P(dim[irank]) ) {
-    rb_ary_store(ridx, irank, Qnil);
+  if ( NIL_P(dim[indim]) ) {
+    rb_ary_store(ridx, indim, Qnil);
     if ( is_leaf ) {
       ret = rb_yield_splat(rb_obj_clone(ridx));
     }
     else {
-      ret = rb_ca_s_each_index_internal(rank, dim, irank+1, ridx);
+      ret = rb_ca_s_each_index_internal(ndim, dim, indim+1, ridx);
     }
   }
   else {
-    for (i=0; i<NUM2SIZE(dim[irank]); i++) {
-      rb_ary_store(ridx, irank, SIZE2NUM(i));
+    for (i=0; i<NUM2SIZE(dim[indim]); i++) {
+      rb_ary_store(ridx, indim, SIZE2NUM(i));
       if ( is_leaf ) {
         ret = rb_yield_splat(rb_obj_clone(ridx));
       }
       else {
-        ret = rb_ca_s_each_index_internal(rank, dim, irank+1, ridx);
+        ret = rb_ca_s_each_index_internal(ndim, dim, indim+1, ridx);
       }
     }
   }
@@ -43,38 +41,32 @@ rb_ca_s_each_index_internal (int rank, VALUE *dim, uint8_t irank, 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
-rb_ca_s_each_index (int rank, VALUE *dim, VALUE self)
+rb_ca_s_each_index (int ndim, VALUE *dim, VALUE self)
 {
-  volatile VALUE ridx = rb_ary_new2(rank);
+  volatile VALUE ridx = rb_ary_new2(ndim);
 #if RUBY_VERSION_CODE >= 190
-  RETURN_ENUMERATOR(self, rank, dim);
+  RETURN_ENUMERATOR(self, ndim, dim);
 #endif
-  return rb_ca_s_each_index_internal(rank, dim, 0, ridx);
+  return rb_ca_s_each_index_internal(ndim, dim, 0, ridx);
 }
 
 /* ------------------------------------------------------------------- */
 
-/* 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
@@ -145,7 +132,7 @@ rb_ca_each_index_internal (VALUE self, int8_t level, VALUE ridx)
   CArray *ca;
   ca_size_t i;
   Data_Get_Struct(self, CArray, ca);
-  if ( level == ca->rank - 1 ) {
+  if ( level == ca->ndim - 1 ) {
     for (i=0; i<ca->dim[level]; i++) {
       rb_ary_store(ridx, level, SIZE2NUM(i));
       ret = rb_yield_splat(rb_obj_clone(ridx));
@@ -160,39 +147,33 @@ 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
 rb_ca_each_index (VALUE self)
 {
   volatile VALUE ridx;
-  int8_t rank = NUM2INT(rb_ca_rank(self));
-  ridx = rb_ary_new2(rank);
+  int8_t ndim = NUM2INT(rb_ca_ndim(self));
+  ridx = rb_ary_new2(ndim);
 #if RUBY_VERSION_CODE >= 190
   RETURN_ENUMERATOR(self, 0, 0);
 #endif
   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
@@ -225,7 +206,7 @@ rb_ca_each_with_index_internal (VALUE self,
   CArray *ca;
   ca_size_t i;
   Data_Get_Struct(self, CArray, ca);
-  if ( level == ca->rank - 1 ) {
+  if ( level == ca->ndim - 1 ) {
     for (i=0; i<ca->dim[level]; i++) {
       idx[level] = i;
       rb_ary_store(ridx, level, SIZE2NUM(i));
@@ -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
@@ -256,12 +235,12 @@ rb_ca_each_with_index (VALUE self)
 {
   volatile VALUE ridx, ret;
   ca_size_t idx[CA_RANK_MAX];
-  int8_t  rank = NUM2INT(rb_ca_rank(self));
+  int8_t  ndim = NUM2INT(rb_ca_ndim(self));
 #if RUBY_VERSION_CODE >= 190
   RETURN_ENUMERATOR(self, 0, 0);
 #endif
   rb_ca_modify(self);
-  ridx = rb_ary_new2(rank);
+  ridx = rb_ary_new2(ndim);
   ret  = rb_ca_each_with_index_internal(self, 0, idx, ridx);
   return ret;
 }
@@ -274,7 +253,7 @@ rb_ca_map_with_index_bang_internal (VALUE self,
   CArray *ca;
   ca_size_t i;
   Data_Get_Struct(self, CArray, ca);
-  if ( level == ca->rank - 1 ) {
+  if ( level == ca->ndim - 1 ) {
     volatile VALUE obj;
     for (i=0; i<ca->dim[level]; i++) {
       idx[level] = i;
@@ -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
@@ -307,14 +284,14 @@ rb_ca_map_with_index_bang (VALUE self)
   volatile VALUE ridx;
   CArray *ca;
   ca_size_t idx[CA_RANK_MAX];
-  int8_t  rank = NUM2INT(rb_ca_rank(self));
+  int8_t  ndim = NUM2INT(rb_ca_ndim(self));
 #if RUBY_VERSION_CODE >= 190
   RETURN_ENUMERATOR(self, 0, 0);
 #endif
   rb_ca_modify(self);
   Data_Get_Struct(self, CArray, ca);
   ca_attach(ca);
-  ridx = rb_ary_new2(rank);
+  ridx = rb_ary_new2(ndim);
   rb_ca_map_with_index_bang_internal(self, 0, idx, ridx);
   ca_sync(ca);
   ca_detach(ca);
@@ -329,7 +306,7 @@ rb_ca_map_index_bang_internal (VALUE self,
   CArray *ca;
   ca_size_t i;
   Data_Get_Struct(self, CArray, ca);
-  if ( level == ca->rank - 1 ) {
+  if ( level == ca->ndim - 1 ) {
     volatile VALUE obj;
     for (i=0; i<ca->dim[level]; i++) {
       idx[level] = i;
@@ -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
@@ -361,26 +336,24 @@ rb_ca_map_index_bang (VALUE self)
   volatile VALUE ridx;
   CArray *ca;
   ca_size_t idx[CA_RANK_MAX];
-  int8_t  rank = NUM2INT(rb_ca_rank(self));
+  int8_t  ndim = NUM2INT(rb_ca_ndim(self));
 #if RUBY_VERSION_CODE >= 190
   RETURN_ENUMERATOR(self, 0, 0);
 #endif
   rb_ca_modify(self);
   Data_Get_Struct(self, CArray, ca);
   ca_attach(ca);
-  ridx = rb_ary_new2(rank);
+  ridx = rb_ary_new2(ndim);
   rb_ca_map_index_bang_internal(self, 0, idx, ridx);
   ca_sync(ca);
   ca_detach(ca);
   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/{carray_mask.c → 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
@@ -668,7 +654,7 @@ rb_ca_value_array (VALUE self)
 
   Data_Get_Struct(self, CArray, ca);
 
-  obj = rb_ca_refer_new(self, ca->data_type, ca->rank, ca->dim, ca->bytes, 0);
+  obj = rb_ca_refer_new(self, ca->data_type, ca->ndim, ca->dim, ca->bytes, 0);
   Data_Get_Struct(obj, CArray, co);
 
   ca_set_flag(co, CA_FLAG_VALUE_ARRAY);
@@ -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,7 @@ rb_ca_is_masked (VALUE self)
 
   Data_Get_Struct(self, CArray, ca);
 
-  co = carray_new(CA_BOOLEAN, ca->rank, ca->dim, ca->bytes, NULL);
+  co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);
 
   ca_update_mask(ca);
   if ( ! ca->mask ) {
@@ -799,14 +779,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 +798,7 @@ rb_ca_is_not_masked (VALUE self)
 
   Data_Get_Struct(self, CArray, ca);
 
-  co = carray_new(CA_BOOLEAN, ca->rank, ca->dim, ca->bytes, NULL);
+  co = carray_new(CA_BOOLEAN, ca->ndim, ca->dim, ca->bytes, NULL);
 
   ca_update_mask(ca);
   if ( ! ca->mask ) {
@@ -842,12 +820,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 +834,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,6 +848,15 @@ rb_ca_count_not_masked (VALUE self)
   return SIZE2NUM(ca_count_not_masked(ca));
 }
 
+/* @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
 rb_ca_unmask_method (int argc, VALUE *argv, VALUE self)
 {
@@ -917,15 +900,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
@@ -970,7 +951,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)
@@ -981,13 +966,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
@@ -1062,13 +1045,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
@@ -1168,9 +1149,9 @@ Init_carray_mask ()
   rb_define_method(rb_cCArray, "inherit_mask_replace", 
                                        rb_ca_inherit_mask_replace_method, -1);
 
-/*  These methods go to lib/carray/base.rb. */
-/*  rb_define_method(rb_cCArray, "count_masked",  rb_ca_count_masked, 0); */
-/*  rb_define_method(rb_cCArray, "count_not_masked", rb_ca_count_not_masked, 0); */
+/*  These methods go to lib/carray/mask.rb. */
+/*  def count_masked (*axis); end */
+/*  def count_not_masked (*axis); end */
 
 }