Data::Buffer(3pm) - phpMan

Command: man perldoc info search(apropos)  


Buffer(3pm)                    User Contributed Perl Documentation                    Buffer(3pm)

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 implementation 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 processes 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 character 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. Increments 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 offset 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:

       o   an int8

       o   a string

       o   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 information 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 generally 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 internal 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 status 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 transferred packet will be
       evenly divisible by 8, which is a requirement of the SSH protocol.

AUTHOR & COPYRIGHTS
       Benjamin Trott, ben AT rhumba.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.32.0                                2020-12-31                                Buffer(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-10-04 13:25 @98.84.18.52 CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!