WordList(3)

NAME

       Data::Buffer - Read/write buffer class

SYNOPSIS

           use Data::Buffer;
           my $buffer = Data::Buffer->new;

           ## Add a 32-bit integer.
           $buffer->put_int32(10932930);

           ## Get it back.
           my $int = $buffer->get_int32;

DESCRIPTION

       Data::Buffer implements a low-level binary buffer in which you can get
       and put integers, strings, and other data.  Internally the implementa-
       tion is based on "pack" and "unpack", such that Data::Buffer is really
       a layer on top of those built-in functions.

       All of the get_* and put_* methods respect the internal offset state in
       the buffer object. This means that you should read data out of the
       buffer in the same order that you put it in. For example:

           $buf->put_int16(24);
           $buf->put_int32(1233455);
           $buf->put_int16(99);

           $buf->get_int16;   # 24
           $buf->get_int32;   # 1233455
           $buf->get_int16;   # 99

       Of course, this assumes that you know the order of the data items in
       the buffer. If your setup is such that your sending and receiving pro-
       cesses won't necessarily know what's inside the buffers they receive,
       take a look at the TEMPLATE USAGE section.

USAGE

       Data::Buffer->new

       Creates a new buffer object and returns it. The buffer is initially
       empty.

       This method takes no arguments.

       Data::Buffer->new_with_init(@strs)

       Creates a new buffer object and appends to it each of the octet strings
       in @strs.

       Returns the new buffer object.

       $buffer->get_int8

       Returns the next 8-bit integer from the buffer (which is really just
       the ASCII code for the next character/byte in the buffer).

       $buffer->put_int8

       Appends an 8-bit integer to the buffer (which is really just the char-
       acter corresponding to that integer, in ASCII).

       $buffer->get_int16

       Returns the next 16-bit integer from the buffer.

       $buffer->put_int16($integer)

       Appends a 16-bit integer to the buffer.

       $buffer->get_int32

       Returns the next 32-bit integer from the buffer.

       $buffer->put_int32($integer)

       Appends a 32-bit integer to the buffer.

       $buffer->get_char

       More appropriately called get_byte, perhaps, this returns the next byte
       from the buffer.

       $buffer->put_char($bytes)

       Appends a byte (or a sequence of bytes) to the buffer.  There is no
       restriction on the length of the byte string $bytes; if it makes you
       uncomfortable to call put_char to put multiple bytes, you can instead
       call this method as put_chars. It's the same thing.

       $buffer->get_bytes($n)

       Grabs $n bytes from the buffer, where $n is a positive integer. Incre-
       ments the internal offset state by $n.

       $buffer->put_bytes($bytes [, $n ])

       Appends a sequence of bytes to the buffer; if $n is unspecified,
       appends the entire length of $bytes.  Otherwise appends only the first
       $n bytes of $bytes.

       $buffer->get_str

       Returns the next "string" from the buffer. A string here is represented
       as the length of the string (a 32-bit integer) followed by the string
       itself.

       $buffer->put_str($string)

       Appends a string (32-bit integer length and the string itself) to the
       buffer.

       $buffer->extract($n)

       Extracts the next $n bytes from the buffer $buffer, increments the off-
       set state in $buffer, and returns a new buffer object containing the
       extracted bytes.

TEMPLATE USAGE

       Generally when you use Data::Buffer it's to communicate with another
       process (perhaps a C program) that bundles up its data into binary
       buffers. In those cases, it's very likely that the data will be in some
       well-known order in the buffer: in other words, it might be documented
       that a certain C program creates a buffer containing:

       * an int8
       * a string
       * an int32

       In this case, you would presumably know about the order of the data in
       the buffer, and you could extract it accordingly:

           $buffer->get_int8;
           $buffer->get_str;
           $buffer->get_int32;

       In other cases, however, there may not be a well-defined order of data
       items in the buffer. This might be the case if you're inventing your
       own protocol, and you want your binary buffers to "know" about their
       contents. In this case, you'll want to use the templating features of
       Data::Buffer.

       When you use the put_ methods to place data in a buffer, Data::Buffer
       keeps track of the types of data that you're inserting in a template
       description of the buffer. This template contains all of the informa-
       tion necessary for a process to receive a buffer and extract the data
       in the buffer without knowledge of the order of the items.

       To use this feature, simply use the insert_template method after you've
       filled your buffer to completion. For example:

           my $buffer = Data::Buffer->new;
           $buffer->put_str("foo");
           $buffer->put_int32(9999);
           $buffer->insert_template;

           ## Ship off the buffer to another process.

       The receiving process should then invoke the get_all method on the
       buffer to extract all of the data:

           my $buffer = Data::Buffer->new;
           $buffer->append( $received_buffer_data );
           my @data = $buffer->get_all;

       @data will now contain two elements: "foo" and 9999.

LOW-LEVEL METHODS

       $buffer->append($bytes)

       Appends raw data $bytes to the end of the in-memory buffer. Generally
       you don't need to use this method unless you're initializing an empty
       buffer, because when you need to add data to a buffer you should gener-
       ally use one of the put_* methods.

       $buffer->empty

       Empties out the buffer object.

       $buffer->bytes([ $offset [, $length [, $replacement ]]])

       Behaves exactly like the substr built-in function, except on the buffer
       $buffer. Given no arguments, bytes returns the entire buffer; given one
       argument $offset, returns everything from that position to the end of
       the string; given $offset and $length, returns the segment of the
       buffer starting at $offset and consisting of $length bytes; and given
       all three arguments, replaces that segment with $replacement.

       This is a very low-level method, and you generally won't need to use
       it.

       Also be warned that you should not intermix use of this method with use
       of the get_* and put_* methods; the latter classes of methods maintain
       internal state of the buffer offset where arguments will be gotten from
       and put, respectively. The bytes method gives no thought to this inter-
       nal offset state.

       $buffer->length

       Returns the length of the buffer object.

       $buffer->offset

       Returns the internal offset state.

       If you insist on intermixing calls to bytes with calls to the get_* and
       put_* methods, you'll probably want to use this method to get some sta-
       tus on that internal offset.

       $buffer->set_offset($offset)

       Sets the internal offset state to $offset.

       $buffer->reset_offset

       Sets the internal offset state to 0.

       $buffer->dump(@args)

       Returns a hex dump of the buffer. The dump is of the entire buffer
       $buffer; in other words, dump doesn't respect the internal offset
       pointer.

       @args is passed directly through to the bytes method, which means that
       you can supply arguments to emulate support of the internal offset:

           my $dump = $buffer->dump($buffer->offset);

       $buffer->insert_padding

       A helper method: pads out the buffer so that the length of the trans-
       ferred packet will be evenly divisible by 8, which is a requirement of
       the SSH protocol.

AUTHOR & COPYRIGHTS

       Benjamin Trott, ben@rhumba.pair.com

       Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin
       Trott. All rights reserved. Data::Buffer is free software; you may
       redistribute it and/or modify it under the same terms as Perl itself.

perl v5.8.8                       2001-07-28                         Buffer(3)
See also Data::Dumper(3)
See also Data::Grove(3)
See also Data::Grove::Parent(3)
See also Data::Grove::Visitor(3)
See also Data::Random(3)
See also Data::Random::WordList(3)
See also SOAP::Data(3)