carray 1.4.0 → 1.5.5

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

@@ -3,10 +3,8 @@
   carray_generate.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
 
 ---------------------------------------------------------------------------- */
 
@@ -15,17 +13,11 @@
 
 /* ----------------------------------------------------------------- */
 
-/* rdoc:
-  class CArray
-    # Sets true at the given index for the boolean array and returns self.
-    # It accept the arguments same as for CArray#[].
-    def set (*argv)
-    end
-    # Sets false at the given index for the boolean array and returns self.
-    # It accept the arguments same as for CArray#[].
-    def unset (*argv)
-    end
-  end
+/* @overload set (*idx)
+
+(Boolean, Modification)
+Sets true at the given index for the boolean array and returns self.
+It accept the arguments same as for CArray#[].
 */
 
 static VALUE
@@ -40,6 +32,13 @@ rb_ca_boolean_set (int argc, VALUE *argv, VALUE self)
   return self;
 }
 
+/* @overload unset (*idx)
+
+(Boolean, Modification)
+Sets false at the given index for the boolean array and returns self.
+It accept the arguments same as for CArray#[].
+*/
+
 static VALUE
 rb_ca_boolean_unset (int argc, VALUE *argv, VALUE self)
 {
@@ -54,12 +53,10 @@ rb_ca_boolean_unset (int argc, VALUE *argv, VALUE self)
 
 /* ----------------------------------------------------------------- */
 
-/* rdoc:
-  class CArray
-    # Returns the 1d index array for non-zero elements of self
-    def where
-    end
-  end
+/* @overload where
+
+(Conversion)
+Returns the 1d index array for non-zero elements of self
 */
 
 VALUE
@@ -245,8 +242,13 @@ rb_ca_seq_bang_object (int argc, VALUE *argv, VALUE self)
   return self;
 }
 
-/* rdoc:
-  class CArray
+/* @overload seq! (init_val=0, step=1) {|elem| ... }
+
+(Conversion, Destructive)
+Generates sequential data with initial value `init_val` 
+and step value `step`. For object array, if the second argument
+is Symbol object, it will be interpreted as stepping method and 
+it is called for the last element in each step.
     # call-seq:
     #   seq (init_val=0, step=1)
     #   seq (init_val=0, step=1) {|x| ... }
@@ -258,12 +260,6 @@ rb_ca_seq_bang_object (int argc, VALUE *argv, VALUE self)
     # is Symbol object, it will be interpreted as stepping method and 
     # it is called for the last element in each step.
     #
-    def seq (init_val=0, step=1)
-    end
-    # 
-    def seq! (init_val=0, step=1)
-    end
-  end
 */
 
 static VALUE
@@ -339,6 +335,26 @@ rb_ca_seq_bang_method (int argc, VALUE *argv, VALUE self)
   return self;
 }
 
+/* @overload seq (init_val=0, step=1) {|elem| ... }
+
+(Conversion)
+Generates sequential data with initial value `init_val` 
+and step value `step`. For object array, if the second argument
+is Symbol object, it will be interpreted as stepping method and 
+it is called for the last element in each step.
+    # call-seq:
+    #   seq (init_val=0, step=1)
+    #   seq (init_val=0, step=1) {|x| ... }
+    #   seq (init_val=0, step=A_symbol)            ### for object array
+    #   seq (init_val=0, step=A_symbol) {|x| ...}  ### for object array
+    #
+    # Generates sequential data with initial value `init_val` 
+    # and step value `step`. For object array, if the second argument
+    # is Symbol object, it will be interpreted as stepping method and 
+    # it is called for the last element in each step.
+    #
+*/
+
 static VALUE
 rb_ca_seq_method (int argc, VALUE *argv, VALUE self)
 {
@@ -456,15 +472,10 @@ ca_swap_bytes (char *ptr, ca_size_t bytes, ca_size_t elements)
 
 }
 
-/* rdoc:
-  class CArray
-    # Swaps the byte order of each element.
-    def swap_bytes
-    end
-    # 
-    def swap_bytes!
-    end
-  end
+/* @overload swap_bytes!
+
+(Conversion, Destructive)
+Swaps the byte order of each element.
 */
 
 VALUE
@@ -553,6 +564,12 @@ rb_ca_swap_bytes_bang (VALUE self)
   return self;
 }
 
