autoc 1.2 → 1.3

data/doc/top-level-namespace.html

@@ -103,9 +103,9 @@
 </div>
 
     <div id="footer">
-  Generated on Sat Nov 22 16:58:03 2014 by
+  Generated on Thu Mar 17 13:32:50 2016 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.8.7.6 (ruby-2.1.5).
+  0.8.7.6 (ruby-2.2.4).
 </div>
 
   </body>

data/lib/autoc.rb

@@ -5,6 +5,7 @@
 . {AutoC::Code} generic C multi-source module generator.
 . {AutoC::Collection} strongly-typed data structure generators similar
 to the C++ STL container classes.
+. {AutoC::String} wrapper around the standard C string with string building capability.
 
 == Versioning scheme
 
@@ -21,12 +22,13 @@ Should the major incompatible changes be made, the new release 2.0 will be intro
 
 =end
 module AutoC
-  VERSION = "1.2"
+  VERSION = "1.3"
 end # AutoC
 
 
 require "autoc/code"
 require "autoc/type"
+require "autoc/string"
 require "autoc/collection"
 require "autoc/collection/list"
 require "autoc/collection/queue"

data/lib/autoc/code.rb

@@ -21,7 +21,7 @@ module AutoC
 # Throw NameError is resulting string is not a valid C identifier.
 def self.c_id(obj)
   obj = obj.to_s
-  #raise NameError.new("#{obj} is not a valid C identifier", obj) if (/^[_a-zA-Z]\w*$/ =~ obj).nil?
+  raise NameError.new("'#{obj}' is not a valid C identifier", obj) if (/^[_a-zA-Z]\w*$/ =~ obj).nil?
   obj
 end
 
@@ -50,7 +50,7 @@ class Code
     end
   end
   def source_size
-    s = String.new
+    s = ::String.new
     write_decls(s)
     write_defs(s)
     s.size
@@ -187,6 +187,7 @@ class Module::Header < Module::File
     stream << %$
       #endif
     $
+    stream << "\n" # DigitalMars C in strict ANSI (-A) mode complains about absent empty line at the very end so let's make it happy
   end
   
 end # Header

data/lib/autoc/collection.rb

@@ -72,6 +72,8 @@ WARNING: the collection being iterated *must not* be modified in any way otherwi
 =end
 class Collection < Type
 
+  include Redirecting
+  
   attr_reader :element, :it_ref
   
   def hash; super ^ element.hash end
@@ -86,55 +88,49 @@ class Collection < Type
     super(type_name, visibility)
     @it_ref = "#{it}*"
     @element = Type.coerce(element_type)
-    @ctor = define_function(:ctor, Function::Signature.new([type_ref^:self]))
-    @dtor = define_function(:dtor, Function::Signature.new([type_ref^:self]))
-    @copy = define_function(:copy, Function::Signature.new([type_ref^:dst, type_ref^:src]))
-    @equal = define_function(:equal, Function::Signature.new([type_ref^:lt, type_ref^:rt], :int))
-    @identify = define_function(:identify, Function::Signature.new([type_ref^:self], :size_t))
-    @less = define_function(:less, Function::Signature.new([type_ref^:lt, type_ref^:rt], :int))
-    element_type_check(element)
+    initialize_redirectors
+    element_requirement(element)
   end
   
