Data::Buffer(3pm)

🌸 Data::Buffer 💖

okay bestie, we're doing Data::Buffer from the Perl user-contributed docs today, and honestly? it's giving tiny-but-mighty. it's a read/write buffer class and it's about to be your new obsession. ✨

---

✨ NAME ✨

Data::Buffer — a 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;

like. look at that. put a number in, get the number back. we love a round trip 💅

---

💜 DESCRIPTION 💜

Data::Buffer implements a low-level binary buffer where you can get and put integers, strings, and other data. Under the hood it's built on pack and unpack, so honestly? Data::Buffer is really just a cute lil layer sitting on top of those built-in functions. no cap. 🫶

here's the thing you NEED to internalise: all of the get_* and put_* methods respect the internal offset state in the buffer object. which means you gotta read data out of the buffer in the same order you put it in. like a queue. like a conversation. like a group chat where everyone replies in order (a fantasy, ik). 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 you know the order of the data items in the buffer. and if your setup is such that your sending and receiving processes won't necessarily know what's inside the buffers they receive? then bestie, run don't walk to the TEMPLATE USAGE section. it's the plot twist you've been waiting for 👑

---

🌟 USAGE 🌟

🦋 Data::Buffer->new

Creates a new buffer object and hands it to you. the buffer starts out empty, a blank canvas, main character energy.

This method takes no arguments. zero. nada. she doesn't need them 💅

🦋 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. so you can just... start with stuff already in there. iconic behaviour honestly.

🦋 $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. either name, same slay ✨

🦋 $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; and 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. fr fr. 🫶

🦋 $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. so it's self-describing. a little overachiever. we stan. 💖

🦋 $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. it's like a little clone baby of your data 👶✨

---

🎀 TEMPLATE USAGE 🎀

so 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. and 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. yes queen, self-aware buffers.

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. it literally just tells them. no guessing. no vibe check needed.

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. periodt. 💅

---

💀 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. it's giving "tools you only reach for in an emergency" 🙈

🌸 $buffer->empty

Empties out the buffer object. poof. gone. she's resetting her whole life 🌈

🌸 $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. it's the friend who doesn't read the chat before replying. 💀

🌸 $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. like checking your bank balance before a shopping spree. necessary. 🫶

🌸 $buffer->set_offset($offset)

Sets the internal offset state to $offset.

🌸 $buffer->reset_offset

Sets the internal offset state to 0. back to the beginning bestie, fresh start ✨

🌸 $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. she's doing it for the protocol. for the culture. 🔥

---

👑 AUTHOR & COPYRIGHTS 👑

Benjamin Trott, ben@rhumba.pair.com 🎀

Except where otherwise noted, Data::Buffer is Copyright 2001 to 2024 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.

---

and that's the whole page bestie!! 🦋 this was Data::Buffer(3pm) from the User Contributed Perl Documentation, sittin' pretty as perl v5.40.0, dated 2024-11-16. mwah. go forth and pack your bytes responsibly 💖✨👑