carray 1.5.1 → 1.5.2

data/ext/carray_cast_func.rb

@@ -161,8 +161,7 @@ puts %{
   the Ruby\'s licence.
 
   This file is automatically generated from carray_math.rb.
-
-  Copyright (C) 2005 Hiroki Motoyoshi
+  Copyright (C) 2005-2020 Hiroki Motoyoshi
 
 ---------------------------------------------------------------------------- */
 

data/ext/carray_class.c

@@ -3,22 +3,19 @@
   carray_class.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"
 
-/* rdoc: 
-  # returns the machine endianness.
-  #     CArray.endian #=> 0 (CA_LITTLE_ENDIAN)
-  #     CArray.endian #=> 1 (CA_BIG_ENDIAN)
+/* @overload endian 
 
-  def CArray.endian 
-  end
+(Inquiry) 
+Returns the machine endianness.
+   0 (CA_LITTLE_ENDIAN)
+   1 (CA_BIG_ENDIAN)
 */
 
 static VALUE
@@ -27,12 +24,10 @@ rb_ca_s_endian (VALUE klass)
   return INT2NUM(ca_endian);
 }
 
-/* rdoc:
-  # returns true if the byte order of the architecture is
-  # big endian.
-
-  def CArray.big_endian?
-  end
+/* @overload big_endian?
+  
+(Inquiry) 
+Returns true if the byte order of the architecture is big endian.
 */
 
 static VALUE
@@ -41,12 +36,11 @@ rb_ca_s_big_endian_p (VALUE klass)
   return ( ca_endian == CA_BIG_ENDIAN ) ? Qtrue : Qfalse;
 }
 
-/* rdoc: 
-  # returns true if the byte order of the architecture is
-  # little endian.
+/* @overload little_endian?
 
-  def CArray.little_endian?
-  end
+(Inquiry) 
+Returns true if the byte order of the architecture is
+little endian.
 */
 
 static VALUE
@@ -55,15 +49,15 @@ rb_ca_s_little_endian_p (VALUE klass)
   return ( ca_endian == CA_LITTLE_ENDIAN ) ? Qtrue : Qfalse;
 }
 
-/* rdoc:
-  #  Returns the byte length of an element of the given data type.
-  #  Retruns <code>0</code> if data_type is equal to CA_FIXLEN.
-  #     CArray.sizeof(CA_INT32)  #=> 4
-  #     CArray.sizeof(CA_DOUBLE) #=> 8
-  #     CArray.sizeof(CA_FIXLEN)   #=> 0
+/* @overload sizeof (data_type)
+
+(Inquiry) 
+Returns the byte length of an element of the given data type.
+Retruns <code>0</code> if data_type is equal to CA_FIXLEN.
+     CArray.sizeof(CA_INT32)  #=> 4
+     CArray.sizeof(CA_DOUBLE) #=> 8
+     CArray.sizeof(CA_FIXLEN)   #=> 0
 
-  def CArray.sizeof (data_type)
-  end
 */
 
 static VALUE
@@ -76,11 +70,10 @@ rb_ca_s_sizeof (VALUE klass, VALUE rtype)
 }
 
 
-/* rdoc:
-  #  Returns true if the given data_type indicate the valid data_type.
+/* @overload data_type?(data_type)
 
-  def CArray.data_type?(data_type)
-  end
+(Inquiry) 
+Returns true if the given data_type indicate the valid data_type.
 */
 
 static VALUE
@@ -94,11 +87,10 @@ rb_ca_s_data_type (VALUE klass, VALUE rtype)
   return ca_valid[data_type] == 1 ? Qtrue : Qfalse;
 }
 
-/* rdoc:
-  #  Returns string representaion of the data_type specifier.
+/* @overload data_type_name(data_type)
 
-  def CArray.data_type_name(data_type)
-  end
+(Inquiry) 
+Returns string representaion of the data_type specifier.
 */
 
 

data/ext/carray_conversion.c

@@ -3,10 +3,8 @@
   carray_conversion.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,13 +41,12 @@ rb_ca_to_a_loop (VALUE self, int32_t level, ca_size_t *idx, VALUE ary)
   }
 }
 