-  def write_intf_decls(stream, declare, define)
-    # Emit default redirection macros
-    # Unlike other special methods the constructors may have extra arguments
-    # Assume the constructor's first parameter is always a target
-    ctor_ex = ctor.parameters.names[1..-1]
-    ctor_lt = ["self"].concat(ctor_ex).join(',')
-    ctor_rt = ["&self"].concat(ctor_ex).join(',')
-    stream << %$
-      #define _#{ctor}(#{ctor_lt}) #{ctor}(#{ctor_rt})
-      #define _#{dtor}(self) #{dtor}(&self)
-      #define _#{identify}(self) #{identify}(&self)
-      #define _#{copy}(dst,src) #{copy}(&dst,&src)
-      #define _#{equal}(lt,rt) #{equal}(&lt,&rt)
-      #define _#{less}(lt,rt) #{less}(&lt,&rt)
-    $
+  # Normally all collections are expected to provide all special functions
+  # If a collection does not provide specific function it should override the respective method
+  
+  # Collection always has default constructor
+  def constructible?; true end
+
+  # Collection always has constructor
+  def initializable?; true end
+
+  # Collection always has destructor but the element is required to be destructible on its own
+  # because collection destruction incurs destruction of all contained elements
+  def destructible?; true && element.destructible? end
+
+  # Collection always has copy constructor but the element is required to be copyable on its own
+  # because collection copying incurs copying of all contained elements
+  def copyable?; true && element.copyable? end
+
+  # Collection always has equality tester but the element is required to be comparable on its own
+  # because collection comparison incurs comparison of all contained elements
+  def comparable?; true && element.comparable? end
+
+  # So far there are no orderable collections therefore inherit false-returning #orderable? 
+
+  # Collection always has hash calculation function but the element is required to be hashable on its own
+  # because collection comparison incurs hash calculation for all contained elements
+  def hashable?
+    # Since using collection as an element of a hash-based container also requires it to be comparable as well 
+    comparable? && element.hashable?
   end
 
-  def copyable?; super && element.copyable? end
-  
-  def comparable?; super && element.comparable? end
-  
-  def hashable?; super && element.hashable? end
+  def write_intf_decls(stream, declare, define)
+    write_redirectors(stream, declare, define)
+  end
   
   private
   
-  def element_type_check(obj)
+  def element_requirement(obj)
     raise "type #{obj.type} (#{obj}) must be destructible" unless obj.destructible?
     raise "type #{obj.type} (#{obj}) must be copyable" unless obj.copyable?
-    raise "type #{obj.type} (#{obj}) must be comparable" unless obj.comparable?
-    raise "type #{obj.type} (#{obj}) must be hashable" unless obj.hashable?
-  end
-  
-  # @private
-  class Redirector < Function
-    # Redirect call to the specific macro
-    def call(*params) "_#{name}(" + params.join(',') + ')' end
-  end # Redirector
-  
-  def define_function(name, signature)
-    Redirector.new(method_missing(name), signature)
   end
   
 end # Collection

data/lib/autoc/collection/hash_map.rb

@@ -60,7 +60,7 @@ Return non-zero value if map +self+ contains no entries and zero value otherwise
 |
 Return a _copy_ of the element in +self+ bound to a key which is considered equal to the key +key+.
 
-WARNING: +self+ *must* contain such key otherwise the behavior is undefined. See ~type~Contains().
+WARNING: +self+ *must* contain such key otherwise the behavior is undefined. See ~type~ContainsKey().
 
 |*_void_* ~type~Purge(*_Type_* * +self+)
 |
@@ -77,7 +77,7 @@ Return non-zero value on successful put and zero value otherwise.
 If +self+ contains a key which is considered equal to the key +key+,
 remove and destroy that key along with an element bound to it
 and put a new pair built of the _copies_ of +key+ and +value+,
-otherwise simply put a new key/element pair into +self+ in the way of ~type~Put().
+otherwise no nothing.
 
 Return non-zero value if the replacement was actually performed and zero value otherwise.
 
@@ -146,22 +146,18 @@ class HashMap < Collection
     @key = Type.coerce(key_type)
     @entry = UserDefinedType.new(:type => entry, :identify => entryIdentify, :equal => entryEqual, :copy => entryCopy, :dtor => entryDtor)
     @set = HashSet.new(set, @entry, :static)
-    @capability.subtract [:orderable]
-    element_type_check(value)
-    key_type_check(key)
+    element_requirement(value)
+    key_requirement(key)
   end
-  
+
   def copyable?; super && key.copyable? end
   
   def comparable?; super && key.comparable? end
   
-  def hashable?
-    # NOTE : must be in sync with Type#hashable?
-    # No super call here because the map's element need not to be hashable,- only the key must be
-    @capability.include?(:hashable) && comparable? && key.hashable?
-  end
+  def hashable?; super && key.hashable? end
   
   def write_intf_types(stream)
