bitary 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 293fa51d8a5a4b4cda3a7a283737d0695b84cfcb55414afde3b9c5bb6f9688aa
-  data.tar.gz: 6d6541faa0fed549f62a3a1b99a293ca4422511c34527a7278ea7459683f506a
+  metadata.gz: 23912fd76ca478d49ef1760e9d8cdb47344b3493377d00db1d133b4131c11b6e
+  data.tar.gz: 49def92fa2d841953139bb16cd81779d92e8f9478b6fe8a395f0400b6344a05b
 SHA512:
-  metadata.gz: 0a81bd80568d6b5fcb20d951f0b193f98941adafd448a896f0a68ae8c97eabecca07a34a2db1d48f4e630a64d1be165ed4efe5f370bc1aabd36f78de4a5b0e7d
-  data.tar.gz: 94f16667978d9d9be2ccf141c6539834d7f3502397db12feee83424eb0586ace151be1ca7bee960b5bc40ba0ec6e9e12c0879c74f700d1cd86c35e21f85337bb
+  metadata.gz: 5faafe8215df8fc28fe075a0bf8a874b503c2346489c1327ddb94f1388c12e52cc6e0218fb25a876da9d75409e58a80f369cc71bde766c325ff4d01a02353330
+  data.tar.gz: 0f4b3584332df720e29be0069b42979af9471152df2e4347e5cde90972902a575bba323d7040ee133a8807b918a817d95a1d65f48032ef8f27d8d8708fed7ddc

data/.rubocop.yml

@@ -23,3 +23,11 @@ Layout/LineLength:
 Style/MixinUsage:
   Exclude:
     - 'spec/**/*.rb'
+
+Style/ArgumentsForwarding:
+  Exclude:
+    - /**/*.rb
+
+Naming/BlockForwarding:
+  Exclude:
+    - /**/*.rb

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.2.0] - 2024-04-14
+
+- `Bitary#to_a` now returns a clone to prevent client code to misuse the data structure (same for `Bitary#each_byte`)
+- Streamline the internal array initialization
+- Enhance constructor implementation
+- `Bitary#set` and `Bitary#set` are now suffixed by `!`
+
+## [0.1.9] - 2024-04-01
+
+- boost perf even more by inlining mapping operations
+
+## [0.1.8] - 2024-04-01
+
+- inline bit operations to regain original perf
+
 ## [0.1.7] - 2024-04-01
 
 - loads of refactoring and perf improvements

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby-based implementation of the bit array data structure.
 
-It's still under development, but as of now, it implements simple and well-optimized logic allowing you to set, unset and retrieve bits (as well as some extra features, see below).
+It implements simple and well-optimized logic allowing you to set, unset and retrieve bits (as well as some extra features, see below).
 
 ## Installation
 
@@ -20,23 +20,22 @@ $ gem install bitary
 
 ## Usage
 
