=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.38.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

String::Slice - Shared Memory Slices of Bigger Strings

=for html
<a href="https://travis-ci.org/ingydotnet/string-slice-pm"><img src="https://travis-ci.org/ingydotnet/string-slice-pm.png" alt="string-slice-pm"></a>

=head1 VERSION

This document describes L<String::Slice> version B<0.08>.
";

=head1 SYNOPSIS

    # Exports 'slice':
    use String::Slice;

    # String::Slice is for parsing across huge strings:
    my $buffer = get_large_buffer;

    # Make an SV to turn into a slice:
    my $slice = '';

    # Move (parse) forward across the $buffer in small increments:
    for (my $pos = 0; $pos <= length $buffer;) {

      # $pos is the current postion in buffer.
      # $slice retains info from previous call:
      slice($slice, $buffer, $pos);

      # front-anchored means /\A…/
      my $regex = get_small_front_anchored_regex;

      # Match may fail. Stay at same $pos if fail:
      $slice =~ $regex or next;

      # Add length of match:
      $pos += $+[0];
    }

=head1 DESCRIPTION

Processing large strings in Perl is inefficient because to access any smaller
portion of a buffer you need to make a copy of that portion. Also finding
substr offsets in large utf8 strings requires looping, since each character
can have a varying length.

This module lets you make a string scalar (a "slice") point to a portion of
the content of another string scalar. Finding the next slice is based on the
position of the previous slice, so hopping over utf8 is much faster.

The primary goal of this module is to make the parsing large data much
faster in Perl.

=head1 API

String::Slice exports one function: C<slice>. It can be called in a few
different ways:

    slice($slice_variable, $big_buffer_variable, $char_offset, $char_length)

This effectively makes C<$slice_variable> a substr of the buffer, providing a
faster, and more memory efficient way of doing:

    $slice_variable = substr($big_buffer_variable, $char_offset, $char_length);

The offset defaults to 0, and if no length is given, the slice goes to the end
of the buffer.

If C<$slice> is already a slice of C<$buffer> then this call:

    slice($slice, $buffer, $offset, $length)

will subtract the previous offset (stashed in the slice internally) from the
current offset and hop the difference. (This may be forwards or backwards).

If length is too long, the slice will go to the end of the buffer.

One side effect of this function is that both strings will become readonly,
and the memory will not be freed until they both go out of scope.

The C<slice> function returns 1 on success and 0 on failure. Failure occurs if
the requested offset is invalid (less than the start or greater than or equal
to the end of the buffer).

=head1 CREDIT

These people provided invaluable help:

=over

=item * Jan Dubois

=item * Florian Ragwitz

=back

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2012-2015. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