+    super
     stream << %$
       /***
       **** #{type}<#{key.type},#{value.type}> (#{self.class})
@@ -213,6 +209,7 @@ class HashMap < Collection
   end
 
   def write_impls(stream, define)
+    super
     stream << %$
       #define AUTOC_VALID_VALUE 1
       #define AUTOC_VALID_KEY 2
@@ -287,9 +284,8 @@ class HashMap < Collection
         int absent;
         #{assert}(self);
         #{assert}(entry);
-        if((absent = !#{containsKey}(self, entry->key))) {
-          #{@set.put}(&self->entries, *entry);
-        }
+        absent = !#{containsKey}(self, entry->key);
+        if(absent) #{@set.put}(&self->entries, *entry);
         return absent;
       }
       #{define} #{copy.definition} {

data/lib/autoc/collection/hash_set.rb

@@ -70,11 +70,11 @@ Remove and destroy all elements stored in +self+.
 |
 Put a _copy_ of the element +what+ into +self+ *only if* there is no such element in +self+ which is considered equal to +what+.
 
-Return non-zero value on successful element put and zero value otherwise.
+Return non-zero value on successful element put (that is there was not such element in +self+) and zero value otherwise.
 
 |*_int_* ~type~Replace(*_Type_* * +self+, *_E_* +with+)
 |
-*If* +self+ contains an element which is considered equal to the element +with+,
+If +self+ contains an element which is considered equal to the element +with+,
 replace that element with a _copy_ of +with+, otherwise do nothing.
 Replaced element is destroyed.
 
@@ -148,11 +148,11 @@ class HashSet < Collection
   def initialize(*args)
     super
     @list = List.new(list, element, :static)
-    @capability.subtract [:orderable]
-    key_type_check(element)
+    key_requirement(element)
   end
   
   def write_intf_types(stream)
+    super
     stream << %$
       /***
       **** #{type}<#{element.type}> (#{self.class})
@@ -170,7 +170,7 @@ class HashSet < Collection
       };
       struct #{it} {
         #{type_ref} set;
-        int bucket_index;
+        size_t bucket_index;
         #{@list.it} it;
       };
     $
@@ -203,10 +203,11 @@ class HashSet < Collection
   end
 
   def write_impls(stream, define)
+    super
     @list.write_intf_decls(stream, static, inline)
     @list.write_impls(stream, static)
     stream << %$
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref});
+      static #{element.type_ref} #{itGetRef}(#{it_ref});
       static void #{rehash}(#{type_ref} self) {
         #{@list.type_ref} buckets;
         size_t index, bucket_count, size, fill;
@@ -407,11 +408,11 @@ class HashSet < Collection
       #{define} void #{itCtor}(#{it_ref} self, #{type_ref} set) {
         #{assert}(self);
         self->set = set;
-        self->bucket_index = -1;
+        self->bucket_index = self->set->bucket_count;
       }
       #{define} int #{itMove}(#{it_ref} self) {
         #{assert}(self);
-        if(self->bucket_index < 0) #{@list.itCtor}(&self->it, &self->set->buckets[self->bucket_index = 0]);
+        if(self->bucket_index >= self->set->bucket_count) #{@list.itCtor}(&self->it, &self->set->buckets[self->bucket_index = 0]);
         if(#{@list.itMove}(&self->it)) return 1;
         while(++self->bucket_index < self->set->bucket_count) {
           #{@list.itCtor}(&self->it, &self->set->buckets[self->bucket_index]);
@@ -423,7 +424,7 @@ class HashSet < Collection
         #{assert}(self);
         return #{@list.itGet}(&self->it);
       }
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref} self) {
+      static #{element.type_ref} #{itGetRef}(#{it_ref} self) {
         #{assert}(self);
         return #{@list.itGetRef}(&self->it);
       }
@@ -432,9 +433,9 @@ class HashSet < Collection
   
   private
   
-  def key_type_check(obj)
+  def key_requirement(obj)
+    element_requirement(obj)
     raise "type #{obj.type} (#{obj}) must be hashable" unless obj.hashable?
-    element_type_check(obj)
   end
 
 end # HashSet

data/lib/autoc/collection/list.rb

@@ -7,7 +7,7 @@ module AutoC
 =begin
 
 List is an ordered unidirectional sequence container.
-List supports submission/polling operations at one end hence it can be used as a LIFO container.
+List supports submission/polling operations on one end hence it can be used as a LIFO container (a stack).
 
 The collection's C++ counterpart is +std::forward_list<>+ template class.
 
@@ -154,12 +154,8 @@ WARNING: current position *must* be valid otherwise the behavior is undefined. S
 =end
 class List < Collection
   
-  def initialize(*args)
-    super
-    @capability.subtract [:orderable]
-  end
-  
   def write_intf_types(stream)
+    super
     stream << %$
       /***
       **** #{type}<#{element.type}> (#{self.class})
@@ -214,8 +210,9 @@ class List < Collection
   end
   
   def write_impls(stream, define)
+    super
     stream << %$
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref});
+      static #{element.type_ref} #{itGetRef}(#{it_ref});
       #{define} #{ctor.definition} {
         #{assert}(self);
         self->head_node = NULL;
@@ -234,12 +231,22 @@ class List < Collection
       }
       #{define} #{copy.definition} {
         #{it} it;
+        size_t index, size;
+        #{element.type}** elements;
         #{assert}(src);
         #{assert}(dst);
         #{ctor}(dst);
-        #{itCtor}(&it, src);
-        while(#{itMove}(&it)) {
-          #{push}(dst, *#{itGetRef}(&it));
+        if(!#{empty}(src)) {
+          /* List is a LIFO type container therefore the insertion order into the destination container should be reversed */
+          elements = (#{element.type}**)#{malloc}((size = #{size}(src))*sizeof(#{element.type}*)); #{assert}(elements);
+          index = 0;
+          #{itCtor}(&it, src);
+          while(#{itMove}(&it)) {
+            #{assert}(index < size);
+            elements[index++] = #{itGetRef}(&it);
+          }
+          for(index = size; index > 0; --index) #{push}(dst, *elements[index-1]); /* Be careful not to run into the underflow of the unsigned integer type */
+          #{free}(elements);
         }
       }
       #{define} #{equal.definition} {