-Documentation still needs to be written, but here is a breakdown
-of the main capabilities brought by the current bit array implementation:
+Here is a breakdown of the main capabilities brought by the current implementation:
 
 ```ruby
 require 'bitary'
 
 bit_array_sz = Bitary.new(128) # give an explicit size. Defaults to 64 bits used per item
 bit_array_ar = Bitary.new(
-  [255, 10, 20],
+  bytes: [255, 10, 20],
   bpi: Bitary::BYTE # 8 bits
 ) # create based on some integer array
 
 bit_array_sz.bpi # 64
 bit_array_ar.bpi # 8
 
-bit_array_ar.size # 128
-bit_array_ar.size # 24
+bit_array_ar.bits # 128
+bit_array_ar.bits # 24
 
 # set/unset/get
 bit_array_sz[23] = 1 # set bit at position 23 (0-indexed)
@@ -58,8 +57,8 @@ bit_array_ar.to_s # "01111111 00001010 00010100"
 
 # increase/decrease bits used per item
 bit_array_ar.bpi = Bitary::LONG # 64 bits
-bit_array_ar.to_a # [8_325_652]
-bit_array_ar.to_s # "0000000000000000000000000000000000000000011111110000101000010100"
+bit_array_ar.to_a # [9154151182816509952]
+bit_array_ar.to_s # "0111111100001010000101000000000000000000000000000000000000000000"
 
 bit_array_sz.bpi # 64
 bit_array_sz.to_a # [1_099_511_627_776, 0]
@@ -73,6 +72,14 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+Access the technical documentation in HTML format by issuing:
+
+```bash
+$ bundle exec yardoc # or simply yardoc if bundler is not being used
+```
+
+The YARD documentation will be generated under `/doc`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Patacode/bitary.

data/lib/bitary/bitwarr.rb

@@ -2,14 +2,14 @@
 
 class Bitary
   class Bitwarr
-    attr_reader :bpi, :bitsize
+    attr_reader :bpi, :bits
 
-    def initialize(initial_data, bpi: Bitary::LONG)
-      @bitsize = init_bitsize(initial_data, bpi)
-      @array = init_array(initial_data, @bitsize, bpi)
-      @bpi = init_bpi(initial_data, bpi)
+    DEFAULT_INIT_CAP = Bitary::Size::LONG * 2
 
-      self.bpi = bpi
+    def initialize(init_cap, bytes:, bpi:)
+      @array = init_array(init_cap, bytes, bpi)
+      @bits = init_bits(init_cap, bytes)
+      @bpi = bpi
     end
 
     def [](bit_index) = @array[item_index(bit_index)]
@@ -26,11 +26,14 @@ class Bitary
     end
 
     def to_s = @array.map { |item| to_binstr(item) }.join(' ')
+    def to_a = @array.clone
 
     def each_byte(&proc)
+      raise ArgumentError if proc.nil?
+
       @array.each do |item|
         explode_item(item, Bitary::BYTE, @bpi, &proc)
-      end
+      end.clone
     end
 
     def bpi=(value)
@@ -40,30 +43,61 @@ class Bitary
       @bpi = value
     end
 
-    def method_missing(method, *, &)
-      @array.respond_to?(method) ? @array.send(method, *, &) : super
-    end
+    private
 
-    def respond_to_missing?(method, include_all = false)
-      @array.respond_to?(method, include_all) || super
+    def init_bits(init_cap, bytes)
+      if init_cap.nil?
+        if bytes.nil?
+          DEFAULT_INIT_CAP
+        else
+          bytes.length * Bitary::BYTE
+        end
+      else
+        init_cap
+      end
     end
 
-    private
+    def compute_nb_items(init_cap, bpi)
+      (init_cap / bpi.to_f).ceil
+    end
 
-    def init_bpi(initial_data, bpi)
-      initial_data.is_a?(Array) ? Bitary::BYTE : bpi
+    def init_array(init_cap, bytes, bpi)
+      if init_cap.nil?
+        if bytes.nil?
+          fill_array(0, DEFAULT_INIT_CAP, bpi)
+        else
+          adjust_array(bytes, bpi)
+        end
+      elsif bytes.nil?
+        fill_array(0, init_cap, bpi)
+      else
+        clone = adjust_array(bytes, bpi)
+        if init_cap > clone.length * bpi
+          adjust_array_to_cap(clone, init_cap, bpi)
+        end
+        clone
+      end
     end
 
-    def init_bitsize(initial_data, bpi)
-      initial_data.is_a?(Array) ? bpi * initial_data.length : initial_data
+    def fill_array(value, size, bpi)
+      [value] * compute_nb_items(size, bpi)
     end
 
-    def init_array(initial_data, bitsize, bpi)
-      if initial_data.is_a?(Array)
-        initial_data.clone
+    def adjust_array(bytes, bpi)
+      if bpi == Bitary::BYTE
+        bytes.clone
       else
-        [0] * (bitsize / bpi.to_f).ceil
+        increase_items_size(bytes, bpi, Bitary::BYTE)
+      end
+    end
+
+    def adjust_array_to_cap(bytes, init_cap, bpi)
+      target_size = compute_nb_items(init_cap, bpi)
+      while target_size > bytes.length
+        bytes << 0
+        target_size -= 1
       end
+      bytes
     end
 
     def item_index(bit_index)
@@ -74,21 +108,16 @@ class Bitary
       format("%0#{@bpi}d", item.to_s(2))
     end
 
-    def operate_bit_at(operation, index)
-      Factory
-        .make("Handler::#{operation.capitalize}", self[index])
-        .execute(
-          index: index % @bpi,
-          size: @bpi
-        )
-    end
-
-    def operate_bit_at!(operation, index)
-      self[index] = operate_bit_at(operation, index)
+    def update_items_size!(new_size)
+      @array = update_items_size(@array, new_size, @bpi)
     end
 
-    def update_items_size!(value)
-      value > @bpi ? increase_items_size!(value) : decrease_items_size!(value)
+    def update_items_size(array, new_size, bpi)
+      if new_size > bpi
+        increase_items_size(array, new_size, bpi)
+      else
+        decrease_items_size(array, new_size, bpi)
+      end
     end
 
     def append_bits(item, bpi, addend)
@@ -115,10 +144,6 @@ class Bitary
       res
     end
 
-    def increase_items_size!(value)
-      @array = increase_items_size(@array, value, @bpi)
-    end
-
     def decrease_items_size(array, new_size, bpi)
       array.each_with_object([]) do |item, acc|
         explode_item(item, new_size, bpi) do |new_item|
@@ -127,10 +152,6 @@ class Bitary
       end
     end
 
-    def decrease_items_size!(value)
-      @array = decrease_items_size(@array, value, @bpi)
-    end
-
     def explode_item(item, new_size, bpi)
       mask = (2**new_size) - 1
       (bpi / new_size).times do |i|

data/lib/bitary/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Bitary
-  VERSION = '0.1.8'
+  VERSION = '0.2.0'
 end

data/lib/bitary.rb

@@ -2,83 +2,205 @@
 
 require_relative 'bitary/size'
 require_relative 'bitary/version'
-require_relative 'bitary/factory'
 require_relative 'bitary/bitwarr'
-require_relative 'bitary/decorator'
-require_relative 'bitary/mapper'
 
+# Bit array facade through client code SHOULD interact with.
 class Bitary
   include Size
 
-  def initialize(initial_data, bpi: LONG)
-    check_initial_data(initial_data)
+  # Creates a new bit array.
+  #
+  # If the initial bit capacity is not given (or `nil`), it will be deducted
+  # from the given byte array. In such case, if no byte array is given, it
+  # will default to {Bitwarr::DEFAULT_INIT_CAP}.
+  #
+  # If no byte array is given (or `nil`), the resulting bit array's items will
+  # all be set to 0.
+  #
+  # Note that, no check is performed on the byte array parameter to ensure
+  # that it has `Integer` items only, as it would considerably impact the
+  # data structure performance at initialization time. So be careful with
+  # it.
+  #
+  # @param init_cap [Integer?] an optional initial bit capacity
+  # @param bytes [Array<Integer>?] an optional byte array used to preset
+  #   the bit array
+  # @param bpi [Integer] the number of bits used per item internally.
+  #   Defaults to {LONG}
+  #
+  # @raise [TypeError] if **init_cap** is neither an `Integer` nor `nil`
+  # @raise [TypeError] if **bytes** is neither an `Array` nor `nil`
+  # @raise [TypeError] if **bpi** is not an `Integer`
+  # @raise [ArgumentError] if **init_cap** is <= 0
+  # @raise [ArgumentError] if **bpi** is not equal to one of the constants
+  #   defined in {Size}
+  def initialize(init_cap = nil, bytes: nil, bpi: LONG)
+    check_init_cap(init_cap)
+    check_bytes(bytes)
     check_bpi(bpi)
 
-    @bitwarr = Factory.make('Bitwarr', initial_data, bpi:)
+    @bitwarr = Bitwarr.new(init_cap, bytes:, bpi:)
   end
 
+  # Gets the bit at given index.
+  #
+  # @param index [Integer] the index of the bit to retrieve
+  #
+  # @raise [TypeError] if **index** is not an `Integer`
+  # @raise [IndexError] if **index** is < 0 || >= {#bits}
+  #
+  # @return [Integer] the bit at given index
   def [](index)
     check_bit_index(index)
 
     @bitwarr.bit_at(index)
   end
 
+  # Sets or unsets the bit at given index.
+  #
+  # The bit at given index will be set to 1 if given value is truthy but 0,
+  # or 0 otherwise.
+  #
+  # @param index [Integer] the index of the bit to set/unset
+  # @param value [Object] the object used to set/unset the bit at given index
+  #
+  # @raise [TypeError] if **index** is not an `Integer`
+  # @raise [IndexError] if **index** is < 0 || >= {#bits}
+  #
+  # @return [Object] the given **value**
   def []=(index, value)
     check_bit_index(index)
 
-    case Factory.make('Mapper::ObjToBit').map(value)
+    case obj_to_bit(value)
     when 0 then @bitwarr.unbit_at!(index)
     else @bitwarr.bit_at!(index)
     end
   end
 
-  def set(index)
+  # Sets the bit at given index to 1 (set).
+  #
+  # Specialization method of {#[]=} that is similar to `bitary[index] = 1`.
+  #
+  # @param index [Integer] the index of the bit to set
+  #
+  # @raise [TypeError] if **index** is not an `Integer`
+  # @raise [IndexError] if **index** is < 0 || >= {#bits}
+  #
+  # @return [Integer] 1
+  def set!(index)
     self[index] = 1
   end
 
-  def unset(index)
+  # Sets the bit at given index to 0 (unset).
+  #
+  # Specialization method of {#[]=} that is similar to `bitary[index] = 0`.
+  #
+  # @param index [Integer] the index of the bit to unset
+  #
+  # @raise [TypeError] if **index** is not an `Integer`
+  # @raise [IndexError] if **index** is < 0 || >= {#bits}
+  #
+  # @return [Integer] 0
+  def unset!(index)
     self[index] = 0
   end
 
-  def each_byte(&)
-    @bitwarr.each_byte(&)
+  # Traverses each byte of this bit array starting with its byte at most
+  # significant address.
+  #
+  # @param block [Proc] the block to execute during byte traversal
+  #
+  # @yield [Integer] each byte of this bit array
+  #
+  # @return [Array<Integer>] a clone of the internal backed array (same
+  #   as {#to_a})
+  def each_byte(&block)
+    @bitwarr.each_byte(&block)
   end
 
+  # Returns a clone of the internal backed array used by this bit array.
+  #
+  # @return [Array<Integer>] a clone of the internal backed array
   def to_a
     @bitwarr.to_a
   end
 
+  # Converts this bit array into an equivalent binary string.
+  #
+  # @return [String] the binary string representation of this bit array
   def to_s
     @bitwarr.to_s
   end
 
+  # Updates the number of bits used internally by each item.
+  #
+  # Depending on the use case, increasing/decreasing the number of bits used
+  # per item could reduce the memory footprint of this bit array.
+  #
+  # The idea is just to pay attention to potential internal fragmentation
+  # and find the right balance between the total number of bits you want to
+  # use and the number of bits that will be used by each item internally.
+  #
+  # @param value [Integer] the new bpi to be used by this bit array
+  #
+  # @raise [TypeError] if **value** is not an `Integer`
+  # @raise [ArgumentError] if **value** is not equal to one of the constants
+  #   defined in {Size}
   def bpi=(value)
     check_bpi(value)
 
     @bitwarr.bpi = value
   end
 
-  def size
-    @bitwarr.bitsize
+  # Returns the total number of bits used by this bit array.
+  #
+  # @return [Integer] he total number of bits used by this bit array
+  def bits
+    @bitwarr.bits
   end
 
+  # Returns the number of bits used per item internally.
+  #
+  # @return [Integer] the number of bits used per item internally
   def bpi
     @bitwarr.bpi
   end
 
   private
 
-  def check_initial_data(initial_data)
-    raise ArgumentError unless [Array, Integer].include?(initial_data.class)
+  def check_init_cap(init_cap)
+    return if init_cap.nil?
+
+    raise TypeError unless init_cap.is_a?(Integer)
+    raise ArgumentError unless init_cap.positive?
+  end
+
+  def check_bytes(bytes)
+    return if bytes.nil?
+
+    raise TypeError unless bytes.is_a?(Array)
   end
 
   def check_bpi(bpi)
+    raise TypeError unless bpi.is_a?(Integer)
     raise ArgumentError unless [BYTE, SHORT, INT, LONG].include?(bpi)
   end
 
   def check_bit_index(bit_index)
-    raise ArgumentError unless bit_index.is_a?(Integer)
-    raise IndexError if bit_index.negative? || bit_index >= @bitwarr.bitsize
+    raise TypeError unless bit_index.is_a?(Integer)
+    raise IndexError if bit_index.negative? || bit_index >= bits
+  end
+
+  def obj_to_bit(value)
+    !!value ? truthy_to_bit(value) : 0
+  end
+
+  def truthy_to_bit(value)
+    value.is_a?(Integer) ? int_to_bit(value) : 1
+  end
+
+  def int_to_bit(value)
+    value.zero? ? 0 : 1
   end
 
   alias at []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bitary
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Maximilien Ballesteros
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-01 00:00:00.000000000 Z
+date: 2024-04-14 00:00:00.000000000 Z
 dependencies: []
 description: Ruby-based implementation of the bit array data structure
 email:
@@ -19,19 +19,13 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/bitary.rb
 - lib/bitary/bitwarr.rb
-- lib/bitary/decorator.rb
-- lib/bitary/decorator/single_method.rb
-- lib/bitary/decorator/single_method/non_nil_enforcer.rb
-- lib/bitary/factory.rb
-- lib/bitary/mapper.rb
-- lib/bitary/mapper/int_to_bit.rb
-- lib/bitary/mapper/obj_to_bit.rb
 - lib/bitary/size.rb
 - lib/bitary/version.rb
 - sig/bitary.rbs

data/lib/bitary/decorator/single_method/non_nil_enforcer.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-class Bitary
-  class Decorator
-    class SingleMethod < Bitary::Decorator
-      class NonNilEnforcer < Bitary::Decorator::SingleMethod
-        protected
-
-        def postcall(resp)
-          (resp.nil? and raise TypeError) || resp
-        end
-      end
-    end
-  end
-end

data/lib/bitary/decorator/single_method.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'single_method/non_nil_enforcer'
-
-class Bitary
-  class Decorator
-    class SingleMethod < Bitary::Decorator
-      def initialize(wrappee, method)
-        super(wrappee) { |meth| meth == method }
-        check_method(wrappee, method)
-      end
-
-      private
-
-      def check_method(wrappee, method)
-        raise ArgumentError unless method.is_a?(Symbol)
-        raise NoMethodError unless wrappee.respond_to?(method)
-      end
-    end
-  end
-end

data/lib/bitary/decorator.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'decorator/single_method'
-
-class Bitary
-  class Decorator
-    def initialize(wrappee, &proc)
-      @wrappee = wrappee
-      @predicate = proc || ->(_method) { true }
-    end
-
-    def method_missing(method, *, **, &)
-      if @wrappee.respond_to?(method)
-        if @predicate.call(method)
-          args, kwargs = precall(method, *, **)
-          resp = @wrappee.send(method, *args, **kwargs, &)
-          postcall(resp)
-        else
-          @wrappee.send(method, *, **, &)
-        end
-      else
-        super
-      end
-    end
-
-    def respond_to_missing?(method, include_all = false)
-      @wrappee.respond_to?(method, include_all) || super
-    end
-
-    def wrappee
-      res = @wrappee
-      res = res.wrappee while res.respond_to?(:wrappee)
-      res
-    end
-
-    protected
-
-    def precall(_method, *args, **kwargs)
-      [args, kwargs]
-    end
-
-    def postcall(resp)
-      resp
-    end
-  end
-end

data/lib/bitary/factory.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-class Bitary
-  class Factory
-    private_class_method :new
-    @memo = {}
-
-    def self.make(name, *, **)
-      raise ArgumentError unless name.is_a?(String)
-
-      name.split('::').reduce(Bitary) do |cls, str|
-        cls.const_get(str)
-      end.new(*, **)
-    end
-
-    def self.make_memo(name, *args, **kwargs)
-      raise ArgumentError unless name.is_a?(String)
-      if @memo.key?(name.to_sym) && !args.empty? && !kwargs.empty?
-        raise ArgumentError
-      end
-
-      @memo[name.to_sym] ||= make(name, *args, **kwargs)
-    end
-  end
-end

data/lib/bitary/mapper/int_to_bit.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-class Bitary
-  class Mapper
-    class IntToBit < Bitary::Mapper
-      def map(value)
-        if value.is_a?(Integer)
-          value.zero? ? 0 : 1
-        else
-          1
-        end
-      end
-    end
-  end
-end

data/lib/bitary/mapper/obj_to_bit.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-class Bitary
-  class Mapper
-    class ObjToBit < Bitary::Mapper
-      def map(value)
-        case !!value
-        when true then IntToBit.new.map(value)
-        when false then 0
-        end
-      end
-    end
-  end
-end

data/lib/bitary/mapper.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'mapper/int_to_bit'
-require_relative 'mapper/obj_to_bit'
-
-class Bitary
-  class Mapper
-    def self.new(*arg, **kwargs)
-      Decorator::SingleMethod::NonNilEnforcer.new(super, :map)
-    end
-
-    def map(value)
-      raise NotImplementedError
-    end
-  end
-end