buffer_copy

This function copies a segment (or all) of the data stored in one buffer to another.

When using two buffers and copying from one to the other, both buffers must have previously been created using the buffer_create function (for example), and you can specify a data offset (in bytes) for the start point of the data to be copied from the source buffer relative to the start of the buffer, as well as another data offset to define the position to copy the data to in the destination buffer.

Syntax:

buffer_copy(src_buffer, src_offset, size, dest_buffer, dest_offset);

Returns:

N/A

Example 1: Copying an entire buffer's contents

buff1 = buffer_create(2048, buffer_grow, 1);
buff2 = buffer_create(2048, buffer_grow, 1);
repeat(2048)
{
    buffer_write(buff1, buffer_u8, irandom(255));
}
buffer_copy(buff1, 0, 2048, buff2, 0);

The above code first creates two buffers, buff1 and buff2, both with a size of 2048 bytes. buff1 is then filled with random bytes (type buffer_u8) using buffer_write and a repeat loop. irandom(255) returns random values from 0 to 255, both inclusive. Finally the entire buff1 is copied to buff2. Copying of the data starts at the start of buff1 (as the src_offset parameter is 0). 2048 bytes (i.e. all bytes) are copied to the destination buffer buff2. Writing starts at the start, indicated by the dest_offset set to 0. After copying, buff2 contains the exact same bytes as buff1 (and so is identical).

Example 2: Copying from a buffer, starting at an offset

buff1 = buffer_create(2048, buffer_fixed, 1);
buff2 = buffer_create(2048, buffer_fixed, 1);
repeat(2048)
{
    buffer_write(buff1, buffer_u8, irandom(255));
}
var _offset = 273;
var _size = buffer_get_size(buff1) - _offset;
buffer_copy(buff1, _offset, _size, buff2, 0);

This example initialises the buffers in the same way as Example 1, i.e. it creates two buffers of size 2048 and fills the first one with random bytes. It then defines an offset from which to start copying bytes from the first buffer buff1 to the second buffer buff2. The number of bytes to copy (i.e. the length or the size) is then calculated by subtracting the offset _offset from the total size of the buffer, retrieved using buffer_get_size. Finally, the contiguous block of bytes in buff1, starting at _offset is copied to buff2. It is copied to buff2 at an offset of 0, so the byte in buff1 at index _offset is copied to index 0 in buff2, the byte in buff1 at index _offset+1 ends up at index 1 in buff2, etc. This happens for a total of _size bytes.