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

Comparing CBOR-XS/README (file contents):
Revision 1.12 by root, Sun Dec 1 17:10:42 2013 UTC vs.
Revision 1.15 by root, Mon Apr 27 20:21:53 2015 UTC

… …
178 code that isn't prepared for this will not leak memory. 178 code that isn't prepared for this will not leak memory.
179 179
180 If $enable is false (the default), then "decode" will throw an error 180 If $enable is false (the default), then "decode" will throw an error
181 when it encounters a self-referential/cyclic data structure. 181 when it encounters a self-referential/cyclic data structure.
182 182
183 FUTURE DIRECTION: the motivation behind this option is to avoid
184 *real* cycles - future versions of this module might chose to decode
185 cyclic data structures using weak references when this option is
186 off, instead of throwing an error.
187
183 This option does not affect "encode" in any way - shared values and 188 This option does not affect "encode" in any way - shared values and
184 references will always be decoded properly if present. 189 references will always be encoded properly if present.
185 190
186 $cbor = $cbor->pack_strings ([$enable]) 191 $cbor = $cbor->pack_strings ([$enable])
187 $enabled = $cbor->get_pack_strings 192 $enabled = $cbor->get_pack_strings
188 If $enable is true (or missing), then "encode" will try not to 193 If $enable is true (or missing), then "encode" will try not to
189 encode the same string twice, but will instead encode a reference to 194 encode the same string twice, but will instead encode a reference to
… …
286 protocol and you need to know where the first CBOR string ends amd 291 protocol and you need to know where the first CBOR string ends amd
287 the next one starts. 292 the next one starts.
288 293
289 CBOR::XS->new->decode_prefix ("......") 294 CBOR::XS->new->decode_prefix ("......")
290 => ("...", 3) 295 => ("...", 3)
296
297 INCREMENTAL PARSING
298 In some cases, there is the need for incremental parsing of JSON texts.
299 While this module always has to keep both CBOR text and resulting Perl
300 data structure in memory at one time, it does allow you to parse a CBOR
301 stream incrementally, using a similar to using "decode_prefix" to see if
302 a full CBOR object is available, but is much more efficient.
303
304 It basically works by parsing as much of a CBOR string as possible - if
305 the CBOR data is not complete yet, the pasrer will remember where it
306 was, to be able to restart when more data has been accumulated. Once
307 enough data is available to either decode a complete CBOR value or raise
308 an error, a real decode will be attempted.
309
310 A typical use case would be a network protocol that consists of sending
311 and receiving CBOR-encoded messages. The solution that works with CBOR
312 and about anything else is by prepending a length to every CBOR value,
313 so the receiver knows how many octets to read. More compact (and
314 slightly slower) would be to just send CBOR values back-to-back, as
315 "CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
316 length.
317
318 The following methods help with this:
319
320 @decoded = $cbor->incr_parse ($buffer)
321 This method attempts to decode exactly one CBOR value from the
322 beginning of the given $buffer. The value is removed from the
323 $buffer on success. When $buffer doesn't contain a complete value
324 yet, it returns nothing. Finally, when the $buffer doesn't start
325 with something that could ever be a valid CBOR value, it raises an
326 exception, just as "decode" would. In the latter case the decoder
327 state is undefined and must be reset before being able to parse
328 further.
329
330 This method modifies the $buffer in place. When no CBOR value can be
331 decoded, the decoder stores the current string offset. On the next
332 call, continues decoding at the place where it stopped before. For
333 this to make sense, the $buffer must begin with the same octets as
334 on previous unsuccessful calls.
335
336 You can call this method in scalar context, in which case it either
337 returns a decoded value or "undef". This makes it impossible to
338 distinguish between CBOR null values (which decode to "undef") and
339 an unsuccessful decode, which is often acceptable.
340
341 @decoded = $cbor->incr_parse_multiple ($buffer)
342 Same as "incr_parse", but attempts to decode as many CBOR values as
343 possible in one go, instead of at most one. Calls to "incr_parse"
344 and "incr_parse_multiple" can be interleaved.
345
346 $cbor->incr_reset
347 Resets the incremental decoder. This throws away any saved state, so
348 that subsequent calls to "incr_parse" or "incr_parse_multiple" start
349 to parse a new CBOR value from the beginning of the $buffer again.
350
351 This method can be caled at any time, but it *must* be called if you
352 want to change your $buffer or there was a decoding error and you
353 want to reuse the $cbor object for future incremental parsings.
291 354
292MAPPING 355MAPPING
293 This section describes how CBOR::XS maps Perl values to CBOR values and 356 This section describes how CBOR::XS maps Perl values to CBOR values and
294 vice versa. These mappings are designed to "do the right thing" in most 357 vice versa. These mappings are designed to "do the right thing" in most
295 circumstances automatically, preserving round-tripping characteristics 358 circumstances automatically, preserving round-tripping characteristics
… …
776 839
777 Strict mode and canonical mode are not implemented. 840 Strict mode and canonical mode are not implemented.
778 841
779LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 842LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
780 On perls that were built without 64 bit integer support (these are rare 843 On perls that were built without 64 bit integer support (these are rare
781 nowadays, even on 32 bit architectures), support for any kind of 64 bit 844 nowadays, even on 32 bit architectures, as all major Perl distributions
845 are built with 64 bit integer support), support for any kind of 64 bit
782 integer in CBOR is very limited - most likely, these 64 bit values will 846 integer in CBOR is very limited - most likely, these 64 bit values will
783 be truncated, corrupted, or otherwise not decoded correctly. This also 847 be truncated, corrupted, or otherwise not decoded correctly. This also
784 includes string, array and map sizes that are stored as 64 bit integers. 848 includes string, array and map sizes that are stored as 64 bit integers.
785 849
786THREADS 850THREADS

Diff Legend

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