ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/XS.pm
(Generate patch)

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.51 by root, Sun Apr 24 19:16:15 2016 UTC vs.
Revision 1.54 by root, Mon Apr 25 18:24:44 2016 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.41; 69our $VERSION = 1.5;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
246If C<$enable> is false (the default), then C<encode> will encode strings 246If C<$enable> is false (the default), then C<encode> will encode strings
247the standard CBOR way. 247the standard CBOR way.
248 248
249This option does not affect C<decode> in any way - string references will 249This option does not affect C<decode> in any way - string references will
250always be decoded properly if present. 250always be decoded properly if present.
251
252=item $cbor = $cbor->text_keys ([$enable])
253
254=item $enabled = $cbor->get_text_keys
255
256If C<$enabled> is true (or missing), then C<encode> will encode all
257perl hash keys as CBOR text strings/UTF-8 string, upgrading them as needed.
258
259If C<$enable> is false (the default), then C<encode> will encode hash keys
260normally - upgraded perl strings (strings internally encoded as UTF-8) as
261CBOR text strings, and downgraded perl strings as CBOR byte strings.
262
263This option does not affect C<decode> in any way.
264
265This option is useful for interoperability with CBOR decoders that don't
266treat byte strings as a form of text. It is especially useful as Perl
267gives very little control over hash keys.
268
269Enabling this option can be slow, as all downgraded hash keys that are
270encoded need to be scanned and converted to UTF-8.
271
272=item $cbor = $cbor->text_strings ([$enable])
273
274=item $enabled = $cbor->get_text_strings
275
276This option works similar to C<text_keys>, above, but works on all strings
277(including hash keys), so C<text_keys> has no further effect after
278enabling C<text_strings>.
279
280If C<$enabled> is true (or missing), then C<encode> will encode all perl
281strings as CBOR text strings/UTF-8 strings, upgrading them as needed.
282
283If C<$enable> is false (the default), then C<encode> will encode strings
284normally (but see C<text_keys>) - upgraded perl strings (strings
285internally encoded as UTF-8) as CBOR text strings, and downgraded perl
286strings as CBOR byte strings.
287
288This option does not affect C<decode> in any way.
289
290This option has similar advantages and disadvantages as C<text_keys>. In
291addition, this option effectively removes the ability to encode byte
292strings, which might break some C<FREEZE> and C<TO_CBOR> methods that rely
293on this, such as bignum encoding, so this option is mainly useful for very
294simple data.
251 295
252=item $cbor = $cbor->validate_utf8 ([$enable]) 296=item $cbor = $cbor->validate_utf8 ([$enable])
253 297
254=item $enabled = $cbor->get_validate_utf8 298=item $enabled = $cbor->get_validate_utf8
255 299
… …
544 my $x = 3.1; # some variable containing a number 588 my $x = 3.1; # some variable containing a number
545 "$x"; # stringified 589 "$x"; # stringified
546 $x .= ""; # another, more awkward way to stringify 590 $x .= ""; # another, more awkward way to stringify
547 print $x; # perl does it for you, too, quite often 591 print $x; # perl does it for you, too, quite often
548 592
549You can force whether a string ie encoded as byte or text string by using 593You can force whether a string is encoded as byte or text string by using
550C<utf8::upgrade> and C<utf8::downgrade>): 594C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled):
551 595
552 utf8::upgrade $x; # encode $x as text string 596 utf8::upgrade $x; # encode $x as text string
553 utf8::downgrade $x; # encode $x as byte string 597 utf8::downgrade $x; # encode $x as byte string
554 598
555Perl doesn't define what operations up- and downgrade strings, so if the 599Perl doesn't define what operations up- and downgrade strings, so if the
556difference between byte and text is important, you should up- or downgrade 600difference between byte and text is important, you should up- or downgrade
557your string as late as possible before encoding. 601your string as late as possible before encoding. You can also force the
602use of CBOR text strings by using C<text_keys> or C<text_strings>.
558 603
559You can force the type to be a CBOR number by numifying it: 604You can force the type to be a CBOR number by numifying it:
560 605
561 my $x = "3"; # some variable containing a string 606 my $x = "3"; # some variable containing a string
562 $x += 0; # numify it, ensuring it will be dumped as a number 607 $x += 0; # numify it, ensuring it will be dumped as a number
… …
663 "$self" # encode url string 708 "$self" # encode url string
664 } 709 }
665 710
666 sub URI::THAW { 711 sub URI::THAW {
667 my ($class, $serialiser, $uri) = @_; 712 my ($class, $serialiser, $uri) = @_;
668
669 $class->new ($uri) 713 $class->new ($uri)
670 } 714 }
671 715
672Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For 716Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
673example, a C<FREEZE> method that returns "type", "id" and "variant" values 717example, a C<FREEZE> method that returns "type", "id" and "variant" values

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines