fast_string 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9fd44e3eb58b60d33076e9bde88fed85a53604fb0b3f67d5dbf9d7ade85f496
+  data.tar.gz: 006a7207651e9eb23169f0eb340c502d5a8a796a98ae3e59cc95281949af52f7
+SHA512:
+  metadata.gz: 28ac83efab70d112ab6d0a3a99c8d82d49912201b1f646ea701374fcb21acb71ca7a30741595980dfbb55e658737e5ed05eac1570646cfeccf74af8e1c6d2312
+  data.tar.gz: a7cf692ee5e95c9c865a909c691370bd33b90646704fa18546fa190de752788e602b59625f187698c0bb9246bdc5dca9607523f2cba4f9ef3ae3110e21cdf521

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Haydarov
+
+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,89 @@
+# fast_string
+
+High-performance Ruby `String` extensions implemented in **C**.
+
+[![Gem Version](https://badge.fury.io/rb/fast_string.svg)](https://badge.fury.io/rb/fast_string)
+[![Ruby](https://github.com/roman-haidarov/fast_string/workflows/Ruby/badge.svg)](https://github.com/roman-haidarov/fast_string/actions)
+
+Optimized string methods for high-throughput workloads: log processing, CSV parsing, HTTP parsing, text analytics, streaming pipelines.
+
+## Installation
+
+```ruby
+gem 'fast_string'
+```
+
+## Usage
+
+```ruby
+require 'fast_string'
+
+"hello".fs_count("l")                     #=> 2
+"line1\nline2\nline3".fs_lines            #=> 2
+"   \t\n  ".fs_blank?                     #=> true
+"  hello  ".fs_trim                       #=> "hello"
+"hello\nworld".fs_byte_replace("\n", " ") #=> "hello world"
+"hello\r\nworld".fs_byte_delete("\r")     #=> "hello\nworld"
+
+data.fs_each_line { |line| puts line }
+```
+
+## API
+
+| Method | Ruby equivalent | What it does |
+|---|---|---|
+| `fs_count(char)` | `str.count(char)` | Count occurrences of a single byte |
+| `fs_lines` | `str.count("\n")` | Count newline characters |
+| `fs_blank?` | `str.strip.empty?` | Check if string is whitespace-only |
+| `fs_trim` | `str.strip` | Strip whitespace (zero-copy) |
+| `fs_byte_replace(from, to)` | `str.tr(from, to)` | Replace one byte with another |
+| `fs_byte_delete(char)` | `str.delete(char)` | Delete all occurrences of a byte |
+| `fs_each_line { }` | `str.each_line { }` | Iterate lines via memchr |
+
+All methods operate at **byte level** using `memchr` and direct memory access. Single-character arguments only.
+
+`fs_trim` returns a zero-copy shared substring — no `memcpy` unlike Ruby's `strip`.
+
+`fs_byte_replace` and `fs_byte_delete` return new strings; originals are not mutated.
+
+## Benchmark
+
+Apple Silicon (M1), Ruby 2.7. Numbers are **times faster** than Ruby stdlib equivalent:
+
+| Method | 42KB | 10MB | 9.6MB CSV | 38MB Log | 5.8MB Unicode |
+|---|---|---|---|---|---|
+| `fs_count` | 1.8x | 7.9x | 6.2x | 9.0x | 9.2x |
+| `fs_lines` | 1.9x | 7.9x | 6.2x | 9.0x | 9.1x |
+| `fs_blank?` | 4.1x | 4.0x | 4.0x | 4.0x | 4.1x |
+| `fs_trim` | 3.8x | 4.0x | 4.0x | 3.9x | 4.0x |
+| `fs_byte_replace` | 5.7x | 15.0x | 13.0x | **16.1x** | **67.9x** |
+| `fs_byte_delete` | 3.8x | 13.5x | 12.2x | **15.1x** | **33.2x** |
+| `fs_each_line` | 1.1x | 1.1x | 1.0x | 1.1x | 1.0x |
+
+`fs_byte_replace` and `fs_byte_delete` show the largest gains because Ruby's `tr` and `delete` go through the encoding layer per character, while fast_string uses `memchr` to skip non-matching regions in bulk.
+
+```bash
+ruby benchmark/benchmark.rb
+```
+
+## Requirements
+
+- Ruby >= 2.7.0
+- C compiler (GCC, Clang)
+
+## Platforms
+
+Linux, macOS, BSD, ARM (Apple Silicon), x86_64
+
+## Development
+
+```bash
+bundle install
+rake compile
+ruby test_basic.rb
+ruby benchmark/benchmark.rb
+```
+
+## License
+
+MIT

data/benchmark/benchmark.rb

@@ -0,0 +1,82 @@
+require 'benchmark'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'fast_string'
+
+small_data = "hello\nworld\ntest line with some text here\n" * 1000
+medium_data = "This is a longer test line with various characters and symbols @#$%^&*().\nAnother line here with different content and more text to process.\nYet another line with even more content to make this realistic.\n" * 50000
+csv_data = ("user_id,name,email,age,city,country\n" + "12345,John Doe,john@example.com,30,New York,USA\n" * 200000).freeze
+log_data = ("2024-01-01T10:30:45.123Z [INFO ] ApplicationController - Processing request\n" * 500000).freeze
+mixed_unicode = "ASCII text here with some unicode: тест, 测试, مرحبا, こんにちは\n" * 100000
+
+puts "FastString Benchmark Results"
+puts "=" * 50
+puts
+
+puts "Test data sizes:"
+puts "Small:  #{small_data.length} bytes"
+puts "Medium: #{medium_data.length} bytes"
+puts "CSV:    #{csv_data.length} bytes"
+puts "Log:    #{log_data.length} bytes"
+puts "Mixed:  #{mixed_unicode.length} bytes"
+puts
+
+test_cases = [
+  ["Small Data", small_data],
+  ["Medium Data", medium_data],
+  ["CSV Data", csv_data],
+  ["Log Data", log_data],
+  ["Mixed Unicode", mixed_unicode]
+]
+
+test_cases.each do |name, data|
+  puts "#{name} (#{data.length} bytes):"
+  puts "-" * 30
+
+  puts "Counting newline characters:"
+  Benchmark.bm(19) do |x|
+    x.report("ruby count") { 1000.times { data.count("\n") } }
+    x.report("fs_count")   { 1000.times { data.fs_count("\n") } }
+    x.report("fs_lines")   { 1000.times { data.fs_lines } }
+  end
+  puts
+
+  whitespace_data = "   \t\n\r  " * (data.length / 20)
+  puts "Checking blank string:"
+  Benchmark.bm(19) do |x|
+    x.report("ruby strip.empty?") { 1000.times { whitespace_data.strip.empty? } }
+    x.report("fs_blank?")         { 1000.times { whitespace_data.fs_blank? } }
+  end
+  puts
+
+  puts "Stripping whitespace:"
+  Benchmark.bm(19) do |x|
+    x.report("ruby strip") { 1000.times { whitespace_data.strip } }
+    x.report("fs_trim")    { 1000.times { whitespace_data.fs_trim } }
+  end
+  puts
+
+  puts "Replacing byte (\\n -> space):"
+  Benchmark.bm(19) do |x|
+    x.report("ruby tr")          { 100.times { data.tr("\n", " ") } }
+    x.report("fs_byte_replace")  { 100.times { data.fs_byte_replace("\n", " ") } }
+  end
+  puts
+
+  puts "Deleting byte (\\r):"
+  crlf_data = data.gsub("\n", "\r\n")
+  Benchmark.bm(19) do |x|
+    x.report("ruby delete")     { 100.times { crlf_data.delete("\r") } }
+    x.report("fs_byte_delete")  { 100.times { crlf_data.fs_byte_delete("\r") } }
+  end
+  puts
+
+  puts "Iterating lines:"
+  Benchmark.bm(19) do |x|
+    x.report("ruby each_line") { 100.times { data.each_line { |line| line.length } } }
+    x.report("fs_each_line")   { 100.times { data.fs_each_line { |line| line.length } } }
+  end
+
+  puts "=" * 50
+  puts
+end

data/ext/fast_string/extconf.rb

@@ -0,0 +1,50 @@
+require 'mkmf'
+
+# Add optimization flags for maximum performance
+$CFLAGS += " -O3 -funroll-loops -ffast-math"
+
+# Additional performance flags
+$CFLAGS += " -DNDEBUG"  # Disable debug assertions
+
+# SIMD support detection and flags
+def check_simd_support
+  # Check for AVX2 support
+  if try_compile("#include <immintrin.h>\nint main() { __m256i v = _mm256_setzero_si256(); return 0; }")
+    puts "AVX2 support detected"
+    $CFLAGS += " -mavx2"
+  # Check for SSE4.1 support
+  elsif try_compile("#include <smmintrin.h>\nint main() { __m128i v = _mm_setzero_si128(); return 0; }")
+    puts "SSE4.1 support detected"
+    $CFLAGS += " -msse4.1"
+  else
+    puts "No advanced SIMD support detected, using scalar fallback"
+  end
+  
+  # Check for ARM NEON on ARM platforms
+  if RUBY_PLATFORM =~ /arm|aarch64/i
+    if try_compile("#include <arm_neon.h>\nint main() { uint8x16_t v = vdupq_n_u8(0); return 0; }")
+      puts "ARM NEON support detected"
+      $CFLAGS += " -mfpu=neon" if RUBY_PLATFORM !~ /aarch64/i
+    end
+  end
+end
+
+# Enable native arch optimizations if supported
+if try_compile("int main() { return 0; }", "-march=native")
+  $CFLAGS += " -march=native"
+  puts "Using -march=native for optimal performance"
+else
+  puts "march=native not supported, using manual SIMD detection"
+  check_simd_support
+end
+
+# Check for required headers and functions
+have_header('immintrin.h')
+have_header('smmintrin.h') 
+have_header('arm_neon.h')
+
+# Ensure we have string.h and required Ruby functions
+abort "string.h is required" unless have_header('string.h')
+abort "Ruby encoding functions not available" unless have_func('rb_enc_get', 'ruby/encoding.h')
+
+create_makefile('fast_string/fast_string')

data/ext/fast_string/fast_string.c

@@ -0,0 +1,166 @@
+#include <ruby.h>
+#include <string.h>
+#include <stdint.h>
+
+static const int whitespace_table[256] = {
+    [' '] = 1, ['\t'] = 1, ['\n'] = 1, ['\r'] = 1, ['\f'] = 1, ['\v'] = 1
+};
+
+static VALUE rb_string_fs_count(VALUE self, VALUE target) {
+    Check_Type(target, T_STRING);
+    if (RSTRING_LEN(target) != 1)
+        rb_raise(rb_eArgError, "target must be a single character");
+
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    unsigned char target_char = (unsigned char)RSTRING_PTR(target)[0];
+    long count = 0;
+    char *current = ptr;
+    char *end = ptr + len;
+
+    while (current < end) {
+        char *found = memchr(current, target_char, end - current);
+        if (found == NULL) break;
+        count++;
+        current = found + 1;
+    }
+    return LONG2NUM(count);
+}
+
+static VALUE rb_string_fs_lines(VALUE self) {
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    long count = 0;
+    char *current = ptr;
+    char *end = ptr + len;
+
+    while (current < end) {
+        char *found = memchr(current, '\n', end - current);
+        if (found == NULL) break;
+        count++;
+        current = found + 1;
+    }
+    return LONG2NUM(count);
+}
+
+static VALUE rb_string_fs_blank(VALUE self) {
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+
+    for (long i = 0; i < len; i++) {
+        if (!whitespace_table[(unsigned char)ptr[i]])
+            return Qfalse;
+    }
+    return Qtrue;
+}
+
+static VALUE rb_string_fs_each_line(VALUE self) {
+    RETURN_ENUMERATOR(self, 0, 0);
+
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    if (len == 0) return self;
+
+    char *current = ptr;
+    char *end = ptr + len;
+
+    while (current < end) {
+        char *found = memchr(current, '\n', end - current);
+        long line_len = found ? (found - current + 1) : (end - current);
+        rb_yield(rb_str_subseq(self, current - ptr, line_len));
+        current += line_len;
+    }
+    return self;
+}
+
+static VALUE rb_string_fs_trim(VALUE self) {
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    long start = 0;
+    long end = len;
+
+    while (start < end && whitespace_table[(unsigned char)ptr[start]])
+        start++;
+    while (end > start && whitespace_table[(unsigned char)ptr[end - 1]])
+        end--;
+
+    if (start == 0 && end == len)
+        return rb_str_dup(self);
+
+    return rb_str_subseq(self, start, end - start);
+}
+
+static VALUE rb_string_fs_byte_replace(VALUE self, VALUE from, VALUE to) {
+    Check_Type(from, T_STRING);
+    Check_Type(to, T_STRING);
+    if (RSTRING_LEN(from) != 1 || RSTRING_LEN(to) != 1)
+        rb_raise(rb_eArgError, "from and to must be single characters");
+
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    unsigned char from_byte = (unsigned char)RSTRING_PTR(from)[0];
+    unsigned char to_byte = (unsigned char)RSTRING_PTR(to)[0];
+
+    if (from_byte == to_byte)
+        return rb_str_dup(self);
+
+    VALUE result = rb_str_new(ptr, len);
+    rb_enc_associate(result, rb_enc_get(self));
+    char *out = RSTRING_PTR(result);
+    char *current = out;
+    char *end = out + len;
+
+    while (current < end) {
+        char *found = memchr(current, from_byte, end - current);
+        if (found == NULL) break;
+        *found = (char)to_byte;
+        current = found + 1;
+    }
+    return result;
+}
+
+static VALUE rb_string_fs_byte_delete(VALUE self, VALUE target) {
+    Check_Type(target, T_STRING);
+    if (RSTRING_LEN(target) != 1)
+        rb_raise(rb_eArgError, "target must be a single character");
+
+    char *ptr = RSTRING_PTR(self);
+    long len = RSTRING_LEN(self);
+    unsigned char target_byte = (unsigned char)RSTRING_PTR(target)[0];
+
+    VALUE result = rb_str_buf_new(len);
+    rb_enc_associate(result, rb_enc_get(self));
+    char *out = RSTRING_PTR(result);
+    long out_len = 0;
+    char *current = ptr;
+    char *end = ptr + len;
+
+    while (current < end) {
+        char *found = memchr(current, target_byte, end - current);
+        if (found == NULL) {
+            long chunk = end - current;
+            memcpy(out + out_len, current, chunk);
+            out_len += chunk;
+            break;
+        }
+        long chunk = found - current;
+        if (chunk > 0) {
+            memcpy(out + out_len, current, chunk);
+            out_len += chunk;
+        }
+        current = found + 1;
+    }
+
+    rb_str_set_len(result, out_len);
+    return result;
+}
+
+void Init_fast_string(void) {
+    rb_define_method(rb_cString, "fs_count",        rb_string_fs_count,        1);
+    rb_define_method(rb_cString, "fs_lines",        rb_string_fs_lines,        0);
+    rb_define_method(rb_cString, "fs_blank?",       rb_string_fs_blank,        0);
+    rb_define_method(rb_cString, "fs_each_line",    rb_string_fs_each_line,    0);
+    rb_define_method(rb_cString, "fs_trim",         rb_string_fs_trim,         0);
+    rb_define_method(rb_cString, "fs_byte_replace", rb_string_fs_byte_replace, 2);
+    rb_define_method(rb_cString, "fs_byte_delete",  rb_string_fs_byte_delete,  1);
+}

data/lib/fast_string/version.rb

@@ -0,0 +1,3 @@
+module FastString
+  VERSION = "0.1.0"
+end

data/lib/fast_string.rb

@@ -0,0 +1,21 @@
+require 'fast_string/version'
+
+# Load the compiled extension (.so on Linux, .bundle on macOS)
+begin
+  require 'fast_string/fast_string'
+rescue LoadError
+  # Fallback for different extension names
+  ext_dir = File.expand_path('../fast_string', __FILE__)
+  if File.exist?(File.join(ext_dir, 'fast_string.bundle'))
+    require File.join(ext_dir, 'fast_string.bundle')
+  elsif File.exist?(File.join(ext_dir, 'fast_string.so'))
+    require File.join(ext_dir, 'fast_string.so')
+  else
+    raise LoadError, "Could not find compiled extension"
+  end
+end
+
+# The C extension will automatically extend String class with fs_ methods
+module FastString
+  # Module can be used for future utility methods if needed
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: fast_string
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roman Haydarov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Minimal set of optimized string scanning methods for high-throughput
+  workloads like log processing, CSV parsing, HTTP parsing, and text analytics. Pure
+  C implementation with no external dependencies.
+email:
+- romnhajdarov@gmail.com
+executables: []
+extensions:
+- ext/fast_string/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- benchmark/benchmark.rb
+- ext/fast_string/extconf.rb
+- ext/fast_string/fast_string.c
+- lib/fast_string.rb
+- lib/fast_string/version.rb
+homepage: https://github.com/roman-haidarov/fast_string
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/roman-haidarov/fast_string
+  source_code_uri: https://github.com/roman-haidarov/fast_string
+  changelog_uri: https://github.com/roman-haidarov/fast_string/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: High-performance Ruby String extensions implemented in C
+test_files: []