+/* @overload swap_bytes
+
+(Conversion)
+Swaps the byte order of each element.
+*/
+
 VALUE
 rb_ca_swap_bytes (VALUE self)
 {
@@ -664,20 +681,17 @@ rb_ca_swap_bytes (VALUE self)
           }                                                          \
         }                                                            \
       }                                                              \
-    }                                                              \    
+    }                                                                \
   }
 
-/* rdoc:
-  class CArray
-    # trims the data into the range between min and max. If `fill_value`
-    # is given, the element out of the range between min and max is filled
-    # by `fill_value`
-    def trim (min, max, fill_value=nil)
-    end
-    #
-    def trim! (min, max, fill_value=nil)
-    end
-  end
+
+
+/* @overload trim! (min, max, fill_value=nil)
+
+(Conversion)
+Trims the data into the range between min and max. If `fill_value`
+is given, the element out of the range between min and max is filled
+by `fill_value`
 */
 
 static VALUE
@@ -720,6 +734,14 @@ rb_ca_trim_bang (int argc, VALUE *argv, VALUE self)
   return self;
 }
 
+/* @overload trim (min, max, fill_value=nil)
+
+(Conversion)
+Trims the data into the range between min and max. If `fill_value`
+is given, the element out of the range between min and max is filled
+by `fill_value`
+*/
+
 static VALUE
 rb_ca_trim (int argc, VALUE *argv, VALUE self)
 {
@@ -727,7 +749,6 @@ rb_ca_trim (int argc, VALUE *argv, VALUE self)
   return rb_ca_trim_bang(argc, argv, out);
 }
 
