This function reads a piece of data of the given type from the given buffer at the buffer's current seek position.
After the function has executed the seek position is advanced by the number of bytes read. The next buffer_read will be done at this new position and will read the next byte(s) of data.
Since the function only reads the contents starting from the buffer's current seek position, you must ensure this is set correctly before calling the function - otherwise, you will get either incorrect results or nothing at all being returned.
NOTE You can use buffer_peek to get a value anywhere in the buffer without changing the seek position.
The return value depends on the type of data that you are reading, which can be one of the following constants:
| Constant | Description | Datatype Returned |
|---|---|---|
| buffer_u8 | An unsigned, 8bit integer. This is a positive value from 0 to 255. | int32 |
| buffer_s8 | A signed, 8bit integer. This can be a positive or negative value from -128 to 127 (0 is classed as positive). | int32 |
| buffer_u16 | An unsigned, 16bit integer. This is a positive value from 0 - 65,535. | int32 |
| buffer_s16 | A signed, 16bit integer. This can be a positive or negative value from -32,768 to 32,767 (0 is classed as positive). | int32 |
| buffer_u32 | An unsigned, 32bit integer. This is a positive value from 0 to 4,294,967,295. | int64 |
| buffer_s32 | A signed, 32bit integer. This can be a positive or negative value from -2,147,483,648 to 2,147,483,647 (0 is classed as positive). | int32 |
| buffer_u64 | An unsigned 64bit integer. This is a positive value from 0 to 18,446,744,073,709,551,615. | int64 |
| buffer_f16 | A 16bit float. This can be a positive or negative value within the range of +/- 65504. | number (real) |
| buffer_f32 | A 32bit float. This can be a positive or negative value within the range of +/-16777216. | number (real) |
| buffer_f64 | A 64bit float. | number (real) |
| buffer_bool | A boolean value, can only be either 1 or 0 (true or false). It is stored in a single byte (8bit) | int32 |
| buffer_string | A string of any size, including a final null terminating character | string |
| buffer_text | A string of any size, without the final null terminating character | string |
If the function succeeds, it will return a value of the given type, however if it fails then it will cause a runner error.
NOTE Using the incorrect data type for the data being read will result in erroneous values being returned.
NOTE Reading a buffer_s32 or buffer_u32 on HTML5 returns the value as a Real, which is a 64-bit double, as int32 is not supported on that platform.
buffer_read(buffer, type)
| Argument | Type | Description |
|---|---|---|
| buffer | Buffer | The buffer to read from. |
| type | Buffer Data Type Constant | The type of data to be read from the buffer (see the list of constants above). |
buffer = buffer_create(10240, buffer_grow, 1);
// buffer_seek(buffer, buffer_seek_start, 0);
buffer_write(buffer, buffer_string, "Hello World");
buffer_seek(buffer, buffer_seek_start, 0);
result = buffer_read(buffer, buffer_string);
show_debug_message("Result = " + result);
The above code creates a buffer, writes a string to it and reads it back.
First a new grow buffer with an initial size of 10240 bytes is created using buffer_create. At this point you can explicitly call buffer_seek to set the seek position to 0, but this isn't necessary since a newly created buffer's seek position is 0. Next the string "Hello World" is written to the buffer with a call to buffer_write. This advances the seek position by 12 bytes: 11 bytes for the characters of the string followed by a final null byte. After this, the string is read back from the buffer. To read the correct data, the seek position is first set back to 0 with a call to buffer_seek. The data is then read into a variable result using buffer_read, which is shown in a debug message.