As we're not passing over (or copying in) a NUL, don't need that extra

[p5sagit/p5-mst-13.2.git] / ext / MIME / Base64 / QuotedPrint.pm

diff --git a/ext/MIME/Base64/QuotedPrint.pm b/ext/MIME/Base64/QuotedPrint.pm
index 5a6bbfa..1d6a7c1 100644 (file)
--- a/ext/MIME/Base64/QuotedPrint.pm
+++ b/ext/MIME/Base64/QuotedPrint.pm
@@ -1,6 +1,6 @@
 package MIME::QuotedPrint;
 
-# $Id: QuotedPrint.pm,v 3.0 2004/01/14 11:59:07 gisle Exp $
+# $Id: QuotedPrint.pm,v 3.7 2005/11/29 20:49:46 gisle Exp $
 
 use strict;
 use vars qw(@ISA @EXPORT $VERSION);
@@ -9,7 +9,7 @@ require Exporter;
 @ISA = qw(Exporter);
 @EXPORT = qw(encode_qp decode_qp);
 
-$VERSION = "3.00";
+$VERSION = "3.07";
 
 use MIME::Base64;  # will load XS version of {en,de}code_qp()
 
@@ -50,19 +50,29 @@ The following functions are provided:
 
 =item encode_qp($str, $eol)
 
-This function returns an encoded version of the string given as
-argument.
+=item encode_qp($str, $eol, $binmode)
 
-The second argument is the line-ending sequence to use.  It is
-optional and defaults to "\n".  Every occurrence of "\n" is
-replaced with this string, and it is also used for additional
-"soft line breaks" to ensure that no line is longer than 76
-characters.  You might want to pass it as "\015\012" to produce data
-suitable for external consumption.  The string "\r\n" produces the
-same result on many platforms, but not all.
+This function returns an encoded version of the string ($str) given as
+argument.
 
-An $eol of "" (the empty string) is special.  In this case, no "soft line breaks" are introduced
-and any literal "\n" in the original data is encoded as well.
+The second argument ($eol) is the line-ending sequence to use.  It is
+optional and defaults to "\n".  Every occurrence of "\n" is replaced
+with this string, and it is also used for additional "soft line
+breaks" to ensure that no line end up longer than 76 characters.  Pass
+it as "\015\012" to produce data suitable for external consumption.
+The string "\r\n" produces the same result on many platforms, but not
+all.
+
+The third argument ($binmode) will select binary mode if passed as a
+TRUE value.  In binary mode "\n" will be encoded in the same way as
+any other non-printable character.  This ensures that a decoder will
+end up with exactly the same string whatever line ending sequence it
+uses.  In general it is preferable to use the base64 encoding for
+binary data; see L<MIME::Base64>.
+
+An $eol of "" (the empty string) is special.  In this case, no "soft
+line breaks" are introduced and binary mode is effectively enabled so
+that any "\n" in the original data is encoded as well.
 
 =item decode_qp($str);
 
@@ -80,10 +90,11 @@ call them as:
   $encoded = MIME::QuotedPrint::encode($decoded);
   $decoded = MIME::QuotedPrint::decode($encoded);
 
-Perl v5.6 and better allow extended Unicode characters in strings.
+Perl v5.8 and better allow extended Unicode characters in strings.
 Such strings cannot be encoded directly, as the quoted-printable
-encoding is only defined for single-byte characters.  The solution is to use the Encode
-module to select the byte encoding you want.  For example:
+encoding is only defined for single-byte characters.  The solution is
+to use the Encode module to select the byte encoding you want.  For
+example:
 
     use MIME::QuotedPrint qw(encode_qp);
     use Encode qw(encode);