POD overhaul

diff --git a/lib/Scalar/Vec/Util.pm b/lib/Scalar/Vec/Util.pm
index 802f1c30905daaa5dbbff98453c1699a35eedd3f..a370396bf09651ce46df8b2a2be94b4b331b6005 100644 (file)
--- a/lib/Scalar/Vec/Util.pm
+++ b/lib/Scalar/Vec/Util.pm
@@ -40,35 +40,38 @@ BEGIN {
     my $t;
     vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20,
                               #                to $t, starting at 10.
     my $t;
     vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20,
                               #                to $t, starting at 10.

-    vcopy $t, 10, $t, 20, 30; # Overalapping areas DWIM.
+    vcopy $t, 10, $t, 20, 30; # Overlapping areas DWIM.

     if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
 
 =head1 DESCRIPTION
 
     if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
 
 =head1 DESCRIPTION
 

-A set of utilities to manipulate bits in vec strings.
-Highly optimized XS routines are used when available, but straightforward pure perl replacements are also provided for platforms without a C compiler.
+This module provides a set of utility routines that efficiently manipulate bits in vec strings.
+Highly optimized XS functions are used whenever possible, but straightforward pure Perl replacements are also available for platforms without a C compiler.

 
 

-This module doesn't reimplement bit vectors.
-It can be used on the very same scalars that C<vec> builds, or actually on any Perl string (C<SVt_PV>).
+Note that this module does not aim at reimplementing bit vectors : all its functions can be used on any Perl string, just like L<perlfunc/vec>.

 
 =head1 CONSTANTS
 
 =head2 C<SVU_PP>
 
 
 =head1 CONSTANTS
 
 =head2 C<SVU_PP>
 

-True when pure perl fallbacks are used instead of XS functions.
+True when pure Perl fallbacks are used instead of XS functions.

 
 =head2 C<SVU_SIZE>
 
 
 =head2 C<SVU_SIZE>
 

-Size in bits of the unit used for moves.
+The size (in bits) of the unit used for bit operations.

 The higher this value is, the faster the XS functions are.
 The higher this value is, the faster the XS functions are.

-It's usually C<CHAR_BIT * $Config{alignbytes}>, except on non-little-endian architectures where it currently falls back to C<CHAR_BIT> (e.g. SPARC).
+It is usually C<CHAR_BIT * $Config{alignbytes}>, except on non-little-endian architectures where it currently falls back to C<CHAR_BIT> (e.g. SPARC).

 
 =head1 FUNCTIONS
 
 
 =head1 FUNCTIONS
 

-=head2 C<vfill $vec, $start, $length, $bit>
+=head2 C<vfill>

 
 

-Starting at C<$start> in C<$vec>, fills C<$length> bits with C<$bit>.
-Grows C<$vec> if necessary.
+    vfill $vec, $start, $length, $bit;
+
+Starting at C<$start> in C<$vec>, fills C<$length> bits with ones if C<$bit> is true and with zeros if C<$bit> is false.
+
+C<$vec> is upgraded to a string and extended if necessary.
+Bits that are outside of the specified area are left untouched.

 
 =cut
 
 
 =cut
 


@@ -90,12 +93,21 @@ sub vfill_pp ($$$$) {
  }
 }
 
  }
 }
 

-=head2 C<< vcopy $from => $from_start, $to => $to_start, $length >>
+=head2 C<vcopy>
+
+    vcopy $from => $from_start, $to => $to_start, $length;

 
 Copies C<$length> bits starting at C<$from_start> in C<$from> to C<$to_start> in C<$to>.
 
 Copies C<$length> bits starting at C<$from_start> in C<$from> to C<$to_start> in C<$to>.