@@ -331,6 +338,9 @@ class List < Collection
         }
         #{abort}();
       }
+      /* FIXME: for the generality's sake there should be both `what` and `with` values
+        This is not achievable without breaking the interface, however,
+        therefore defer this change to the major version bump */
       #{define} int #{replaceEx}(#{type_ref} self, #{element.type} with, int count) {
         #{node}* node;
         int replaced = 0;
@@ -403,7 +413,7 @@ class List < Collection
         #{element.copy("result", "self->this_node->element")};
         return result;
       }
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref} self) {
+      static #{element.type_ref} #{itGetRef}(#{it_ref} self) {
         #{assert}(self);
         #{assert}(self->this_node);
         return &self->this_node->element;

data/lib/autoc/collection/queue.rb

@@ -9,7 +9,7 @@ module AutoC
 Queue is an ordered bidirectional sequence container.
 Queue supports addition/removal operations at both ends.
 However, it is intended to be used as a FIFO container as opposed to {AutoC::List}
-since submission and polling operations are performed on the opposite ends.
+therefore the default submission, polling and retrieval operations are performed on the opposite ends.
 
 This collection is a synergy of C++ +std::list<>+ and +std::queue<>+ template classes.
 
@@ -193,12 +193,8 @@ WARNING: current position *must* be valid otherwise the behavior is undefined. S
 =end
 class Queue < Collection
   
-  def initialize(*args)
-    super
-    @capability.subtract [:orderable]
-  end
-  
   def write_intf_types(stream)
+    super
     stream << %$
       /***
       **** #{type}<#{element.type}> (#{self.class})
@@ -263,8 +259,9 @@ class Queue < Collection
   end
   
   def write_impls(stream, define)
+    super
     stream << %$
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref});
+      static #{element.type_ref} #{itGetRef}(#{it_ref});
       #{define} #{ctor.definition} {
         #{assert}(self);
         self->head_node = self->tail_node = NULL;
@@ -506,7 +503,7 @@ class Queue < Collection
         #{element.copy("result", "self->this_node->element")};
         return result;
       }
-      #{define} #{element.type_ref} #{itGetRef}(#{it_ref} self) {
+      static #{element.type_ref} #{itGetRef}(#{it_ref} self) {
         #{assert}(self);
         #{assert}(self->this_node);
         return &self->this_node->element;

data/lib/autoc/collection/vector.rb

@@ -78,9 +78,17 @@ Return number of elements stored in vector +self+.
 
 |*_void_* ~type~Sort(*_Type_* * +self+)
 |
+Perform an ascending sort.
+See ~type~SortEx().
+
+NOTE : optional operation.
+
+|*_void_* ~type~SortEx(*_Type_* * +self+, *_int_* ascending)
+|
 NOTE : optional operation.
 
-Perform a sorting operation on the contents of vector +self+ utilizing either generated of user supplied ordering functions.
+Perform a sort operation on the contents of vector +self+ utilizing either generated of user supplied ordering functions.
+If the +ascending+ is non-zero, perform the sorting in ascending order otherwise perform the soring in descending order.
 
 Note that this operation is defined only if element type is orderable, e.g. has equality testing and comparison operations defined.
 
@@ -124,12 +132,15 @@ class Vector < Collection
   def initialize(*args)
     super
     # Override the default type constructor as the Vector's requires one extra parameter
-    # Note that this makes the Vector instance un-constructible
-    @ctor = define_function(:ctor, Function::Signature.new([type_ref^:self, :size_t^:element_count]))
-    @capability.subtract [:constructible, :orderable] # No default constructor and no less operation defined
+    # Note that this makes the Vector instance non-constructible
+    @ctor = define_redirector(:ctor, Function::Signature.new([type_ref^:self, :size_t^:element_count]))
   end
 
+  # No default constructor provided
+  def constructible?; false end
+    
   def write_intf_types(stream)
+    super
     stream << %$
       /***
       **** #{type}<#{element.type}> (#{self.class})
@@ -144,8 +155,7 @@ class Vector < Collection
       };
       struct #{it} {
         #{type_ref} vector;
-        int index;
-        int forward;
+        int index, forward;
       };
     $
   end
@@ -156,6 +166,7 @@ class Vector < Collection
       #{declare} #{ctor.declaration};
       #{declare} #{dtor.declaration};
       #{declare} #{copy.declaration};
+      /* TODO #{copyRange}() */
       #{declare} #{equal.declaration};
       #{declare} #{identify.declaration};
       #{declare} void #{resize}(#{type_ref}, size_t);
@@ -199,11 +210,13 @@ class Vector < Collection
       }
     $
     stream << %$
