NAME

    Math::ReedSolomon::Encoder - Calculate Reed-Solomon Error Correction
    Codes

VERSION

    This document describes Math::ReedSolomon::Encoder version 0.001.

SYNOPSIS

       use Math::ReedSolomon::Encoder qw< :all >;
    
       # message is an array of integers
       my $message_aref = [ 0 .. 9 ];
    
       # calculate 22 values of error correction
       my $ecc_aref = rs_correction($message_aref, 22);
    
       # calculate the message + correction overall array ref
       my $expanded_aref = rs_encode($message_aref, 22);
    
       # message is a string of octets
       my $message_str = 'abcdefghij';
    
       # calculate 17 octets of error correction 
       my $ecc_string = rs_correction_string($message_str, 17);
    
       # calculate the message + correction overall string
       my $expanded_str = rs_encode_string($message_str, 17);

DESCRIPTION

    Calculate the Reed-Solomon Error Correction Codes in a very specific
    (although very common) condition, namely with alpha set to 2 and the
    irreducible polynomial set to x^8 + x^4 + x^3 + x^2 + 1. This is not
    written on the stone, though, as it's possible to change these values
    through package variables $Math::ReedSolomon::Encoder::ALPHA and
    $Math::ReedSolomon::Encoder::PRIME_POLY.

    This module has no pretense of efficiency or optimization, but provides
    a pure-Perl way of doing the necessary calculations, which comes handy
    in non-heavy-duty situation where the most straightforward portabiity
    characteristics are of value. In other terms, this module is expressely
    geared at being embedded in a bigger program.

INTERFACE

    There are a total of four exportable function, two depending on the
    data format (either arrays of integers, or strings of octets), and two
    orthogonal alternatives for calculating the Error Correction Codes only
    or the whole result of appending the ECCs after the input.

 rs_correction

       my $aref = rs_correction($message_aref, $n_ecc);

    Calculate the Error Correction Codes only, array-reference interface.
    The return value is an array reference that contains the generated ECCs
    only.

 rs_correction_string

       my $aref = rs_correction_string($message_string, $n_ecc);

    Calculate the Error Correction Codes only, string interface. The return
    value is a string of octets that contains the generated ECCs only.

 rs_encode

       my $aref = rs_encode($message_aref, $n_ecc);

    Encode the input message adding the Error Correction Codes,
    array-reference interface. The return value is an array reference that
    contains a copy of the input message value, followed by the generated
    ECCs.

 rs_encode_string

       my $aref = rs_encode_string($message_string, $n_ecc);

    Encode the input message adding the Error Correction Codes, string
    interface. The return value is string of octets that contains a copy of
    the input message value, followed by the generated ECCs.

 Alternative Parameters

    The Reed-Solomon ECC calculation techniques work equally well as long
    as the underlying mathematics are complied with, i.e. as long as the
    value of alpha is a generator and a suitable irreducible polynomial is
    selected for polynomial divisions. Math::ReedSolomon::Encoder allows
    setting these two values via package variables:

      * $Math::ReedSolomon::Encoder::ALPHA

      set to 2 by default.

      * $Math::ReedSolomon::Encoder::PRIME_POLY

      set to 0x11d by default. Each bit represents a coefficient in a
      base-2 polynomial, so 0x11d is the same as 0b100011101, that is the
      irreducible polynomial in Z2: x^8 + x^4 + x^3 + x^2 + 1.

    The values above are commonly found in practical implementations, e.g.
    in QR Codes generation.

BUGS AND LIMITATIONS

    Minimul perl version 5.24.

    Report bugs through GitHub (patches welcome) at
    https://codeberg.org/polettix/Math-ReedSolomon-Encoder.

AUTHOR

    Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

    Copyright 2025 by Flavio Poletti <flavio@polettix.it>

    Licensed under the Apache License, Version 2.0 (the "License"); you may
    not use this file except in compliance with the License. You may obtain
    a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    implied. See the License for the specific language governing
    permissions and limitations under the License.

    Just to be clear: apache-2.0