ob64 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8b76a774595914a6124939fe2410fe4ae5bb0687286315ab4ec1f05b8569d70
-  data.tar.gz: 662b74f7505f28362436d44771e51720884cf0ea48076b12e59094eacf4e87b6
+  metadata.gz: 93d2eaeaa970d18c2ab92ff9f5bb4621c22135c16faa0f1ef09ac71babe94b95
+  data.tar.gz: 7bad60e17ca1b3189634cb2043d58bf1ffa85c701deff0b99886dde4a34082e1
 SHA512:
-  metadata.gz: b0e357acff49af3e42b36cb41b521393ed4f6604fc4f5943c491a504741b985d5a47e63217acd27e0896cb2b23a8df2412fe133fff1d76d275decc5cf0a39f7f
-  data.tar.gz: 560f3439cff65bc442f16a8815afa729422e6286f6305a044f92035bf28666b80c80c8471ffd7ac0b83379ea999643a531ef9a5905449093dafe10cff36490e9
+  metadata.gz: fc8c44a79e33c420a13c1d4460a2773ed6d60ff0e4eab47ea5ad0a1db4365d85c4e642e442dfa4a2753ef0153f8bde876dca4867005f28c124f4b7251b06e55d
+  data.tar.gz: 61b2550bc2035667a86d6bfd87149fcba0bd3faa33d9e29c6f42f89cef8be2b5e5df6a36a35682e2cb9d193ea1252ee7d37bcb1d787d0c62cfa78d1618218144

data/.github/scripts/install-sde

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Installs Intel SDE if this CPU can't run the avx512 codec, and exports SDE,
+# a command prefix that emulates a CPU that can.
+set -euo pipefail
+
+missing=
+for flag in avx512vl avx512vbmi avx512_vbmi2; do
+  grep -qw "$flag" /proc/cpuinfo || missing=1
+done
+[ -n "$missing" ] || exit 0
+
+url=https://downloadmirror.intel.com/924984/sde-external-10.13.1-2026-07-28-lin.tar.xz
+sha256=94e97d623fec54385686e1e7ba65ebc9941748c05ee451423948334892bf2b50
+dir="$RUNNER_TEMP/sde"
+
+curl -fsSL -o "$dir.tar.xz" "$url"
+echo "$sha256  $dir.tar.xz" | sha256sum -c --quiet
+mkdir -p "$dir"
+tar xJf "$dir.tar.xz" -C "$dir" --strip-components=1
+# Ice Lake: AVX512 with VBMI and VBMI2
+echo "SDE=$dir/sde64 -icl --" >>"$GITHUB_ENV"

data/.github/workflows/main.yml

@@ -36,8 +36,15 @@ jobs:
         ruby: ["3.3", "3.4", "4.0"]
         os: [ubuntu-24.04, ubuntu-24.04-arm]
         cc: [gcc, clang]
+        include:
+          # Ruby built with AddressSanitizer, x86-64 only: memory errors in the
+          # C code fail the specs. ubsan adds UndefinedBehaviorSanitizer.
+          - ruby: asan-release
+            os: ubuntu-24.04
+            cc: clang
+            ubsan: true
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -55,14 +62,57 @@ jobs:
       - name: Compile
         env:
           # Same warnings for both compilers; Ruby's defaults are GCC-only.
-          MAKEFLAGS: 'CC=${{ matrix.cc }} warnflags=-Wall\ -Wextra\ -Wno-unused-parameter\ -Werror'
+          MAKEFLAGS: >-
+            CC=${{ matrix.cc }}${{ matrix.ubsan && '\ -fsanitize=undefined\ -fno-sanitize-recover=all' || '' }}
+            warnflags=-Wall\ -Wextra\ -Wno-unused-parameter\ -Werror
         run: bundle exec rake compile
 
+      - name: Install Intel SDE if the CPU lacks AVX512
+        if: runner.arch == 'X64'
+        run: .github/scripts/install-sde
+
       - name: Show codecs
-        run: bundle exec ruby -Ilib -rob64 -e 'p Ob64.codecs, Ob64.codec'
+        run: $SDE bundle exec ruby -Ilib -rob64 -e 'p Ob64.codecs, Ob64.codec'
+
+      - name: Test
+        env:
+          # Fails the codec spec if one is missing
+          OB64_CODECS: ${{ runner.arch == 'X64' && 'scalar,avx2,avx512' || 'scalar,neon64' }}
+        run: $SDE bundle exec rake spec
+
+  codecs:
+    # The C codecs alone under ASan and UBSan, on exact-size buffers.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+        cc: [gcc, clang]
+    runs-on: ${{ matrix.os }}
+    # Long under SDE, which emulates AVX512 slowly
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Install Clang
+        if: matrix.cc == 'clang'
+        run: command -v clang || { sudo apt-get update && sudo apt-get install -y clang; }
+
+      - name: Install Intel SDE if the CPU lacks AVX512
+        if: runner.arch == 'X64'
+        run: .github/scripts/install-sde
 
       - name: Test