-/* rdoc:
-  class CArray
-    # Converts the array to Ruby's array. For higher dimension, 
-    # the array is nested ndim-1 times.
-    def to_a
-    end
-  end
+/* 
+@overload to_a
+
+(Conversion)
+Converts the array to Ruby's array. For higher dimension, 
+the array is nested ndim-1 times.
 */
 
 VALUE
@@ -66,13 +63,12 @@ rb_ca_to_a (VALUE self)
   return ary;
 }
 
-/* rdoc:
-  class CArray
-    # Convert the 
-    def convert (data_type=nil, dim=nil)
-      yield
-    end
-  end
+/* @overload convert (data_type=nil, dim=nil) { |elem| ... }
+
+(Conversion) 
+Returns new array which elements are caluculated 
+in the iteration block. The output array is internally created 
+using `CArray#template` to which the arguments is passed.
 */
 
 static VALUE
@@ -106,12 +102,10 @@ rb_ca_convert (int argc, VALUE *argv, VALUE self)
   return obj;
 }
 
-/* rdoc:
-  class CArray
-    # dumps the value array to the given IO stream
-    def dump_binary(io)
-    end
-  end
+/* @overload dump_binary
+
+(IO) 
+Dumps the value array to the given IO stream
 */
 
 static VALUE
@@ -187,19 +181,10 @@ rb_ca_dump_binary (int argc, VALUE *argv, VALUE self)
   return io;
 }
 
-static VALUE
-rb_ca_dump (int argc, VALUE *argv, VALUE self)
-{
-  rb_warn("CArray#dump will be obsolete, use CArray#dump_binary");
-  return rb_ca_dump_binary(argc, argv, self);
-}
+/* @overload to_s
 
-/* rdoc:
-  class CArray
-    # dumps the value array to a string.
-    def to_s
-    end
-  end
+(Conversion) 
+Dumps the value array to a string.
 */
 
 static VALUE
@@ -208,12 +193,10 @@ rb_ca_to_s (VALUE self)
   return rb_ca_dump_binary(0, NULL, self);
 }
 
-/* rdoc:
-  class CArray
-    # loads the value array from the given IO stream
-    def load_binary (io)
-    end
-  end
+/* @overload load_binary (io)
+
+(IO) 
+Loads the value array from the given IO stream
 */
 
 static VALUE
@@ -256,13 +239,6 @@ rb_ca_load_binary (VALUE self, VALUE io)
   return self;
 }
 
-static VALUE
-rb_ca_load (VALUE self, VALUE io)
-{
-  rb_warn("CArray#load will be obsolete, use CArray#load_binary");
-  return rb_ca_load_binary(self, io);
-}
-
 void *
 ca_to_cptr (void *ap)
 {
@@ -314,13 +290,11 @@ ca_to_cptr (void *ap)
 }
 
 
-/* rdoc:
-  class CArray
-    # Convert the 
-    def convert (data_type=nil, dim=nil)
-      yield
-    end
-  end
+/* @overload str_format (*fmts)
+
+(Conversion) 
+Creates object type array consist of string using the "::format" method.
+The Multiple format strings are given, they are applied cyclic in turn.
 */
 
 
@@ -366,9 +340,15 @@ rb_ca_format (int argc, VALUE *argv, VALUE self)
 }
 
 
-
 #include <time.h>
 
+/* @overload str_strptime (fmt)
+
+(Conversion) 
+Creates object type array consist of Time objects 
+which are created by 'Time.strptime' applied to the elements of the object.
+This method assumes all the elements of the objetct to be String.
+*/
 
 static VALUE
 rb_ca_strptime (VALUE self, VALUE rfmt)
@@ -385,6 +365,7 @@ rb_ca_strptime (VALUE self, VALUE rfmt)
     rb_raise(rb_eRuntimeError, "strptime can be applied only to object type.");
   }
 
+  Check_Type(rfmt, T_STRING);
   fmt = (char *) StringValuePtr(rfmt);
 
   obj = rb_ca_template(self);
@@ -423,6 +404,13 @@ rb_ca_strptime (VALUE self, VALUE rfmt)
   return obj;
 }
 
+/* @overload time_strptime (fmt)
+
+(Conversion) 
+Creates object type array consist of strings
+which are created by 'Time#strftime' applied to the elements of the object.
+This method assumes all the elements of the objetct to be Time or DateTime.
+*/
 
 static VALUE
 rb_ca_strftime (VALUE self, VALUE rfmt)
