uncle_blake3 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9da28c3f3c9490f04d35fc3d29efb959b079ad9acdb2f79d1cb1019bc437213a
-  data.tar.gz: bda52bea8990bf57253dc0b72b8c14759b3eeae3944f3f98362c2985feb8027d
+  metadata.gz: 743e230c6eeeecf88ca38acfa04bb212085d456dcded4b872d70426835cea804
+  data.tar.gz: b47f56a53d6ebe8a83ac09cd63e4d89ff0af61afd6969d5d31350167576b2897
 SHA512:
-  metadata.gz: ed506ef5ba7b9042bd1f201ffd8906b970f421c4f67e3a5e683d61aa88023adf8755afa9bfd339dfdce888e9b3fe57854a2be4ce2f0a6633191eca3a26c12898
-  data.tar.gz: 82271beb236082775ec8a221849c11202c3d6aba329d73477a701c90fbacd484cc8c18986336b6ca36748059910523e2e2db62ed7c8a60617c203265b466ef08
+  metadata.gz: b22a753142ae17492aca3210d36a3e8f7332d848dfb4c3ed9bd629ef87eadee9be41e25f71441e6419e150ab93a9d9d2a9dec4defa4c0f48982426ddea1085a0
+  data.tar.gz: 9093e31501959a8e22970eac43a0857100da31eff9225eec07b23e1f253c849e34e2dfb20a18823aa99fe9dacf37dd56ac31b4dbce93b800a4bd87131ad9b5b4

data/README.md

@@ -1,5 +1,8 @@
 # UncleBlake3
 