-        run: bundle exec rake spec
+        env:
+          CC: ${{ matrix.cc }}
+          OB64_CODECS: ${{ runner.arch == 'X64' && 'scalar,avx2,avx512' || 'scalar,neon64' }}
+        run: bundle exec rake spec:c
 
   package:
     runs-on: ubuntu-24.04
@@ -89,7 +139,8 @@ jobs:
             require "ob64"
             require "ob64/core_ext"
             s = Random.bytes(4096)
-            abort "Base64 round trip failed" unless Ob64::Base64.decode(Ob64::Base64.encode(s)) == s
+            abort "RFC 4648 round trip failed" unless Ob64::Base64::RFC4648.decode(Ob64::Base64::RFC4648.encode(s)) == s
+            abort "RFC 2045 round trip failed" unless Ob64::Base64::RFC2045.decode(Ob64::Base64::RFC2045.encode(s)) == s
             abort "UU round trip failed" unless Ob64::UU.decode(Ob64::UU.encode(s)) == s
             abort "pack round trip failed" unless [s].pack("m0").unpack1("m0") == s
           '

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.8.0] - 2026-10-27
+
+- Fix undefined behavior in AVX512 detection.
+- `Ob64::Base64::RFC4648.encode` and `encode_urlsafe` return US-ASCII Strings, like `pack("m0")` (were BINARY).
+
+## [0.7.0] - 2026-10-26
+
+- **Breaking:** Split `Ob64::Base64` into one module per RFC. `Ob64::Base64::RFC4648` has `encode`, `decode`, `encode_urlsafe`, `decode_urlsafe`, `encoded_length_of` and `decoded_length_of` (were `Ob64::Base64.encode`, `decode`, `urlsafe_encode`, `urlsafe_decode`, `encoded_length_of` and `decoded_length_of`).
+- Add `Ob64::Base64::RFC2045` with `encode` (optionally with CRLF line breaks), `decode`, `encoded_length_of` and `decoded_length_of`, like `pack("m")` and `unpack1("m")`.
+
 ## [0.6.0] - 2026-10-26
 
 - **Breaking:** `ob64/core_ext` patches `Array#pack`, `String#unpack` and `String#unpack1` instead of `Base64`.

data/Gemfile

@@ -5,7 +5,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "benchmark-ips"
-gem "byebug"
+gem "debug"
 gem "guard"
 gem "guard-rspec"
 gem "rake", "~> 13.0"

data/README.md

