NAME
    overload::substr - overload Perl's substr() function
SYNOPSIS
       package My::Stringlike::Object;
     
       use overload::substr;
     
       sub _substr
       {
          my $self = shift;
          if( @_ > 2 ) {
             $self->replace_substr( @_ );
          }
          else {
             return $self->get_substr( @_ );
          }
       }
     
       ...
DESCRIPTION
    This module allows an object class to overload the substr core
    function, which Perl's overload pragma does not allow by itself.
    It is invoked similarly to the overload pragma, being passed a single
    named argument which should be a code reference or method name to
    implement the substr function.
       use overload::substr substr => \&SUBSTR;
     
       use overload::substr substr => "SUBSTR";
    The referred method will be invoked as per core's substr; namely, it
    will take the string to be operated on (which will be an object in this
    case), an offset, optionally a length, and optionally a replacement.
       $str->SUBSTR( $offset );
       $str->SUBSTR( $offset, $length );
       $str->SUBSTR( $offset, $length, $replacement );
    In each case, whatever it returns will be the return value of the
    substr function that invoked it.
    If the substr argument is not provided, it defaults to a method called
    _substr.
    It is not required that the return value be a plain string; any Perl
    value may be returned unmodified from the substr method, or passed in
    as the value of the replacement. This allows objects to behave in
    whatever way is deemed most appropriate.
TODO
      * More testing - edge cases, especially in LVALUE logic.
      * Test for memory leaks, especially in LVALUE logic.
      * Look into / implement fixup of substr() ops compiled before module
      is loaded
      * Consider if implementations of split(), and m// and s/// regexps
      should be done that also uses the overloaded substr() method.
ACKNOWLEDGEMENTS
    With thanks to Matt S Trout <mst@shadowcat.co.uk> for suggesting the
    possibility, and Joshua ben Jore <jjore@cpan.org> for the inspiration
    by way of UNIVERSAL::ref.
AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>