-      #{declare} void #{sort}(#{type_ref});
+      #define #{sort}(self) #{sortEx}(self, 1)
+      #{declare} void #{sortEx}(#{type_ref}, int);
     $ if element.orderable?
   end
   
   def write_impls(stream, define)
+    super
     stream << %$
       static void #{allocate}(#{type_ref} self, size_t element_count) {
         #{assert}(self);
@@ -283,7 +296,7 @@ class Vector < Collection
       }
     $
     stream << %$
-      static int #{comparator}(void* lp_, void* rp_) {
+      static int #{ascend}(void* lp_, void* rp_) {
         #{element.type_ref} lp = (#{element.type_ref})lp_;
         #{element.type_ref} rp = (#{element.type_ref})rp_;
         if(#{element.equal("*lp", "*rp")}) {
@@ -294,18 +307,21 @@ class Vector < Collection
           return +1;
         }
       }
-      #{define} void #{sort}(#{type_ref} self) {
+      static int #{descend}(void* lp_, void* rp_) {
+        return -#{ascend}(lp_, rp_);
+      }
+      #{define} void #{sortEx}(#{type_ref} self, int ascending) {
         typedef int (*F)(const void*, const void*);
         #{assert}(self);
-        qsort(self->values, #{size}(self), sizeof(#{element.type}), (F)#{comparator});
+        qsort(self->values, #{size}(self), sizeof(#{element.type}), ascending ? (F)#{ascend} : (F)#{descend});
       }
     $ if element.orderable?
   end
  
   private
   
-  def element_type_check(obj)
-    # Additional requirement is imposed on the vector's element
+  def element_requirement(obj)
+    # Vector requires the element to have default parameterless constructor
     raise "type #{obj.type} (#{obj}) must be constructible" unless obj.constructible?
     super
   end