@@ -463,6 +451,10 @@ rb_ca_strftime (VALUE self, VALUE rfmt)
   return obj;
 }
 
+/* @private
+
+*/
+
 static VALUE 
 rb_test_ca_to_cptr (VALUE self)
 {
@@ -497,10 +489,8 @@ Init_carray_conversion ()
   rb_define_method(rb_cCArray, "to_a", rb_ca_to_a, 0);
   rb_define_method(rb_cCArray, "convert", rb_ca_convert, -1);
 
-  rb_define_method(rb_cCArray, "dump", rb_ca_dump, -1);
   rb_define_method(rb_cCArray, "dump_binary", rb_ca_dump_binary, -1);
   rb_define_method(rb_cCArray, "to_s", rb_ca_to_s, 0);
-  rb_define_method(rb_cCArray, "load", rb_ca_load, 1);
   rb_define_method(rb_cCArray, "load_binary", rb_ca_load_binary, 1);
 
   /* DO NOT define CArray#to_ary, it makes trouble with various situations */
@@ -509,7 +499,7 @@ Init_carray_conversion ()
   rb_define_method(rb_cCArray, "str_format", rb_ca_format, -1); 
 
   rb_define_method(rb_cCArray, "str_strptime", rb_ca_strptime, 1);
-  rb_define_method(rb_cCArray, "str_strftime", rb_ca_strftime, 1);
+  rb_define_method(rb_cCArray, "time_strftime", rb_ca_strftime, 1);
 
   rb_define_method(rb_cCArray, "test_ca_to_cptr", rb_test_ca_to_cptr, 0);
 

data/ext/carray_copy.c

@@ -3,10 +3,8 @@
   carray_copy.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,12 +41,9 @@ ca_copy (void *ap)
   return co;
 }
 
-/* rdoc:
-  class CArray
-    # create CArray object from `self` with same contents includes mask state.
-    def to_ca
-    end
-  end
+/* @overload to_ca
+
+(Copy) Creates CArray object from `self` with same contents includes mask state.
 */
 
 VALUE
@@ -101,15 +96,12 @@ ca_template_safe2 (void *ap, int8_t data_type, ca_size_t bytes)
   }
 }
 
-/* rdoc:
-  class CArray
-    # returns CArray object with same dimension with `self`
-    # The data type of the new carray object can be specified by `data_type`.
-    # For fixlen data type, the option `:bytes` is used to specified the
-    # data length.
-    def template(data_type=self.data_type, options={:bytes=>0})
-    end
-  end
+/* @overload template(data_type=self.data_type, bytes: 0)
+
+(Copy) Returns CArray object with same dimension with `self`
+The data type of the new carray object can be specified by `data_type`.
+For fixlen data type, the option `:bytes` is used to specified the
+data length.
 */
 
 static VALUE
@@ -284,14 +276,10 @@ ca_paste (void *ap, ca_size_t *offset, void *sp)
   ca_detach_n(2, ca, cs);
 }
 
-/* rdoc:
-  class CArray
-    # pastes `ary` to `self` at the index `idx`.
-    # `idx` should be Array object with the length same as `self.ndim`.
-    # `ary` should have same shape with `self`.
-    def paste (idx, ary)
-    end
-  end
+/* @overload paste (idx, ary)
+(Copy) Pastes `ary` to `self` at the index `idx`.
+`idx` should be Array object with the length same as `self.ndim`.
+`ary` should have same shape with `self`.
 */
 
 static VALUE
@@ -402,12 +390,8 @@ ca_clip (void *ap, ca_size_t *offset, void *sp)
   ca_detach_n(2, ca, cs);
 }
 
-/* rdoc:
-  class CArray
-    # clips the data at `idx` from `self` to `ary`.
-    def clip (idx, ary)
-    end
-  end
+/* @overload clip (idx, ary)
+(copy) Clips the data at `idx` from `self` to `ary`.
 */
 
 static VALUE

data/ext/carray_core.c

@@ -3,10 +3,8 @@
   carray_core.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
 
 ---------------------------------------------------------------------------- */
 
