[convert-base91.git] / lib / Convert / Base91.pm

package Convert::Base91;

use 5.014000;
use strict;
use warnings;
use parent qw/Exporter/;

our @EXPORT_OK = qw/encode_base91 decode_base91/;
our @EXPORT = ();

our $VERSION = '0.001002';

require XSLoader;
XSLoader::load('Convert::Base91', $VERSION);

our $base91 = __PACKAGE__->new;

sub encode_base91 {
	my ($data) = @_;
	$base91->encode($data);
	$base91->encode_end;
}

sub decode_base91 {
	my ($data) = @_;
	$base91->decode($data);
	$base91->decode_end;
}

1;
__END__

=encoding utf-8

=head1 NAME

Convert::Base91 - XS base91 encoding/decoding

=head1 SYNOPSIS

  use Convert::Base91 qw/encode_base91 decode_base91/;

  # procedural interface
  my $encoded = encode_base91 'some data';
  say $encoded; # qrLg,W;Hr%w
  my $decoded = decode_base91 $encoded;
  say $decoded; # some data


  # OO interface
  my $base91 = Convert::Base91->new;
  $base91->encode('some ');
  $base91->encode('data');
  my $enc = $base91->encode_end;
  say $enc; # qrLg,W;Hr%w

  $base91->decode('qrLg,');
  $base91->decode('W;Hr%w');
  my $dec = $base91->decode_end;
  say $dec; # some data

=head1 DESCRIPTION

Base91 is a method for encoding binary data as printable ASCII
characters. Every two base91 characters (16 bits) encode 13 or 14 bits
of actual data, thus the overhead is between 14% and 23%, an
improvement over base64's overhead of 33%.

This module provides a procedural interface for encoding/decoding
whole strings and an OO interface for encoding/decoding in chunks.

The C<encode_base91> and C<decode_base91> functions are available for
export, but are not exported by default.

=over

=item B<encode_base91> $binary_data

Takes a string containing arbitrary bytes and returns the
base91 encoded data.

=item B<decode_base91> $base91_data

Takes a string containing base91 encoded data and returns the decoded
string of arbitrary bytes.

=item Convert::Base91->B<new>

Create a new C<Convert::Base91> object to keep the state for a chunk
encoding/decoding operation.

=item $base91->B<encode>($data)

Submit the next chunk of arbitrary binary data to be encoded. Returns
nothing.

=item $base91->B<encode_end>

Signals that all chunks of data to be encoded have been submitted.
Returns the base91 encoded data, and clears the state of the $base91
object so it may be used again (for either encoding or decoding).

=item $base91->B<decode>($data)

Submit the next chunk of base91 data to be decoded. Returns nothing.

=item $base91->B<decode_end>

Signals that all chunks of data to be decoded have been submitted.
Returns the decoded data, and clears the state of the $base91 object
so it may be used again (for either encoding or decoding).

=back

=head1 SEE ALSO

L<http://base91.sourceforge.net/>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2017 by Marius Gavrilescu

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


=cut
Commit	Line	Data
1a1c8cd6 MG	1	package Convert::Base91;
	2
	3	use 5.014000;
	4	use strict;
	5	use warnings;
	6	use parent qw/Exporter/;
	7
	8	our @EXPORT_OK = qw/encode_base91 decode_base91/;
	9	our @EXPORT = ();
	10
ec0ffc97	11	our $VERSION = '0.001002';
1a1c8cd6 MG	12
	13	require XSLoader;
	14	XSLoader::load('Convert::Base91', $VERSION);
	15
	16	our $base91 = __PACKAGE__->new;
	17
	18	sub encode_base91 {
	19	my ($data) = @_;
	20	$base91->encode($data);
	21	$base91->encode_end;
	22	}
	23
	24	sub decode_base91 {
	25	my ($data) = @_;
	26	$base91->decode($data);
	27	$base91->decode_end;
	28	}
	29
	30	1;
	31	__END__
	32
	33	=encoding utf-8
	34
	35	=head1 NAME
	36
	37	Convert::Base91 - XS base91 encoding/decoding
	38
	39	=head1 SYNOPSIS
	40
	41	use Convert::Base91 qw/encode_base91 decode_base91/;
	42
	43	# procedural interface
	44	my $encoded = encode_base91 'some data';
	45	say $encoded; # qrLg,W;Hr%w
	46	my $decoded = decode_base91 $encoded;
	47	say $decoded; # some data
	48
	49
	50	# OO interface
	51	my $base91 = Convert::Base91->new;
	52	$base91->encode('some ');
	53	$base91->encode('data');
	54	my $enc = $base91->encode_end;
	55	say $enc; # qrLg,W;Hr%w
	56
	57	$base91->decode('qrLg,');
	58	$base91->decode('W;Hr%w');
	59	my $dec = $base91->decode_end;
	60	say $dec; # some data
	61
	62	=head1 DESCRIPTION
	63
	64	Base91 is a method for encoding binary data as printable ASCII
	65	characters. Every two base91 characters (16 bits) encode 13 or 14 bits
	66	of actual data, thus the overhead is between 14% and 23%, an
	67	improvement over base64's overhead of 33%.
	68
	69	This module provides a procedural interface for encoding/decoding
	70	whole strings and an OO interface for encoding/decoding in chunks.
	71
	72	The C<encode_base91> and C<decode_base91> functions are available for
	73	export, but are not exported by default.
	74
	75	=over
76
77	=item B<encode_base91> $binary_data
78
79	Takes a string containing arbitrary bytes and returns the
80	base91 encoded data.
81
82	=item B<decode_base91> $base91_data
83
84	Takes a string containing base91 encoded data and returns the decoded
85	string of arbitrary bytes.
86
87	=item Convert::Base91->B<new>
88
89	Create a new C<Convert::Base91> object to keep the state for a chunk
90	encoding/decoding operation.
91
92	=item $base91->B<encode>($data)
93
94	Submit the next chunk of arbitrary binary data to be encoded. Returns
95	nothing.
96
97	=item $base91->B<encode_end>
98
99	Signals that all chunks of data to be encoded have been submitted.
100	Returns the base91 encoded data, and clears the state of the $base91
101	object so it may be used again (for either encoding or decoding).
102
103	=item $base91->B<decode>($data)
104
105	Submit the next chunk of base91 data to be decoded. Returns nothing.
106
107	=item $base91->B<decode_end>
108
109	Signals that all chunks of data to be decoded have been submitted.
110	Returns the decoded data, and clears the state of the $base91 object
111	so it may be used again (for either encoding or decoding).
112
113	=back
114
115	=head1 SEE ALSO
116
117	L<http://base91.sourceforge.net/>
118
119	=head1 AUTHOR
120
121	Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
122
123	=head1 COPYRIGHT AND LICENSE
124
125	Copyright (C) 2017 by Marius Gavrilescu
126
127	This library is free software; you can redistribute it and/or modify
128	it under the same terms as Perl itself, either Perl version 5.26.1 or,
129	at your option, any later version of Perl 5 you may have available.
130
131
132	=cut