hikari_buffer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 540d2520c67449dd639af257f9a415942f42f4e50a885e15922a9ea61bc22fc5
+  data.tar.gz: 80cd2f004b6434f2c9927e3af94e2563d766c2dbfe27ed7d46c169bcd7f68370
+SHA512:
+  metadata.gz: 8c4e41cb1fdd5fec74fc896d864b48fdfcfa3a4e925570ef6187125dca187ba4b3bd579087201b45d336b963519e4232cdd72c598345d5364953de037bf995ee
+  data.tar.gz: 88a7e464c4f86a40827ab44a23acb66358f9f6f9a8860f75f5b77e4b77b2442edf5291f61ce58f43a0abcf29bc30a2b80fcd6be2473d48c94a36bab70a98e29b

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [0.1.0] - 2026-08-05
+
+### Added
+
+- Native C extension
+- Integer serialization (signed/unsigned)
+- Floating point serialization
+- Boolean serialization
+- String serialization
+- Byte serialization
+- Peek operations
+- Skip operation
+- Automatic buffer growth
+- Comprehensive test suite
+- Benchmarks

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"Hikari Buffer" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact the maintainer through GitHub by opening a private discussion or issue.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# Hikari Buffer
+
+[![Ruby](https://github.com/AntarMukhopadhyaya/hikari-buffer/actions/workflows/main.yml/badge.svg)](https://github.com/AntarMukhopadhyaya/hikari-buffer/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A fast, lightweight binary buffer for Ruby built as a native C extension. Hikari Buffer provides efficient serialization and deserialization of primitive data types, strings, and raw bytes through a clean, chainable API.
+
+## Features
+
+* 🚀 Native C extension for maximum performance
+* 📦 Binary serialization and deserialization
+* 🔢 Signed integers (`i8`, `i16`, `i32`, `i64`)
+* 🔢 Unsigned integers (`u8`, `u16`, `u32`, `u64`)
+* 🌊 Floating-point numbers (`f32`, `f64`)
+* ✅ Boolean support
+* 📝 UTF-8 string serialization
+* 📄 Raw byte serialization
+* 🎯 Cursor-based reading and writing
+* 🔄 Automatic buffer growth
+* 🧪 Comprehensive RSpec test suite
+
+## Installation
+
+### RubyGems
+
+```bash
+gem install hikari_buffer
+```
+
+### Bundler
+
+```ruby
+gem "hikari_buffer"
+```
+
+## Quick Start
+
+```ruby
+require "hikari_buffer"
+
+buffer = Hikari::Buffer.new
+
+buffer
+  .write_u32(42)
+  .write_bool(true)
+  .write_f64(Math::PI)
+  .write_string("Hello, Hikari!")
+
+buffer.rewind
+
+puts buffer.read_u32
+puts buffer.read_bool
+puts buffer.read_f64
+puts buffer.read_string
+```
+
+## Supported Types
+
+| Type   | Read | Write |
+| ------ | :--: | :---: |
+| u8     |   ✅  |   ✅   |
+| u16    |   ✅  |   ✅   |
+| u32    |   ✅  |   ✅   |
+| u64    |   ✅  |   ✅   |
+| i8     |   ✅  |   ✅   |
+| i16    |   ✅  |   ✅   |
+| i32    |   ✅  |   ✅   |
+| i64    |   ✅  |   ✅   |
+| f32    |   ✅  |   ✅   |
+| f64    |   ✅  |   ✅   |
+| bool   |   ✅  |   ✅   |
+| bytes  |   ✅  |   ✅   |
+| string |   ✅  |   ✅   |
+
+## Buffer API
+
+```ruby
+buffer.capacity
+buffer.size
+buffer.cursor
+buffer.tell
+buffer.remaining
+
+buffer.seek(position)
+buffer.rewind
+buffer.clear
+```
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/AntarMukhopadhyaya/hikari-buffer.git
+cd hikari-buffer
+bundle install
+```
+
+Compile the native extension:
+
+```bash
+bundle exec rake compile
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+## Roadmap
+
+* [x] Primitive integer serialization
+* [x] Floating-point serialization
+* [x] Boolean serialization
+* [x] String serialization
+* [x] Raw byte serialization
+* [x] Automatic buffer growth
+* [ ] Peek operations
+* [ ] Endianness support
+* [ ] Array serialization
+* [ ] UUID serialization
+* [ ] Benchmarks
+* [ ] Precompiled native gems for Windows, Linux, and macOS
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are welcome.
+
+If you'd like to contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for your changes
+4. Ensure all tests pass
+5. Open a Pull Request
+
+## License
+
+Released under the MIT License. See the `LICENSE` file for details.

data/Rakefile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+namespace :bench do
+  Dir.glob("bench/*.rb").sort.each do |file|
+    name = File.basename(file, ".rb")
+
+    desc "Run #{name} benchmark"
+    task name.to_sym do
+      ruby file
+    end
+  end
+
+  desc "Run all benchmarks"
+  task :all do
+    Dir.glob("bench/*.rb").sort.each do |file|
+      puts
+      puts "=" * 80
+      puts "Running #{File.basename(file)}"
+      puts "=" * 80
+
+      ruby file
+    end
+  end
+end
+
+require "rake/extensiontask"
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load("hikari_buffer.gemspec")
+
+Rake::ExtensionTask.new("hikari_buffer", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/hikari_buffer"
+end
+
+task default: %i[clobber compile spec rubocop]

data/bench/growth_stress.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+
+require "hikari_buffer"
+
+Benchmark.ips do |x|
+  x.report("Growth (8 -> many)") do
+    buf = Hikari::Buffer.new(8)
+
+    10_000.times do |i|
+      buf.write_u32(i)
+    end
+  end
+
+  x.compare!
+end

data/bench/marshal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("Marshal") do
+    Marshal.dump({
+                   hp: 100,
+                   mana: 50,
+                   x: 12.3,
+                   y: 45.6,
+                   alive: true,
+                   level: 99
+                 })
+  end
+
+  x.report("Hikari") do
+    buf.clear
+
+    buf
+      .write_i32(100)
+      .write_i32(50)
+      .write_f32(12.3)
+      .write_f32(45.6)
+      .write_bool(true)
+      .write_u16(99)
+  end
+
+  x.compare!
+end

data/bench/mixed_workload.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+TEXT = "Hello World"
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("Array#pack") do
+    [
+      42,
+      -1234,
+      3.1415926535
+    ].pack("L<q<d") + [1].pack("C") + [TEXT.bytesize].pack("L<") + TEXT
+  end
+
+  x.report("Hikari") do
+    buf.clear
+
+    buf
+      .write_u32(42)
+      .write_i64(-1234)
+      .write_f64(3.1415926535)
+      .write_bool(true)
+      .write_string(TEXT)
+  end
+
+  x.compare!
+end

data/bench/protocol.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+
+require "hikari_buffer"
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("Protocol") do
+    buf.clear
+
+    buf
+      .write_u16(0xCAFE)
+      .write_u32(100)
+      .write_bool(true)
+      .write_f64(99.5)
+      .write_string("Player")
+      .write_bytes("abcd")
+  end
+end

data/bench/read_bytes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+DATA = Random.bytes(512)
+
+buf = Hikari::Buffer.new
+buf.write_bytes(DATA)
+
+Benchmark.ips do |x|
+  x.report("Hikari") do
+    buf.rewind
+    buf.read_bytes(DATA.bytesize)
+  end
+end

data/bench/read_string.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+TEXT = "Hello, Hikari Buffer!"
+
+buf = Hikari::Buffer.new
+buf.write_string(TEXT)
+
+Benchmark.ips do |x|
+  x.report("Hikari") do
+    buf.rewind
+    buf.read_string
+  end
+end

data/bench/sequential_packet.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+TEXT = "Hello"
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("Hikari packet") do
+    buf.clear
+
+    buf
+      .write_u8(42)
+      .write_i16(-123)
+      .write_u32(999_999)
+      .write_f64(Math::PI)
+      .write_bool(true)
+      .write_string(TEXT)
+
+    buf.rewind
+
+    buf.read_u8
+    buf.read_i16
+    buf.read_u32
+    buf.read_f64
+    buf.read_bool
+    buf.read_string
+  end
+end

data/bench/stringio.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "stringio"
+
+require "hikari_buffer"
+
+buf = Hikari::Buffer.new
+io = StringIO.new
+
+Benchmark.ips do |x|
+  x.report("StringIO") do
+    io.rewind
+    io.write([123].pack("L"))
+  end
+
+  x.report("Hikari") do
+    buf.clear
+    buf.write_u32(123)
+  end
+
+  x.compare!
+end

data/bench/write_bytes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+DATA = Random.bytes(512)
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("String#dup") do
+    DATA.dup
+  end
+
+  x.report("Hikari") do
+    buf.clear
+    buf.write_bytes(DATA)
+  end
+
+  x.compare!
+end

data/bench/write_string.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+
+TEXT = "Hello, Hikari Buffer!"
+
+buf = Hikari::Buffer.new
+
+Benchmark.ips do |x|
+  x.report("String#dup") do
+    TEXT.dup
+  end
+
+  x.report("Hikari") do
+    buf.clear
+    buf.write_string(TEXT)
+  end
+
+  x.compare!
+end

data/bench/write_u32.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "hikari_buffer"
+buf = Hikari::Buffer.new
+Benchmark.ips do |x|
+  x.report("Array#pack") do
+    [123_456_789].pack("L")
+  end
+  x.report("Hikari") do
+    buf.write_u32(123_456_789)
+  end
+  x.compare!
+end