-If C<$from_start + $length> is too long for C<$from>, zeros are copied past C<$length>.
-Grows C<$to> if necessary.
-Doesn't need to allocate any extra memory.
+
+C<$from> and C<$to> are allowed to be the same scalar, and the given areas can rightfully overlap.
+
+C<$from> is upgraded to a string if it isn't one already.
+If C<$from_start + $length> goes out of the bounds of C<$from>, then the extra bits are treated as zeros.
+C<$to> is upgraded to a string and extended if necessary.
+The content of C<$from> is not modified, except when it is equal to C<$to>.
+Bits that are outside of the specified area are left untouched.
+
+This function does not need to allocate any extra memory.

 
 =cut
 
 
 =cut
 


@@ -112,12 +124,19 @@ sub vcopy_pp ($$$$$) {
  }
 }
 
  }
 }
 

-=head2 C<< vshift $v, $start, $length => $bits [, $insert ] >>
+=head2 C<vshift>
+
+    vshift $v, $start, $length => $bits, $insert;

 
 In the area starting at C<$start> and of length C<$length> in C<$v>, shift bits C<abs $bits> positions left if C<< $bits > 0 >> and right otherwise.
 
 In the area starting at C<$start> and of length C<$length> in C<$v>, shift bits C<abs $bits> positions left if C<< $bits > 0 >> and right otherwise.

-If C<$insert> is defined, also fills the resulting gap with ones if C<$insert> is true and zeros if it's false.
-Bits outside of the specified area are left untouched.
-Doesn't need to allocate any extra memory.
+
+When C<$insert> is defined, the resulting gap is also filled with ones if C<$insert> is true and with zeros if C<$insert> is false.
+
+C<$v> is upgraded to a string if it isn't one already.
+If C<$start + $length> goes out of the bounds of C<$v>, then the extra bits are treated as zeros.
+Bits that are outside of the specified area are left untouched.
+
+This function does not need to allocate any extra memory.

 
 =cut
 
 
 =cut
 


@@ -145,11 +164,17 @@ sub vshift ($$$$;$) {
  }
 }
 
  }
 }
 

-=head2 C<< vrot $v, $start, $length, $bits >>
+=head2 C<vrot>
+
+    vrot $v, $start, $length, $bits;

 
 In the area starting at C<$start> and of length C<$length> in C<$v>, rotates bits C<abs $bits> positions left if C<< $bits > 0 >> and right otherwise.
 
 In the area starting at C<$start> and of length C<$length> in C<$v>, rotates bits C<abs $bits> positions left if C<< $bits > 0 >> and right otherwise.

-Bits outside of the specified area are left untouched.
-Currently allocates an extra buffer of size C<O($bits)>.
+
+C<$v> is upgraded to a string if it isn't one already.
+If C<$start + $length> goes out of the bounds of C<$v>, then the extra bits are treated as zeros.
+Bits that are outside of the specified area are left untouched.
+
+This function currently allocates an extra buffer of size C<O($bits)>.

 
 =cut
 
 
 =cut
 


@@ -178,10 +203,16 @@ sub vrot ($$$$) {
  }
 }
 
  }
 }
 

-=head2 C<< veq $v1 => $v1_start, $v2 => $v2_start, $length >>
+=head2 C<veq>
+
+    veq $v1 => $v1_start, $v2 => $v2_start, $length;

 
 Returns true if the C<$length> bits starting at C<$v1_start> in C<$v1> and C<$v2_start> in C<$v2> are equal, and false otherwise.
 
 Returns true if the C<$length> bits starting at C<$v1_start> in C<$v1> and C<$v2_start> in C<$v2> are equal, and false otherwise.

-If needed, C<$length> is decreased to fit inside C<$v1> and C<$v2> boundaries.
+
+C<$v1> and C<$v2> are upgraded to strings if they aren't already, but their contents are never modified.
+If C<$v1_start + $length> (respectively C<$v2_start + $length>) goes out of the bounds of C<$v1> (respectively C<$v2>), then the extra bits are treated as zeros.
+
+This function does not need to allocate any extra memory.

 
 =cut
 
 
 =cut