NAME
String::Slice - Shared Memory Slices of Bigger Strings
VERSION
This document describes String::Slice version 0.08. ";
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];
}
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.
API
String::Slice exports one function: slice. It can be called in a few
different ways:
slice($slice_variable, $big_buffer_variable, $char_offset, $char_length)
This effectively makes $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 $slice is already a slice of $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 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).
CREDIT
These people provided invaluable help:
* Jan Dubois
* Florian Ragwitz
AUTHOR
Ingy döt Net <ingy@cpan.org>
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 http://www.perl.com/perl/misc/Artistic.html