@@ -2,13 +2,56 @@
 
 [![Gem Version](https://badge.fury.io/rb/ob64.svg)](http://rubygems.org/gems/ob64)
 [![CI](https://github.com/jcmfernandes/ob64/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/jcmfernandes/ob64/actions/workflows/main.yml)
-[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/ob64/0.6.0)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/ob64/0.8.0)
 
 A *fast* Base64 and uuencode encoder and decoder as a Ruby gem.
 
-How fast? Try it yourself, execute:
+How fast? Times faster than Ruby's own `pack` / `unpack1`, per call, measured with `benchmark.rb` on an AMD Ryzen 9 9900X (AVX512) with Ruby 3.4:
 
-    $ rake benchmark
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "1 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [3.1, 4.8, 11.1, 12.6, 5.2, 3.9, 5.9, 4.2]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "4 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [6.3, 8.4, 17.6, 22.9, 8.4, 6.1, 7.5, 5.2]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "16 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [11.1, 12.6, 24.3, 32.8, 6.0, 7.0, 7.2, 5.3]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "512 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [14.0, 13.8, 39.2, 42.0, 7.7, 7.6, 7.3, 5.3]
+```
+
+- `m0`: RFC 4648 (`Ob64::Base64::RFC4648.encode` / `decode`)
+- `url`: RFC 4648 URL-safe (`encode_urlsafe` / `decode_urlsafe`), against Ruby's `pack("m0")` plus `tr`
+- `m`: RFC 2045 (`Ob64::Base64::RFC2045.encode` / `decode`)
+- `u`: uuencode (`Ob64::UU.encode` / `decode`)
+
+Try it yourself:
+
+    $ bin/rake compile benchmark
 
 ## Acknowledgements
 
@@ -40,26 +83,34 @@ require "ob64"
 
 ### Base64
 
+One module per RFC, each with `encode`, `decode`, `encoded_length_of` and `decoded_length_of`.
+
+RFC 4648, no line breaks, same output as `pack("m0")` / `unpack1("m0")`:
+
 ```ruby
 bin1 = "This is data!"
-string = Ob64::Base64.encode(bin1)
+string = Ob64::Base64::RFC4648.encode(bin1)
 # string = "VGhpcyBpcyBkYXRhIQ=="
 
-bin2 = Ob64::Base64.decode(string)
+bin2 = Ob64::Base64::RFC4648.decode(string)
 puts "Same? #{bin1 == bin2}"
 # "Same? true"
+
+Ob64::Base64::RFC4648.decode("VGhpcyBpcyBkYXRhIQ", loose: true)  # padding optional
+Ob64::Base64::RFC4648.encode_urlsafe(bin1, padding: false)        # '-' and '_' instead of '+' and '/'
+Ob64::Base64::RFC4648.decode_urlsafe(string)
 ```
 
-Decode input with or without padding:
+Bad padding, non-zero trailing bits and non-alphabet characters raise `ArgumentError`.
+
+RFC 2045 (MIME), line-wrapped, same output as `pack("m")` / `unpack1("m")`:
 
 ```ruby
-Ob64::Base64.decode("VGhpcyBpcyBkYXRhIQ", loose: true)
+Ob64::Base64::RFC2045.encode(bin)              # 60-char lines, each ending in "\n"
+Ob64::Base64::RFC2045.encode(bin, 76, crlf: true)
+Ob64::Base64::RFC2045.decode(string)           # skips line breaks and other non-alphabet characters
 ```
 
-Bad padding, non-zero trailing bits and non-alphabet characters still raise `ArgumentError`.
-
-URL-safe alphabet: `Ob64::Base64.urlsafe_encode(bin, padding: false)`, `Ob64::Base64.urlsafe_decode(string)`.
-
 ### uuencode
 
 Same output as `pack("u")` / `unpack1("u")`:
@@ -107,7 +158,7 @@ See [{file:CHANGELOG.md}](CHANGELOG.md).
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests, and `rake spec:c` to check the C codecs for memory errors. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 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).
 
@@ -118,8 +169,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jcmfer
 ## TODO
 
 * Streaming interface
-* RFC 2045 (MIME) encoding/decoding
-* Windows support
 
 ## License
 

data/Rakefile

@@ -14,6 +14,17 @@ Rake::ExtensionTask.new("ob64_ext") do |ext|
   ext.ext_dir = "ext/ob64"
 end
 
+desc "Check the SIMD codecs against scalar in C, under ASan and UBSan; SEED=n repeats a run"
+task "spec:c" do
+  mkdir_p "tmp"
+  sh "#{ENV.fetch("CC", "cc")} -std=gnu99 -O3 -g -fsanitize=address,undefined -fno-sanitize-recover=all " \
+    "-fno-omit-frame-pointer -Wall -Wextra -Wno-unused-parameter -Werror -Iext/ob64 -o tmp/codecs_test " \
+    "spec/c/codecs_test.c ext/ob64/pack_base64.c ext/ob64/pack_uuencode.c"
+  # SDE: an emulator prefix, see .github/scripts/install-sde. It must run the test
+  # itself: under SDE, ASan programs started by another one exit 0 unrun.
+  sh "#{ENV["SDE"]} tmp/codecs_test #{ENV["SEED"]}"
+end
+
 desc "Run benchmark"
 task :benchmark do
   load "#{__dir__}/benchmark.rb"

data/benchmark.rb

@@ -41,28 +41,30 @@ each_size do |bin|
 
   compare(
     "Ruby pack(\"m0\")" => -> { NATIVE_PACK.bind_call([bin], "m0") },
-    "ob64 Base64.encode" => -> { Ob64::Base64.encode(bin) },
+    "ob64 Base64::RFC4648.encode" => -> { Ob64::Base64::RFC4648.encode(bin) },
     "ob64 pack(\"m0\")" => -> { [bin].pack("m0") }
   )
   compare(
     "Ruby unpack1(\"m0\")" => -> { NATIVE_UNPACK1.bind_call(m0, "m0") },
-    "ob64 Base64.decode" => -> { Ob64::Base64.decode(m0) },
+    "ob64 Base64::RFC4648.decode" => -> { Ob64::Base64::RFC4648.decode(m0) },
     "ob64 unpack1(\"m0\")" => -> { m0.unpack1("m0") }
   )
   compare(
     "Ruby pack(\"m0\").tr" => -> { NATIVE_PACK.bind_call([bin], "m0").tr("+/", "-_") },
-    "ob64 Base64.urlsafe_encode" => -> { Ob64::Base64.urlsafe_encode(bin) }
+    "ob64 Base64::RFC4648.encode_urlsafe" => -> { Ob64::Base64::RFC4648.encode_urlsafe(bin) }
   )
   compare(
     "Ruby tr.unpack1(\"m0\")" => -> { NATIVE_UNPACK1.bind_call(urlsafe.tr("-_", "+/"), "m0") },
-    "ob64 Base64.urlsafe_decode" => -> { Ob64::Base64.urlsafe_decode(urlsafe) }
+    "ob64 Base64::RFC4648.decode_urlsafe" => -> { Ob64::Base64::RFC4648.decode_urlsafe(urlsafe) }
   )
   compare(
     "Ruby pack(\"m\")" => -> { NATIVE_PACK.bind_call([bin], "m") },
+    "ob64 Base64::RFC2045.encode" => -> { Ob64::Base64::RFC2045.encode(bin) },
     "ob64 pack(\"m\")" => -> { [bin].pack("m") }
   )
   compare(
     "Ruby unpack1(\"m\")" => -> { NATIVE_UNPACK1.bind_call(m, "m") },
+    "ob64 Base64::RFC2045.decode" => -> { Ob64::Base64::RFC2045.decode(m) },
     "ob64 unpack1(\"m\")" => -> { m.unpack1("m") }
   )
 end if $run_base64_benchmark

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/ext/ob64/ob64_ext.c

@@ -1,5 +1,6 @@
 #include <stdbool.h>
 #include "ob64.h"
+#include "ruby/encoding.h"
 
 VALUE mOb64 = Qnil;
 VALUE mOb64_Ext = Qnil;
@@ -51,6 +52,8 @@ VALUE Ob64_encode_string(VALUE self, VALUE bin, VALUE urlsafe, VALUE padding)
 
   pack_base64_encode(RSTRING_PTR(bin), bin_len, RSTRING_PTR(result), flags);
   rb_str_set_len(result, __encoded_length_of(bin_len, RTEST(padding)));
+  /* US-ASCII, as pack("m0") */
+  ENCODING_CODERANGE_SET(result, rb_usascii_encindex(), ENC_CODERANGE_7BIT);
   RB_GC_GUARD(bin);
 
   return result;

data/ext/ob64/ob64_pack.c

@@ -60,6 +60,20 @@ uuencode(VALUE from, long line_len)
   return ascii_result(res, n);
 }
 
+/* line_len: bytes per line, a multiple of 3; crlf: lines end in "\r\n" */
+static VALUE
+base64_encode_rfc2045(VALUE from, long line_len, int crlf)
+{
+  long plen = RSTRING_LEN(from);
+  /* A line break per line */
+  long lines = (plen + line_len - 1) / line_len;
+  VALUE res = rb_str_buf_new((plen + 2) / 3 * 4 + lines * (crlf ? 2 : 1));
+  size_t n = pack_base64_encode_rfc2045(RSTRING_PTR(from), (size_t)plen, RSTRING_PTR(res), (int)line_len, crlf);
+  RB_GC_GUARD(from);
+
+  return ascii_result(res, n);
+}
+
 static VALUE
 Ob64_pack(int argc, VALUE *argv, VALUE ary)
 {
@@ -75,31 +89,22 @@ Ob64_pack(int argc, VALUE *argv, VALUE ary)
     return rb_call_super_kw(argc, argv, RB_PASS_CALLED_KEYWORDS);
   }
 
-  VALUE res;
-  size_t n;
-
   if (type == 'm' && count == 0) {
-    res = rb_str_buf_new((plen + 2) / 3 * 4);
-    n = pack_base64_encode(RSTRING_PTR(from), (size_t)plen, RSTRING_PTR(res), 0);
-  }
-  else {
-    long len = count;
+    VALUE res = rb_str_buf_new((plen + 2) / 3 * 4);
+    size_t n = pack_base64_encode(RSTRING_PTR(from), (size_t)plen, RSTRING_PTR(res), 0);
+    RB_GC_GUARD(from);
 
-    /* '*' gets 45, as natively */
-    if (len <= 2) len = 45;
-    else if (len > 63 && type == 'u') len = 63;
-    else len = len / 3 * 3;
+    return ascii_result(res, n);
+  }
 
-    if (type == 'u') return uuencode(from, len);
+  long len = count;
 
-    /* A newline per line */
-    long lines = (plen + len - 1) / len;
-    res = rb_str_buf_new((plen + 2) / 3 * 4 + lines);
-    n = pack_base64_encode_rfc2045(RSTRING_PTR(from), (size_t)plen, RSTRING_PTR(res), (int)len);
-  }
-  RB_GC_GUARD(from);
+  /* '*' gets 45, as natively */
+  if (len <= 2) len = 45;
+  else if (len > 63 && type == 'u') len = 63;
+  else len = len / 3 * 3;
 
-  return ascii_result(res, n);
+  return type == 'u' ? uuencode(from, len) : base64_encode_rfc2045(from, len, 0);
 }
 
 static VALUE
@@ -174,6 +179,58 @@ Ob64_unpack1(int argc, VALUE *argv, VALUE str)
   return res;
 }
 
+/* Bytes per line for a line_length in chars; validates both arguments */
+static long
+rfc2045_line_bytes(VALUE bin, VALUE line_length)
+{
+  long chars = NUM2LONG(line_length);
+
+  StringValue(bin);
+  if (chars < 4 || chars % 4 || chars / 4 * 3 > INT_MAX) {
+    rb_raise(rb_eArgError, "line length must be a positive multiple of 4: %ld", chars);
+  }
+  /* Bound the output size */
+  if (RSTRING_LEN(bin) > LONG_MAX / 4) rb_raise(rb_eArgError, "argument too big");
+
+  return chars / 4 * 3;
+}
+
+static VALUE
+Ob64_encode_rfc_2045(VALUE self, VALUE bin, VALUE line_length, VALUE crlf)
+{
+  long line_bytes = rfc2045_line_bytes(bin, line_length);
+
+  return base64_encode_rfc2045(bin, line_bytes, RTEST(crlf));
+}
+
+static VALUE
+Ob64_decode_rfc_2045(VALUE self, VALUE string)
+{
+  StringValue(string);
+
+  return base64_decode(string, 1);
+}
+
+static VALUE
+Ob64_encoded_length_of_rfc_2045(VALUE self, VALUE bin, VALUE line_length, VALUE crlf)
+{
+  long line_bytes = rfc2045_line_bytes(bin, line_length);
+  long plen = RSTRING_LEN(bin);
+
+  /* 4 chars per 3 bytes, a line break per line */
+  return LONG2NUM((plen + 2) / 3 * 4 + (plen + line_bytes - 1) / line_bytes * (RTEST(crlf) ? 2 : 1));
+}
+
+static VALUE
+Ob64_decoded_length_of_rfc_2045(VALUE self, VALUE string)
+{
+  StringValue(string);
+  size_t n = pack_base64_decoded_length_rfc2045(RSTRING_PTR(string), (size_t)RSTRING_LEN(string));
+  RB_GC_GUARD(string);
+
+  return SIZET2NUM(n);
+}
+
 static VALUE
 Ob64_uuencode(VALUE self, VALUE bin)
 {
@@ -221,6 +278,10 @@ Init_ob64_pack(VALUE mExt)
   rb_define_method(mUnpack, "unpack", Ob64_unpack, -1);
   rb_define_method(mUnpack, "unpack1", Ob64_unpack1, -1);
 
+  rb_define_private_method(mExt, "__encode_rfc_2045", Ob64_encode_rfc_2045, 3);
+  rb_define_private_method(mExt, "__decode_rfc_2045", Ob64_decode_rfc_2045, 1);
+  rb_define_private_method(mExt, "__encoded_length_of_rfc_2045", Ob64_encoded_length_of_rfc_2045, 3);
+  rb_define_private_method(mExt, "__decoded_length_of_rfc_2045", Ob64_decoded_length_of_rfc_2045, 1);
   rb_define_private_method(mExt, "__uuencode", Ob64_uuencode, 1);
   rb_define_private_method(mExt, "__uudecode", Ob64_uudecode, 1);
   rb_define_private_method(mExt, "__uuencoded_length_of", Ob64_uuencoded_length_of, 1);

data/ext/ob64/pack_base64.c

@@ -4359,7 +4359,7 @@ pack_base64_xgetbv (uint32_t index)
 }
 
 #ifndef bit_AVX512vl
-#define bit_AVX512vl (1 << 31)
+#define bit_AVX512vl (1u << 31)
 #endif
 #ifndef bit_AVX512vbmi
 #define bit_AVX512vbmi (1 << 1)
@@ -4993,7 +4993,7 @@ pack_base64_decode (const char *src, size_t srclen, char *out, size_t *outlen, i
  * ====================================================================== */
 
 static size_t
-encode_rfc2045_plain(const char *src, size_t srclen, char *out, int bytes_per_line)
+encode_rfc2045_plain(const char *src, size_t srclen, char *out, int bytes_per_line, int crlf)
 {
     const uint8_t *s = (const uint8_t *)src;
     char *o = out;
@@ -5012,6 +5012,7 @@ encode_rfc2045_plain(const char *src, size_t srclen, char *out, int bytes_per_li
         srclen -= 3;
         line_bytes += 3;
         if (line_bytes >= bytes_per_line) {
+            if (crlf) *o++ = '\r';
             *o++ = '\n';
             line_bytes = 0;
         }
@@ -5022,6 +5023,7 @@ encode_rfc2045_plain(const char *src, size_t srclen, char *out, int bytes_per_li
         *o++ = base64_table_enc_6bit[((s[0] & 0x03) << 4) | (s[1] >> 4)];
         *o++ = base64_table_enc_6bit[(s[1] & 0x0F) << 2];
         *o++ = '=';
+        if (crlf) *o++ = '\r';
         *o++ = '\n';
     }
     else if (srclen == 1) {
@@ -5029,9 +5031,11 @@ encode_rfc2045_plain(const char *src, size_t srclen, char *out, int bytes_per_li
         *o++ = base64_table_enc_6bit[(s[0] & 0x03) << 4];
         *o++ = '=';
         *o++ = '=';
+        if (crlf) *o++ = '\r';
         *o++ = '\n';
     }
     else if (line_bytes > 0) {
+        if (crlf) *o++ = '\r';
         *o++ = '\n';
     }
 
@@ -5052,13 +5056,13 @@ encode_whole (const struct codec *codec, const char *src, size_t srclen, char *o
 }
 
 size_t
-pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_per_line)
+pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_per_line, int crlf)
 {
 	const struct codec *codec = codec_get();
 
 	bytes_per_line = bytes_per_line / 3 * 3;
 	if (bytes_per_line == 0) bytes_per_line = 45;
-	if (!codec->enc_loop) return encode_rfc2045_plain(src, srclen, out, bytes_per_line);
+	if (!codec->enc_loop) return encode_rfc2045_plain(src, srclen, out, bytes_per_line, crlf);
 
 	size_t line = (size_t)bytes_per_line;
 	size_t chars = line / 3 * 4;
@@ -5072,6 +5076,7 @@ pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_
 		if (lines_per_batch == 0) {
 			/* Lines longer than the buffer: encode in place */
 			o += encode_whole(codec, src, line, o);
+			if (crlf) *o++ = '\r';
 			*o++ = '\n';
 			lines = 1;
 		}
@@ -5081,6 +5086,7 @@ pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_
 			for (size_t i = 0; i < lines; i++) {
 				memcpy(o, buf + i * chars, chars);
 				o += chars;
+				if (crlf) *o++ = '\r';
 				*o++ = '\n';
 			}
 		}
@@ -5088,7 +5094,7 @@ pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_
 		srclen -= lines * line;
 	}
 
-	return (size_t)(o - out) + encode_rfc2045_plain(src, srclen, o, bytes_per_line);
+	return (size_t)(o - out) + encode_rfc2045_plain(src, srclen, o, bytes_per_line, crlf);
 }
 
 /*
@@ -5180,3 +5186,24 @@ pack_base64_decode_rfc2045(const char *src, size_t srclen, char *out)
 	if (n == 0) return (size_t)(o - (uint8_t *)out) + decode_rfc2045_from(s, end, o, NULL, 0);
 	return (size_t)(o - (uint8_t *)out) + decode_rfc2045_from(s, end, o, buf, n);
 }
+
+size_t
+pack_base64_decoded_length_rfc2045(const char *src, size_t srclen)
+{
+	const uint8_t *s = (const uint8_t *)src;
+	const uint8_t *end = s + srclen;
+	size_t n = 0;
+
+	/* Counts what pack_base64_decode_rfc2045 decodes: alphabet chars up to a '=' in group position 3-4 */
+	for (; s < end; s++) {
+		const uint8_t v = base64_table_dec_8bit[*s];
+
+		if (v == 255) continue;
+		if (v == 254) {
+			if (n % 4 >= 2) break;
+			continue;
+		}
+		n++;
+	}
+	return n / 4 * 3 + (n % 4 == 3 ? 2 : n % 4 == 2 ? 1 : 0);
+}

data/ext/ob64/pack_base64.h

@@ -27,7 +27,10 @@ size_t pack_base64_encode(const char *src, size_t srclen, char *out, int flags);
 int pack_base64_decode(const char *src, size_t srclen, char *out, size_t *outlen, int flags);
 
 /* RFC 2045 codec (m with line wrapping, lenient decode) */
-size_t pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_per_line);
+/* Lines end in "\r\n" if crlf, "\n" otherwise */
+size_t pack_base64_encode_rfc2045(const char *src, size_t srclen, char *out, int bytes_per_line, int crlf);
 size_t pack_base64_decode_rfc2045(const char *src, size_t srclen, char *out);
+/* Length pack_base64_decode_rfc2045 would return; reads all of src */
+size_t pack_base64_decoded_length_rfc2045(const char *src, size_t srclen);
 
 #endif /* PACK_BASE64_H */

data/lib/ob64/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ob64
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/ob64.rb

@@ -3,7 +3,8 @@
 require_relative "ob64/version"
 require_relative "ob64_ext"
 
-# Fast base64 and uuencode encoding and decoding: see {Base64} and {UU}.
+# Fast base64 and uuencode encoding and decoding: see {Base64::RFC4648},
+# {Base64::RFC2045} and {UU}.
 module Ob64
   # The glue between Ruby and the C codecs. See +../ext/ob64/ob64_ext.c+.
   module Ext; end
@@ -44,88 +45,150 @@ module Ob64
     codecs.last
   end
 
-  # Methods for base64-encoding and -decoding strings.
+  # Base64 encoding and decoding, one module per RFC: {RFC4648} and {RFC2045}.
   module Base64
-    include Ext
-    extend Ext
-
-    module_function
-
-    # Returns the Base64-encoded version of +bin+.
-    # This method complies with RFC 4648.
-    # No line feeds are added.
-    #
-    # @param bin [String]
-    # @return [String]
-    def encode(bin)
-      __encode(bin, false, true)
-    end
-
-    # Returns the Base64-decoded version of +string+.
-    # This method complies with RFC 4648.
-    # ArgumentError is raised if +string+ is incorrectly padded or contains
-    # non-alphabet characters. Note that CR or LF are also rejected.
-    #
-    # With +loose+, the padding character is optional: both correctly-padded
-    # and unpadded input are accepted. Incorrectly-padded input is still
-    # rejected.
-    #
-    # @param string [String]
-    # @param loose [Boolean] - if unpadded input is accepted
-    # @return [String]
-    # @raise [ArgumentError] if +string+ cannot be decoded
-    def decode(string, loose: false)
-      __decode(string, false, loose)
-    end
-
-    # Returns the Base64-encoded version of +bin+.
-    # This method complies with ``Base 64 Encoding with URL and Filename Safe
-    # Alphabet'' in RFC 4648.
-    # The alphabet uses '-' instead of '+' and '_' instead of '/'.
-    # Note that the result can still contain '='.
-    # You can remove the padding by setting +padding+ as false.
-    #
-    # @param bin [String]
-    # @param padding [Boolean] - if the output must be padded
-    # @return [String]
-    def urlsafe_encode(bin, padding: true)
-      __encode(bin, true, padding)
-    end
-
-    # Returns the Base64-decoded version of +string+.
-    # This method complies with ``Base 64 Encoding with URL and Filename Safe
-    # Alphabet'' in RFC 4648.
-    # The alphabet uses '-' instead of '+' and '_' instead of '/'.
-    #
-    # The padding character is optional.
-    # This method accepts both correctly-padded and unpadded input.
-    # Note that it still rejects incorrectly-padded input.
-    #
-    # @param string [String]
-    # @return [String]
-    # @raise [ArgumentError] if +string+ cannot be decoded
-    def urlsafe_decode(string)
-      __decode(string, true, true)
+    # Base64 as in RFC 4648: no line breaks, strict decoding.
+    module RFC4648
+      include Ext
+      extend Ext
+
+      module_function
+
+      # Returns the Base64-encoded version of +bin+, like
+      # <tt>[bin].pack("m0")</tt>. No line feeds are added.
+      #
+      # @param bin [String]
+      # @return [String]
+      def encode(bin)
+        __encode(bin, false, true)
+      end
+
+      # Returns the Base64-decoded version of +string+, like
+      # <tt>string.unpack1("m0")</tt>.
+      # ArgumentError is raised if +string+ is incorrectly padded or contains
+      # non-alphabet characters. Note that CR or LF are also rejected.
+      #
+      # With +loose+, the padding character is optional: both correctly-padded
+      # and unpadded input are accepted. Incorrectly-padded input is still
+      # rejected.
+      #
+      # @param string [String]
+      # @param loose [Boolean] - if unpadded input is accepted
+      # @return [String]
+      # @raise [ArgumentError] if +string+ cannot be decoded
+      def decode(string, loose: false)
+        __decode(string, false, loose)
+      end
+
+      # Returns the Base64-encoded version of +bin+ with the ``URL and Filename
+      # Safe'' alphabet: '-' instead of '+' and '_' instead of '/'.
+      # Note that the result can still contain '='.
+      # You can remove the padding by setting +padding+ as false.
+      #
+      # @param bin [String]
+      # @param padding [Boolean] - if the output must be padded
+      # @return [String]
+      def encode_urlsafe(bin, padding: true)
+        __encode(bin, true, padding)
+      end
+
+      # Returns the Base64-decoded version of +string+ with the ``URL and
+      # Filename Safe'' alphabet: '-' instead of '+' and '_' instead of '/'.
+      #
+      # The padding character is optional.
+      # This method accepts both correctly-padded and unpadded input.
+      # Note that it still rejects incorrectly-padded input.
+      #
+      # @param string [String]
+      # @return [String]
+      # @raise [ArgumentError] if +string+ cannot be decoded
+      def decode_urlsafe(string)
+        __decode(string, true, true)
+      end
+
+      # Returns the length of {encode} (or, with the same +padding+,
+      # {encode_urlsafe}) of +bin+.
+      #
+      # Fast: computed from +bin+'s length.
+      #
+      # @param bin [String]
+      # @param padding [Boolean] - if the Base64-encoded version of +bin+ will be padded
+      # @return [Integer]
+      def encoded_length_of(bin, padding: true)
+        __encoded_length_of(bin, padding)
+      end
+
+      # Returns the length of {decode} (or {decode_urlsafe}) of +string+,
+      # padded or not.
+      #
+      # Fast: computed from +string+'s length and its last two characters. It
+      # doesn't validate the rest, so decoding may still raise.
+      #
+      # @param string [String]
+      # @return [Integer]
+      # @raise [ArgumentError] if +string+ has an invalid length
+      def decoded_length_of(string)
+        __decoded_length_of(string)
+      end
     end
 
-    # Returns the length of the Base64-encoded version of +bin+.
-    #
-    # @param bin [String]
-    # @param padding [Boolean] - if the Base64-encoded version of +bin+ will be padded
-    # @return [Integer]
-    def encoded_length_of(bin, padding: true)
-      __encoded_length_of(bin, padding)
-    end
-
-    # Returns the length of the Base64-decoded version of +string+.
-    #
-    # ArgumentError is raised if +string+ has an invalid length.
-    #
-    # @param string [String]
-    # @return [Integer]
-    # @raise [ArgumentError] if +string+ has an invalid length
-    def decoded_length_of(string)
-      __decoded_length_of(string)
+    # Base64 as in RFC 2045 (MIME): line breaks, lenient decoding.
+    module RFC2045
+      include Ext
+      extend Ext
+
+      module_function
+
+      # Returns the Base64-encoded version of +bin+ in lines of +line_length+
+      # characters, each ending in a line break. Like <tt>[bin].pack("m")</tt>
+      # by default; with +crlf+, lines end in "\r\n", as MIME requires.
+      # RFC 2045 allows lines of up to 76 characters; longer ones are allowed
+      # here, as in +pack+, but break the RFC.
+      #
+      # @param bin [String]
+      # @param line_length [Integer] - characters per line, a positive multiple of 4
+      # @param crlf [Boolean] - if lines end in "\r\n" instead of "\n"
+      # @return [String]
+      # @raise [ArgumentError] if +line_length+ is not a positive multiple of 4
+      def encode(bin, line_length = 60, crlf: false)
+        __encode_rfc_2045(bin, line_length, crlf)
+      end
+
+      # Returns the Base64-decoded version of +string+, like
+      # <tt>string.unpack1("m")</tt>: characters outside the alphabet, such
+      # as line breaks, are skipped. Decoding is lenient, as in Ruby, and
+      # never raises for malformed input.
+      #
+      # @param string [String]
+      # @return [String]
+      def decode(string)
+        __decode_rfc_2045(string)
+      end
+
+      # Returns the length of {encode} of +bin+.
+      #
+      # Fast: computed from +bin+'s length.
+      #
+      # @param bin [String]
+      # @param line_length [Integer] - characters per line, a positive multiple of 4
+      # @param crlf [Boolean] - if lines end in "\r\n" instead of "\n"
+      # @return [Integer]
+      # @raise [ArgumentError] if +line_length+ is not a positive multiple of 4
+      def encoded_length_of(bin, line_length = 60, crlf: false)
+        __encoded_length_of_rfc_2045(bin, line_length, crlf)
+      end
+
+      # Returns the length of {decode} of +string+.
+      #
+      # Costly: reads all of +string+, since skipped characters and +=+ decide
+      # the length. To size a buffer, <tt>string.bytesize * 3 / 4</tt> is
+      # always enough and fast.
+      #
+      # @param string [String]
+      # @return [Integer]
+      def decoded_length_of(string)
+        __decoded_length_of_rfc_2045(string)
+      end
     end
   end
 
@@ -155,7 +218,9 @@ module Ob64
       __uudecode(string)
     end
 
-    # Returns the length of the uuencoded version of +bin+.
+    # Returns the length of {encode} of +bin+.
+    #
+    # Fast: computed from +bin+'s length.
     #
     # @param bin [String]
     # @return [Integer]
@@ -163,9 +228,13 @@ module Ob64
       __uuencoded_length_of(bin)
     end
 
-    # Returns the length of the uudecoded version of +string+.
+    # Returns the length of {decode} of +string+.
     # Like {decode}, never raises for malformed input.
     #
+    # Costly: reads all of +string+, since each line's length character
+    # decides the length. To size a buffer, <tt>string.bytesize * 3 / 4</tt>
+    # is always enough and fast.
+    #
     # @param string [String]
     # @return [Integer]
     def decoded_length_of(string)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ob64
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - João Fernandes
@@ -19,6 +19,7 @@ extensions:
 extra_rdoc_files: []
 files:
 - ".github/dependabot.yml"
+- ".github/scripts/install-sde"
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
@@ -35,6 +36,7 @@ files:
 - bin/_guard-core
 - bin/console
 - bin/guard
+- bin/rake
 - bin/rspec
 - bin/setup
 - bin/standardrb
@@ -58,8 +60,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jcmfernandes/ob64
   changelog_uri: https://github.com/jcmfernandes/ob64/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/ob64/0.6.0
-  source_code_uri: https://github.com/jcmfernandes/ob64/tree/v0.6.0
+  documentation_uri: https://www.rubydoc.info/gems/ob64/0.8.0
+  source_code_uri: https://github.com/jcmfernandes/ob64/tree/v0.8.0
 rdoc_options: []
 require_paths:
 - lib
@@ -74,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.23
 specification_version: 4
 summary: A fast Base64 and uuencode encoder and decoder.
 test_files: []