@@ -998,10 +996,13 @@ rb_ca_s_ensure_detach (VALUE list)
   return Qnil;
 }
 
-/* rdoc:
-  def CArray.attach(*argv) # :nodoc:
-    yield
-  end
+/* @overload attach (*arrays)
+
+(Internal) Guarantees that the reference memory block is attached.
+The memory block is detached at the end of the block evaluation.
+It is not ensured the syncing the memory block at the end of the block evaluation.
+
+@yield
 */
 
 static VALUE
@@ -1035,10 +1036,13 @@ rb_ca_s_ensure_sync_detach (VALUE list)
   return Qnil;
 }
 
-/* rdoc:
-  def CArray.attach!(*argv) # :nodoc:
-    yield
-  end
+/* @overload attach! (*arrays)
+
+(Internal) Guarantees that the reference memory block is attached.
+The memory block is detached at the end of the block evaluation.
+It is ensured the syncing the memory block at the end of the block evaluation.
+
+@yield
 */
 
 static VALUE
@@ -1065,12 +1069,13 @@ rb_ca_ensure_detach (VALUE self)
   return Qnil;
 }
 
-/* rdoc:
-  class CArray
-    def attach () # :nodoc:
-      yield
-    end
-  end
+/* @overload attach 
+
+(Internal) Guarantees that the reference memory block is attached.
+The memory block is detached at the end of the block evaluation.
+It is ensured the syncing the memory block at the end of the block evaluation.
+
+@yield
 */
 
 static VALUE
@@ -1088,12 +1093,13 @@ rb_ca_ensure_sync_detach (VALUE self)
   return Qnil;
 }
 
-/* rdoc:
-  class CArray
-    def attach! () # :nodoc:
-      yield
-    end
-  end
+/* @overload attach! 
+
+(Internal) Guarantees that the reference memory block is attached.
+The memory block is detached at the end of the block evaluation.
+It is ensured the syncing the memory block at the end of the block evaluation.
+
+@yield
 */
 
 static VALUE
@@ -1104,7 +1110,11 @@ rb_ca_attach_bang (VALUE self)
   return rb_ensure(rb_yield, self, rb_ca_ensure_sync_detach, self);
 }
 
-/* CArray#__attach__ */
+/* @overload __attach__ 
+
+(Internal, DevelopperOnly) Attaches the reference memory block.
+User must call "CArray#__detach__" appropreate timing.
+*/
 
 static VALUE
 rb_ca__attach__ (VALUE self)
@@ -1113,7 +1123,10 @@ rb_ca__attach__ (VALUE self)
   return self;
 }
 
-/* CArray#__sync__ */
+/* @overload __detach__ 
+
+(Internal, DevelopperOnly) Syncs the reference memory block to the parent array.
+*/
 
 static VALUE
 rb_ca__sync__ (VALUE self)
@@ -1123,7 +1136,10 @@ rb_ca__sync__ (VALUE self)
   return self;
 }
 
-/* CArray#__detach__ */
+/* @overload __detach__ 
+
+(Internal, DevelopperOnly) Detaches the reference memory block.
+*/
 
 static VALUE
 rb_ca__detach__ (VALUE self)
@@ -1162,12 +1178,9 @@ rb_ca_data_class_encode (VALUE self, VALUE obj)
 
 /* ------------------------------------------------------------------- */
 
-/* rdoc:
-  class CArray
-    # Returns data class member names
-    def members
-    end
-  end
+/* @overload members
+
+(Inquiry) Returns data class member names
 */
 
 VALUE
@@ -1228,12 +1241,9 @@ rb_ca_field_as_member (VALUE self, VALUE sym)
   }
 }
 
-/* rdoc:
-  class CArray
-    # Returns an array of data class members (fields)
-    def fields
-    end
-  end
+/* @overload fields
+
+(Reference) Returns an array of data class members (fields)
 */
 
 VALUE
@@ -1254,12 +1264,9 @@ rb_ca_fields (VALUE self)
   return list;
 }
 
-/* rdoc:
-  class CArray
-    # Returns an array of data class members (fields) with names specified 
-    def fields_at (*names)
-    end
-  end
+/* @overload fields_at (*names)
+
+Returns an array of data class members (fields) with names specified 
 */
 
 VALUE