bitary 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e00e1deaf6796f8875294cb61799bc4ee1ae956c681489cee8243c9cad532224
-  data.tar.gz: 74088437d85300f562cb47011f17f9242329a0522a95878dfadce0a54803fffe
+  metadata.gz: 23912fd76ca478d49ef1760e9d8cdb47344b3493377d00db1d133b4131c11b6e
+  data.tar.gz: 49def92fa2d841953139bb16cd81779d92e8f9478b6fe8a395f0400b6344a05b
 SHA512:
-  metadata.gz: 71b02ce18e1ad4decb42b8680fbcbb44cf44b9a4edb3637300aa40e1ef90825279b9b4c76e3eef24cf08b8b084cf248129f49e55dd98a191ac2223f185c3e7fb
-  data.tar.gz: a55ae4d18bd812a9d3a3ff1d6eafa263a5eb362978ed8dd47cfed2c0638927c6491f286f70f767a2cc0eeafea85704583cbee085ad450c8d533d5c086f9d8e1f
+  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,14 @@
+## [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

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,11 +2,13 @@
 
 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)
+    DEFAULT_INIT_CAP = Bitary::Size::LONG * 2
+
+    def initialize(init_cap, bytes:, bpi:)
+      @array = init_array(init_cap, bytes, bpi)
+      @bits = init_bits(init_cap, bytes)
       @bpi = bpi
     end
 
@@ -24,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)
@@ -38,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 init_bitsize(initial_data, bpi)
-      initial_data.is_a?(Array) ? bpi * initial_data.length : initial_data
+    def compute_nb_items(init_cap, bpi)
+      (init_cap / bpi.to_f).ceil
     end
 
-    def init_array(initial_data, bitsize, bpi)
-      if initial_data.is_a?(Array)
-        if bpi == Bitary::BYTE
-          initial_data.clone
+    def init_array(init_cap, bytes, bpi)
+      if init_cap.nil?
+        if bytes.nil?
+          fill_array(0, DEFAULT_INIT_CAP, bpi)
         else
-          increase_items_size(initial_data, bpi, Bitary::BYTE)
+          adjust_array(bytes, bpi)
         end
+      elsif bytes.nil?
+        fill_array(0, init_cap, bpi)
       else
-        [0] * (bitsize / bpi.to_f).ceil
+        clone = adjust_array(bytes, bpi)
+        if init_cap > clone.length * bpi
+          adjust_array_to_cap(clone, init_cap, bpi)
+        end
+        clone
+      end
+    end
+
+    def fill_array(value, size, bpi)
+      [value] * compute_nb_items(size, bpi)
+    end
+
+    def adjust_array(bytes, bpi)
+      if bpi == Bitary::BYTE
+        bytes.clone
+      else
+        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)

data/lib/bitary/version.rb

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

data/lib/bitary.rb

@@ -4,22 +4,70 @@ require_relative 'bitary/size'
 require_relative 'bitary/version'
 require_relative 'bitary/bitwarr'
 
+# 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 = Bitwarr.new(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)
 
@@ -29,60 +77,122 @@ class Bitary
     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)
-    case !!value
-    when true then truthy_to_bit(value)
-    when false then 0
-    end
+    !!value ? truthy_to_bit(value) : 0
   end
 
   def truthy_to_bit(value)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bitary
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  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,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md