malloc 0.2.4 → 0.2.5

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/packagetask'
 require 'rbconfig'
 
 PKG_NAME = 'malloc'
-PKG_VERSION = '0.2.4'
+PKG_VERSION = '0.2.5'
 CXX = ENV[ 'CXX' ] || 'g++'
 STRIP = ENV[ 'STRIP' ] || 'strip'
 RB_FILES = FileList[ 'lib/**/*.rb' ]
@@ -40,6 +40,7 @@ $SITEARCHDIR = Config::CONFIG[ 'sitearchdir' ]
 
 task :default => :all
 
+desc 'Compile Ruby extension (default)'
 task :all => [ SO_FILE ]
 
 file SO_FILE => OBJ do |t|

data/lib/malloc_ext.rb

@@ -1,3 +1,21 @@
+# String#bytesize is defined if it does not exist already
+class String
+
+  unless method_defined? :bytesize
+
+    # String#bytesize is defined if it does not exist already
+    #
+    # Provided for compatibility with Ruby 1.8.6. Same as #size.
+    #
+    # @private
+    def bytesize
+      size
+    end
+
+  end
+  
+end
+
 # Namespace of the Hornetseye project.
 module Hornetseye
 
@@ -8,7 +26,15 @@ module Hornetseye
 
       # Create new Malloc object
       #
-      # @param [size] Number of bytes to allocate.
+      # Allocate the specified number of bytes of raw memory.
+      #
+      # @example Allocate raw memory
+      # require 'malloc'
+      # include Hornetseye
+      # m = Malloc.new 32
+      # # Malloc(32)
+      #
+      # @param [Integer] size Number of bytes to allocate.
       # @return [Malloc] A new Malloc object.
       def new( size )
         retval = orig_new size
@@ -22,12 +48,61 @@ module Hornetseye
 
     # Number of bytes allocated
     #
+    # @example Querying size of allocated memory
+    # require 'malloc'
+    # include Hornetseye
+    # m = Malloc.new 32
+    # m.size
+    # # 32
+    # ( m + 8 ).size
+    # # 24
+    #
     # @return [Integer] Size of allocated memory.
     attr_reader :size
 
+    # Display information about this object
+    #
+    # @example Displaying information about a Malloc object
+    # require 'malloc'
+    # Hornetseye::Malloc.new( 8 ).inspect
+    # "Malloc(8)"
+    #
+    # @return [String] A string with information about this object.
+    def inspect
+      "Malloc(#{@size})"
+    end
+
+    # Read data from memory
+    #
+    # @example Convert data of Malloc object to string
+    # require 'malloc'
+    # include Hornetseye
+    # m = Malloc.new 5
+    # m.write 'abcde'
+    # m.to_s
+    # "abcde"
+    #
+    # @return [String] A string containing the data.
+    #
+    # @see #read
+    def to_s
+      read @size
+    end
+
     # Operator for doing pointer arithmetic
     #
-    # @param [offset] Non-negative offset for pointer.
+    # @example Pointer arithmetic
+    # require 'malloc'
+    # include Hornetseye
+    # m = Malloc.new 4
+    # # Malloc(4)
+    # m.write 'abcd'
+    # n = m + 2
+    # # Malloc(2)
+    # n.read 2
+    # # "cd"
+    #
+    # @param [Integer] offset Non-negative offset for pointer.
     # @return [Malloc] A new Malloc object.
     def +( offset )
       if offset > @size
@@ -43,8 +118,20 @@ module Hornetseye
 
     # Read data from memory
     #
-    # @param [length] Number of bytes to read.
+    # @example Reading and writing data
+    # require 'malloc'
+    # include Hornetseye
+    # m = Malloc.new 4
+    # # Malloc(4)
+    # m.write 'abcd'
+    # m.read 2
+    # # "ab"
+    #
+    # @param [Integer] length Number of bytes to read.
     # @return [String] A string containing the data.
+    #
+    # @see #write
+    # @see #to_s
     def read( length )
       raise "Only #{@size} bytes of memory left to read " +
         "(illegal attempt to read #{length} bytes)" if length > @size
@@ -55,8 +142,19 @@ module Hornetseye
 
     # Write data to memory
     #
-    # @param [string] A string with the data.
-    # @return [String] Returns the parameter `string`.
+    # @example Reading and writing data
+    # require 'malloc'
+    # include Hornetseye
+    # m = Malloc.new 4
+    # # Malloc(4)
+    # m.write 'abcd'
+    # m.read 2
+    # # "ab"
+    #
+    # @param [String] string A string with the data.
+    # @return [String] Returns the parameter +string+.
+    #
+    # @see #read
     def write( string )
       if string.bytesize > @size
         raise "Must not write more than #{@size} bytes of memory " +
@@ -70,23 +168,3 @@ module Hornetseye
   end
 
 end
-
-# The string class of the standard library
-#
-# @private
-class String
-
-  unless method_defined? :bytesize
-
-    # This method won't be overriden if it is defined already
-    #
-    # Provided for compatibility with Ruby 1.8.6. Same as #size.
-    #
-    # @private
-    def bytesize
-      size
-    end
-
-  end
-  
-end

data/test/tc_malloc.rb

@@ -8,6 +8,16 @@ class TC_Malloc < Test::Unit::TestCase
     assert_raise( ArgumentError ) { Hornetseye::Malloc.new }
   end
 
+  def test_inspect
+    assert_equal 'Malloc(32)', Hornetseye::Malloc.new( 32 ).inspect
+  end
+
+  def test_to_s
+    m = Hornetseye::Malloc.new 3
+    m.write 'abc'
+    assert_equal 'abc', m.to_s
+  end
+
   def test_read_write
     m = Hornetseye::Malloc.new 6
     assert_equal 'abcdef', m.write( 'abcdef' )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: malloc
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors: 
 - Jan Wedekind
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-14 00:00:00 +00:00
+date: 2010-01-14 00:00:00 +00:00
 default_executable: 
 dependencies: []