-
 void
 Init_carray_generate ()
 {

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

@@ -3,10 +3,8 @@
   carray_iterator.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
 
 ---------------------------------------------------------------------------- */
 
@@ -15,19 +13,19 @@
 VALUE rb_cCAIterator;
 
 int8_t
-ca_iter_rank (VALUE self)
+ca_iter_ndim (VALUE self)
 {
-  int8_t rank;
+  int8_t ndim;
   if ( TYPE(self) == T_DATA ) {
     CAIterator *it;
     Data_Get_Struct(self, CAIterator, it);
-    rank = it->rank;
+    ndim = it->ndim;
   }
   else {
-    VALUE rrank = rb_ivar_get(self, rb_intern("@rank"));
-    rank = (int8_t) NUM2LONG(rrank);
+    VALUE rndim = rb_ivar_get(self, rb_intern("@ndim"));
+    ndim = (int8_t) NUM2LONG(rndim);
   }
-  return rank;
+  return ndim;
 }
 
 void
@@ -37,16 +35,16 @@ ca_iter_dim (VALUE self, ca_size_t *dim)
   if ( TYPE(self) == T_DATA ) {
     CAIterator *it;
     Data_Get_Struct(self, CAIterator, it);
-    for (i=0; i<it->rank; i++) {
+    for (i=0; i<it->ndim; i++) {
       dim[i] = it->dim[i];
     }
   }
   else {
-    VALUE rrank = rb_ivar_get(self, rb_intern("@rank"));
+    VALUE rndim = rb_ivar_get(self, rb_intern("@ndim"));
     VALUE rdim  = rb_ivar_get(self, rb_intern("@dim"));
-    int8_t rank;
-    rank = (int8_t) NUM2INT(rrank);
-    for (i=0; i<rank; i++) {
+    int8_t ndim;
+    ndim = (int8_t) NUM2INT(rndim);
+    for (i=0; i<ndim; i++) {
       dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
     }
   }
@@ -60,16 +58,16 @@ ca_iter_elements (VALUE self)
     CAIterator *it;
     Data_Get_Struct(self, CAIterator, it);
     elements = 1;
-    for (i=0; i<it->rank; i++) {
+    for (i=0; i<it->ndim; i++) {
       elements *= it->dim[i];
     }
   }
   else {
-    VALUE rrank = rb_ivar_get(self, rb_intern("@rank"));
+    VALUE rndim = rb_ivar_get(self, rb_intern("@ndim"));
     VALUE rdim  = rb_ivar_get(self, rb_intern("@dim"));
-    int8_t rank = (int8_t) NUM2INT(rrank);
+    int8_t ndim = (int8_t) NUM2INT(rndim);
     elements = 1;
-    for (i=0; i<rank; i++) {
+    for (i=0; i<ndim; i++) {
       elements *= NUM2SIZE(rb_ary_entry(rdim, i));
     }
   }
@@ -119,10 +117,10 @@ ca_iter_kernel_at_index (VALUE self, ca_size_t *idx, VALUE rref)
   }
   else {
     VALUE vidx;
-    int8_t rank = ca_iter_rank(self);
+    int8_t ndim = ca_iter_ndim(self);
     int i;
-    vidx = rb_ary_new2(rank);
-    for (i=0; i<rank; i++) {
+    vidx = rb_ary_new2(ndim);
+    for (i=0; i<ndim; i++) {
       rb_ary_store(vidx, i, SIZE2NUM(idx[i]));
     }
     rker = rb_funcall(self, rb_intern("kernel_at_index"), 2,
@@ -161,10 +159,10 @@ ca_iter_kernel_move_to_index (VALUE self, ca_size_t *idx, VALUE rref)
   }
   else {
     VALUE vidx;
-    int8_t rank = ca_iter_rank(self);
+    int8_t ndim = ca_iter_ndim(self);
     int i;
-    vidx = rb_ary_new2(rank);
-    for (i=0; i<rank; i++) {
+    vidx = rb_ary_new2(ndim);
+    for (i=0; i<ndim; i++) {
       rb_ary_store(vidx, i, SIZE2NUM(idx[i]));
     }
     rker = rb_funcall(self, rb_intern("kernel_move_to_index"), 2,
@@ -188,17 +186,17 @@ ca_iter_prepare_output (VALUE self, VALUE rtype, VALUE rbytes)
   if ( TYPE(self) == T_DATA ) {
     CAIterator *it;
     Data_Get_Struct(self, CAIterator, it);
-    co = carray_new_safe(data_type, it->rank, it->dim, bytes, NULL);
+    co = carray_new_safe(data_type, it->ndim, it->dim, bytes, NULL);
   }
   else {
-    VALUE rrank = rb_ivar_get(self, rb_intern("@rank"));
+    VALUE rndim = rb_ivar_get(self, rb_intern("@ndim"));
     VALUE rdim  = rb_ivar_get(self, rb_intern("@dim"));
-    int8_t rank = NUM2LONG(rrank);
+    int8_t ndim = NUM2LONG(rndim);
     ca_size_t dim[CA_RANK_MAX];
-    for (i=0; i<rank; i++) {
+    for (i=0; i<ndim; i++) {
       dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
     }
-    co = carray_new_safe(data_type, rank, dim, bytes, NULL);
+    co = carray_new_safe(data_type, ndim, dim, bytes, NULL);
   }
 
   obj = ca_wrap_struct(co);
@@ -209,21 +207,21 @@ ca_iter_prepare_output (VALUE self, VALUE rtype, VALUE rbytes)
 
 /* -------------------------------------------------------------------- */
 
-/* rdoc:
+/* yard:
   class CAIterator
-    def rank
+    def ndim
     end
   end
 */
 
 
 VALUE
-rb_ca_iter_rank (VALUE self)
+rb_ca_iter_ndim (VALUE self)
 {
-  return LONG2NUM(ca_iter_rank(self));
+  return LONG2NUM(ca_iter_ndim(self));
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def dim
     end
@@ -235,17 +233,17 @@ rb_ca_iter_dim (VALUE self)
 {
   VALUE rdim;
   ca_size_t dim[CA_RANK_MAX];
-  int8_t rank = ca_iter_rank(self);
+  int8_t ndim = ca_iter_ndim(self);
   int i;
   ca_iter_dim(self, dim);
-  rdim = rb_ary_new2(rank);
-  for (i=0; i<rank; i++) {
+  rdim = rb_ary_new2(ndim);
+  for (i=0; i<ndim; i++) {
     rb_ary_store(rdim, i, SIZE2NUM(dim[i]));
   }
   return rdim;
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def elements
     end
@@ -258,7 +256,7 @@ rb_ca_iter_elements (VALUE self)
   return SIZE2NUM(ca_iter_elements(self));
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def reference
     end
@@ -271,7 +269,7 @@ rb_ca_iter_reference (VALUE self)
   return ca_iter_reference(self);
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def kernel_at_addr
     end
@@ -289,7 +287,7 @@ rb_ca_iter_kernel_at_addr (int argc, VALUE *argv, VALUE self)
   return ca_iter_kernel_at_addr(self, NUM2SIZE(raddr), rcarray);
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def kernel_at_index
     end
@@ -301,7 +299,7 @@ rb_ca_iter_kernel_at_index (int argc, VALUE *argv, VALUE self)
 {
   volatile VALUE rindex, rcarray;
   ca_size_t idx[CA_RANK_MAX];
-  int8_t  rank = ca_iter_rank(self);
+  int8_t  ndim = ca_iter_ndim(self);
   int i;
 
   rb_scan_args(argc, argv, "11", (VALUE *) &rindex, (VALUE *) &rcarray);
@@ -310,14 +308,14 @@ rb_ca_iter_kernel_at_index (int argc, VALUE *argv, VALUE self)
     rcarray = rb_ca_iter_reference(self);
   }
 
-  for (i=0; i<rank; i++) {
+  for (i=0; i<ndim; i++) {
     idx[i] = NUM2SIZE(rb_ary_entry(rindex, i));
   }
 
   return ca_iter_kernel_at_index(self, idx, rcarray);
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def kernel_move_to_addr
     end
@@ -330,7 +328,7 @@ rb_ca_iter_kernel_move_to_addr (VALUE self, VALUE raddr, VALUE rker)
   return ca_iter_kernel_move_to_addr(self, NUM2SIZE(raddr), rker);
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def kernel_move_to_index
     end
@@ -341,17 +339,17 @@ VALUE
 rb_ca_iter_kernel_move_to_index (VALUE self, VALUE rindex, VALUE rker)
 {
   ca_size_t idx[CA_RANK_MAX];
-  int8_t  rank = ca_iter_rank(self);
+  int8_t  ndim = ca_iter_ndim(self);
   int i;
 
-  for (i=0; i<rank; i++) {
+  for (i=0; i<ndim; i++) {
     idx[i] = NUM2SIZE(rb_ary_entry(rindex, i));
   }
 
   return ca_iter_kernel_move_to_index(self, idx, rker);
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def prepare_output
     end
@@ -371,7 +369,7 @@ rb_ca_iter_prepare_output (int argc, VALUE *argv, VALUE self)
 
 /* -------------------------------------------------------------------- */
 
-/* rdoc:
+/* yard:
   class CAIterator
     def calculate
     end
@@ -470,7 +468,7 @@ rb_ca_iter_calculate (int argc, VALUE *argv, VALUE self)
   return routput;
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def filter
     end
@@ -501,7 +499,7 @@ rb_ca_iter_filter (int argc, VALUE *argv, VALUE self)
   argc--;
   argv++;
 
-  co = carray_new(data_type, cr->rank, cr->dim, 0, NULL);
+  co = carray_new(data_type, cr->ndim, cr->dim, 0, NULL);
   routput = ca_wrap_struct(co);
 
   if ( NIL_P(argv[0]) ) {
@@ -547,7 +545,7 @@ rb_ca_iter_filter (int argc, VALUE *argv, VALUE self)
   return routput;
 }
 
-/* rdoc:
+/* yard:
   class CAIterator
     def evaluate
     end
@@ -606,8 +604,10 @@ Init_carray_iterator ()
 {
   rb_cCAIterator = rb_define_class("CAIterator", rb_cObject);
 
-  rb_define_method(rb_cCAIterator, "rank",      rb_ca_iter_rank,      0);
+  rb_define_method(rb_cCAIterator, "ndim",      rb_ca_iter_ndim,      0);
+  rb_define_method(rb_cCAIterator, "rank",      rb_ca_iter_ndim,      0); /* alias */
   rb_define_method(rb_cCAIterator, "dim",       rb_ca_iter_dim,       0);
+  rb_define_method(rb_cCAIterator, "shape",     rb_ca_iter_dim,       0); /* alias */
   rb_define_method(rb_cCAIterator, "elements",  rb_ca_iter_elements,  0);
   rb_define_method(rb_cCAIterator, "reference", rb_ca_iter_reference, 0);