+[![GitHub version](https://badge.fury.io/gh/the-cave%2Funcle-blake3.svg)](https://badge.fury.io/gh/the-cave%2Funcle-blake3)
+[![Gem Version](https://badge.fury.io/rb/uncle_blake3.svg)](https://badge.fury.io/rb/uncle_blake3)
+
 ## What is it?
 
 UncleBlake3 is a Ruby binding of [Blake3](https://github.com/BLAKE3-team/BLAKE3), a fast cryptographic hash function.
@@ -25,9 +28,9 @@ In order to install the gem, your needs:
 
 Add this line to your application's Gemfile:
 
-```ruby
+~~~ruby
 gem 'uncle_blake3'
-```
+~~~
 
 And then execute:
 
@@ -35,7 +38,7 @@ And then execute:
 
 ## Usage Examples
 
-~~~Ruby
+~~~ruby
 # basic usage
 ::UncleBlake3::Digest.hexdigest("\x00")
 # => "2d3adedff11b61f14c886e35afa036736dcd87a74d27b5c1510225d0f592e213"

data/lib/uncle_blake3/binding.rb

@@ -3,6 +3,7 @@
 require_relative 'build/loader'
 
 module UncleBlake3
+  # @!visibility private
   module Binding
     extend ::FFI::Library
     ffi_lib Build::Loader.find('UncleBlake3')

data/lib/uncle_blake3/build/loader.rb

@@ -5,6 +5,7 @@ require 'pathname'
 require_relative 'platform'
 
 module UncleBlake3
+  # @!visibility private
   module Build
     # taken from:
     # https://github.com/ffi/ffi-compiler/blob/master/lib/ffi-compiler/loader.rb

data/lib/uncle_blake3/build/platform.rb

@@ -4,6 +4,7 @@ require 'ffi'
 require 'singleton'
 
 module UncleBlake3
+  # @!visibility private
   module Build
     # mostly taken from:
     # https://github.com/ffi/ffi-compiler/blob/master/lib/ffi-compiler/platform.rb

data/lib/uncle_blake3/digest.rb

@@ -6,6 +6,13 @@ require 'objspace'
 require_relative 'binding'
 
 module UncleBlake3
+  # @example basic usage
+  #   digest = ::UncleBlake3::Digest.new(output_length: 10)
+  #   digest << 'some input'
+  #   digest << 'some more input'
+  #   digest.hexdigest
+  #   #=> "d709fca62bbf74099e87"
+  # See {file:README.md README} for more usage examples
   class Digest
     KEY_LENGTH = Binding.key_length
     DEFAULT_OUTPUT_LENGTH = Binding.default_output_length
@@ -21,6 +28,7 @@ module UncleBlake3
       include Error
     end
 
+    # Create a new Digest
     def initialize(output_length: DEFAULT_OUTPUT_LENGTH, key: nil, key_seed: nil)
       raise TypeError, 'Hash length is not an Integer' unless output_length.is_a?(::Integer)
       raise ArgumentError, 'Hash length out of range' unless (1...(1 << 20)).include?(output_length)
@@ -49,6 +57,7 @@ module UncleBlake3
       invalidate_cache
     end
 
+    # Feed in the data
     def update(data)
       data_size = data.bytesize
       data_buffer = ::FFI::MemoryPointer.new(:uint8, data_size)
@@ -59,10 +68,12 @@ module UncleBlake3
       invalidate_cache
     end
 
+    # Alias for {#update}
     def <<(*args, **kwargs)
       update(*args, **kwargs)
     end
 
+    # Finalize and output a binary hash
     def digest
       @_digest_cache ||= begin
         data_buffer = ::FFI::MemoryPointer.new(:uint8, @output_length)
@@ -71,10 +82,12 @@ module UncleBlake3
       end
     end
 
+    # Finalize and output a hexadecimal-encoded hash
     def hexdigest
       @_hexdigest_cache ||= digest.unpack1('H*')
     end
 
+    # Finalize and output a Base64-encoded hash
     def base64digest
       @_base64digest_cache ||= ::Base64.strict_encode64(digest)
     end
@@ -88,21 +101,37 @@ module UncleBlake3
     end
 
     class << self
+      # @!visibility private
       # https://www.mikeperham.com/2010/02/24/the-trouble-with-ruby-finalizers/
       def _create_finalizer(instance)
-        proc {
+        proc do
           Binding.destroy(instance)
-        }
+        end
       end
 
+      # Shortcut to calculate a raw digest
+      # @example basic usage
+      #   ::UncleBlake3::Digest.digest('some input')
+      #   #=> "{7\x00\f\x00EZ\xBD \x9A\x9A\x02\xDDH|>({\xC6\xA1\x9DNA\xEB\x81\xC8K\x85\x9E\xBF\x87;"
+      # @example with key derived from seed
+      #   ::UncleBlake3::Digest.digest('some input', key_seed: 'secret')
+      #   #=> "\xA7d\x13c)e\e`>\x9D\e\xB0\x9E\xF9\xA6\x82F:\xA8w;\xB0!\xBC*l\xF3w\x83\x85\xCA\x1E"
+      # @example with raw key (fixed-length key)
+      #   ::UncleBlake3::Digest.digest('some input', key: '0123456789abcdef0123456789abcdef')
+      #   #=> "8Z\x89+\x1A}\x0E\xBBI\xD4)\xC5\x9A\x8A\x17\x13[\xB7\x1DO\x98\xE8\xEF\x06\xD58\x83c\xC3u\x13\xE1"
+      # @example controlled output length
+      #   ::UncleBlake3::Digest.digest('some input', output_length: 5)
+      #   #=> "{7\x00\f\x00"
       def digest(*args, **kwargs)
         _generic_digest(*args, **kwargs, &:digest)
       end
 
+      # Same as {.digest} but encode the output in hexadecimal format
       def hexdigest(*args, **kwargs)
         _generic_digest(*args, **kwargs, &:hexdigest)
       end
 
+      # Same as {.digest} but encode the output in Base64 format
       def base64digest(*args, **kwargs)
         _generic_digest(*args, **kwargs, &:base64digest)
       end

data/lib/uncle_blake3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UncleBlake3
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uncle_blake3
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Sarun Rattanasiri
@@ -38,9 +38,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 13.0.0
-description: This gem brought the hash algorithm, Blake3, to Ruby. It uses the official
-  Blake3 implementation which optimized and maintained by the original Blake3 team
-  themselves.
+description: |-
+  Blake3 binding for Ruby
+  The gem build on top of the official Blake3 implementation maintained by the team behind Blake3 themselves.
+  It supports `AVX512`, `AVX2`, `SSE4.1`, and `SSE2` acceleration with thin and stable binding.
 email: midnight_w@gmx.tw
 executables: []
 extensions:
@@ -90,8 +91,8 @@ licenses:
 - BSD-3-Clause
 metadata:
   homepage_uri: https://github.com/the-cave/uncle-blake3
-  source_code_uri: https://github.com/the-cave/uncle-blake3/tree/v0.0.2
-  documentation_uri: https://rubydoc.info/gems/uncle_blake3/0.0.2/
+  source_code_uri: https://github.com/the-cave/uncle-blake3/tree/v0.0.3
+  documentation_uri: https://rubydoc.info/gems/uncle_blake3/0.0.3
   bug_tracker_uri: https://github.com/the-cave/uncle-blake3/issues
 post_install_message:
 rdoc_options: []
@@ -111,5 +112,5 @@ requirements: []
 rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
-summary: A binding of the Blake3 hash algorithm for Ruby
+summary: Blake3, the hash algorithm, native binding for Ruby
 test_files: []