/ 
gb64-1.0.0
/ gb64

NAME

gb64 - Fast Pure Perl Base64 Encoding and Decoding

SYNOPSIS

use gb64 qw(enc_b64 dec_b64);

# Direct encoding/decoding
my $encoded = enc_b64("Hello World");  # Returns "SGVsbG8gV29ybGQ="
my $decoded = dec_b64($encoded);       # Returns "Hello World"

# Streaming encoding/decoding
my $gb64 = gb64->new;
$gb64->add("Hello ")->add("World");
$encoded = $gb64->encode;              # Returns "SGVsbG8gV29ybGQ="
$gb64->add($encoded);
$decoded = $gb64->decode;              # Returns "Hello World"

DESCRIPTION

gb64 is a high-performance, pure Perl implementation of Base64 encoding and decoding, conforming to RFC 4648. It provides both a functional interface for one-shot encoding/decoding and an object-oriented streaming interface for processing large or incremental data. Optimized with unpack, pack, and array-based lookups, gb64 outperforms other pure Perl Base64 implementations, such as MIME::Base64::Perl, by up to 97.7% for large inputs.

The module has no XS or C dependencies, making it lightweight and portable across all Perl environments. It includes robust error handling for invalid inputs and supports both small and large datasets efficiently.

METHODS

new()

Creates a new gb64 object with an empty buffer for streaming operations.

my $gb64 = gb64->new;
add($data)

Appends data to the internal buffer for streaming encoding or decoding. Throws an error if $data is undefined.

$gb64->add("Hello ");
$gb64->add("World");
encode()

Encodes the buffered data as Base64, clears the buffer, and returns the encoded string.

my $encoded = $gb64->encode;  # Returns Base64-encoded string
decode()

Decodes the buffered Base64 data, clears the buffer, and returns the decoded binary data. Throws an error if the input is not valid Base64.

my $decoded = $gb64->decode;  # Returns decoded binary data

EXPORTABLE FUNCTIONS

enc_b64($data)

Encodes the input $data to Base64. Returns an empty string if $data is undefined.

my $encoded = enc_b64("Hello World");  # Returns "SGVsbG8gV29ybGQ="
dec_b64($data)

Decodes the Base64 input $data to binary. Returns an empty string if $data is undefined. Throws an error for invalid Base64 length or characters.

my $decoded = dec_b64("SGVsbG8gV29ybGQ=");  # Returns "Hello World"

ERROR HANDLING

gb64 provides robust error handling for invalid inputs:

  • add($data): Throws "Input must be defined" if $data is undefined.

  • dec_b64($data): Throws "Invalid Base64 length" if the input length is not a multiple of 4 (or empty).

  • dec_b64($data): Throws "Invalid Base64 character at position $pos" if the input contains characters outside the Base64 alphabet (A-Z, a-z, 0-9, +, /, =).

Example:

use gb64 qw(dec_b64);
eval { dec_b64("###"); };
print $@;  # "Invalid Base64 length"

eval { dec_b64("Z@=="); };
print $@;  # "Invalid Base64 character at position 1"

PERFORMANCE

gb64 is optimized for speed, using unpack, pack, and array-based lookups to minimize overhead. Benchmarks show it achieves:

- Encoding: 26.4 iterations/second for large inputs (110k bytes). - Decoding: 24.5 iterations/second for large inputs (110k bytes).

Compared to MIME::Base64::Perl, gb64 is up to 97.7% faster for large inputs (26.4/s vs. 1051/s for encoding, 24.5/s vs. 1049/s for decoding). For small inputs (~5 bytes), performance is comparable for encoding but slightly slower for decoding (-28.0%) due to robust validation.

Benchmark example (see benchmark.pl in the distribution):

use Benchmark qw(cmpthese);
use gb64 qw(enc_b64);
use MIME::Base64::Perl qw(encode_base64);
my $large = "Hello World" x 10000;
cmpthese(-5, {
    'gb64_enc_large' => sub { enc_b64($large) },
    'perl_enc_large' => sub { encode_base64($large, '') },
});

gb64 is ideal for applications requiring pure Perl Base64 processing, especially for large datasets, where its performance advantage is most pronounced.

EXAMPLES

Basic encoding and decoding
use gb64 qw(enc_b64 dec_b64);
my $data = "Hello World";
my $encoded = enc_b64($data);  # "SGVsbG8gV29ybGQ="
my $decoded = dec_b64($encoded);  # "Hello World"
print "$decoded\n";
Streaming large data
use gb64;
my $gb64 = gb64->new;
open my $fh, '<', 'large_file.txt' or die $!;
while (my $chunk = <$fh>) {
    $gb64->add($chunk);
}
close $fh;
my $encoded = $gb64->encode;
print "$encoded\n";
Handling invalid input
use gb64 qw(dec_b64);
eval { dec_b64("Invalid#Input"); };
if ($@) {
    print "Error: $@\n";  # "Invalid Base64 length"
}

AUTHOR

OnEhIppY, Domero Software <domerosoftware@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2025 by OnEhIppY, Domero Software

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO