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.12 by root, Tue Oct 29 15:13:50 2013 UTC vs.
Revision 1.16 by root, Tue Oct 29 22:04:52 2013 UTC

… …
46In short, CBOR is a faster and very compact binary alternative to JSON, 46In short, CBOR is a faster and very compact binary alternative to JSON,
47with the added ability of supporting serialisation of Perl objects. (JSON 47with the added ability of supporting serialisation of Perl objects. (JSON
48often compresses better than CBOR though, so if you plan to compress the 48often compresses better than CBOR though, so if you plan to compress the
49data later you might want to compare both formats first). 49data later you might want to compare both formats first).
50 50
51To give you a general idea about speed, with texts in the megabyte range,
52C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
53L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
54data, the worse L<Storable> performs in comparison.
55
56As for compactness, C<CBOR::XS> encoded data structures are usually about
5720% smaller than the same data encoded as (compact) JSON or L<Storable>.
58
51The primary goal of this module is to be I<correct> and the secondary goal 59The primary goal of this module is to be I<correct> and the secondary goal
52is to be I<fast>. To reach the latter goal it was written in C. 60is to be I<fast>. To reach the latter goal it was written in C.
53 61
54See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 62See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
55vice versa. 63vice versa.
… …
58 66
59package CBOR::XS; 67package CBOR::XS;
60 68
61use common::sense; 69use common::sense;
62 70
63our $VERSION = 0.05; 71our $VERSION = 0.07;
64our @ISA = qw(Exporter); 72our @ISA = qw(Exporter);
65 73
66our @EXPORT = qw(encode_cbor decode_cbor); 74our @EXPORT = qw(encode_cbor decode_cbor);
67 75
68use Exporter; 76use Exporter;
… …
283C<1>, which get turned into false and true in CBOR. 291C<1>, which get turned into false and true in CBOR.
284 292
285=item CBOR::XS::Tagged objects 293=item CBOR::XS::Tagged objects
286 294
287Objects of this type must be arrays consisting of a single C<[tag, value]> 295Objects of this type must be arrays consisting of a single C<[tag, value]>
288pair. The (numerical) tag will be encoded as a CBOR tag, the value will be 296pair. The (numerical) tag will be encoded as a CBOR tag, the value will
289encoded as appropriate for the value. 297be encoded as appropriate for the value. You cna use C<CBOR::XS::tag> to
298create such objects.
290 299
291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 300=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
292 301
293These special values become CBOR true, CBOR false and CBOR undefined 302These special values become CBOR true, CBOR false and CBOR undefined
294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 303values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
… …
515 524
516sub CBOR::XS::Tagged::value { 525sub CBOR::XS::Tagged::value {
517 $_[0][1] = $_[1] if $#_; 526 $_[0][1] = $_[1] if $#_;
518 $_[0][1] 527 $_[0][1]
519} 528}
529
530=head2 EXAMPLES
531
532Here are some examples of C<CBOR::XS::Tagged> uses to tag objects.
533
534You can look up CBOR tag value and emanings in the IANA registry at
535L<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
536
537Prepend a magic header (C<$CBOR::XS::MAGIC>):
538
539 my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
540 # same as:
541 my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
542
543Serialise some URIs and a regex in an array:
544
545 my $cbor = encode_cbor [
546 (CBOR::XS::tag 32, "http://www.nethype.de/"),
547 (CBOR::XS::tag 32, "http://software.schmorp.de/"),
548 (CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
549 ];
550
551Wrap CBOR data in CBOR:
552
553 my $cbor_cbor = encode_cbor
554 CBOR::XS::tag 24,
555 encode_cbor [1, 2, 3];
520 556
521=head1 CBOR and JSON 557=head1 CBOR and JSON
522 558
523CBOR is supposed to implement a superset of the JSON data model, and is, 559CBOR is supposed to implement a superset of the JSON data model, and is,
524with some coercion, able to represent all JSON texts (something that other 560with some coercion, able to represent all JSON texts (something that other

Diff Legend

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