Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
stream_memory.c

Streams in memory: write a little binary record, then read it back.

Streams in memory: write a little binary record, then read it back.A file format is a sequence of integers in a fixed byte order. This example writes one, a tiny "save game" record, into a stream that lives in memory and grows as it is written, then reads it back with the byte-order functions and checks the status to tell a complete record from a truncated one.

What you'll learn

  • bj_create_stream makes an empty stream that reads, writes and grows.
  • bj_write_stream_u32_be and its siblings store integers in the byte order a format fixes, whatever the computer running the program.
  • bj_stream_peek looks at the bytes without moving the cursor.
  • bj_stream_status says why a read fell short: the end of the data, here, rather than an error.
#include <banjo/log.h>
#include <banjo/main.h>
#include <banjo/stream.h>
#define MAGIC 0x53415645u // "SAVE", big-endian
int main(int argc, char* argv[]) {
(void)argc; (void)argv;
// An empty stream in memory: it owns its bytes and grows as we write.
if (save == 0) {
bj_err("Out of memory");
return 1;
}
// The record: a big-endian magic number, a version, a score and a
// signed position. Each writer returns BJ_TRUE when all its bytes went
// through, so a whole record can be checked with one condition.
const bj_bool written = bj_write_stream_u32_be(save, MAGIC)
&& bj_write_stream_u32_le(save, 125000)
&& bj_write_stream_i16_le(save, -42);
bj_info("Record written: %s, %zu bytes", written ? "yes" : "no", bj_stream_length(save));
// Peeking shows the bytes as the format stores them, without moving the
// cursor: the magic reads "SAVE" in memory because it is big-endian.
const unsigned char* bytes = (const unsigned char*)bj_stream_peek(save, 0, 4);
if (bytes != 0) {
bj_info("First bytes: %c%c%c%c", bytes[0], bytes[1], bytes[2], bytes[3]);
}
// Back to the start, and read the record as a parser would.
uint32_t magic = 0;
uint16_t version = 0;
uint32_t score = 0;
int16_t position = 0;
if (bj_read_stream_u32_be(save, &magic) && magic == MAGIC
&& bj_read_stream_u16_le(save, &version)
&& bj_read_stream_u32_le(save, &score)
&& bj_read_stream_i16_le(save, &position)) {
bj_info("Version %u, score %lu, position %d", (unsigned)version, (unsigned long)score, (int)position);
}
// One read too many: the reader gives BJ_FALSE, and the status tells
// the end of the data from a failure. A seek clears it.
uint8_t extra = 0;
if (!bj_read_stream_u8(save, &extra)) {
bj_info("Past the record, the status is %s",
bj_stream_status(save) == BJ_STREAM_STATUS_END ? "END" : "an error");
}
return 0;
}
struct bj_stream bj_stream
Definition api.h:374
uint32_t bj_bool
Boolean type used throughout the Banjo API.
Definition api.h:264
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
#define bj_err(...)
Log a message using the BJ_LOG_ERROR level.
Definition log.h:169
bj_bool bj_write_stream_i16_le(struct bj_stream *stream, int16_t value)
Writes a little-endian int16_t.
size_t bj_seek_stream(struct bj_stream *stream, ptrdiff_t position, enum bj_seek_origin from)
Seeks to a new position in the stream relative to a specified origin.
size_t bj_stream_length(struct bj_stream *stream)
Return the total size of the stream, in bytes.
bj_bool bj_read_stream_u8(struct bj_stream *stream, uint8_t *value)
Reads one byte.
const void * bj_stream_peek(struct bj_stream *stream, size_t offset, size_t length)
Points at bytes of the stream without moving the cursor.
bj_bool bj_write_stream_u16_le(struct bj_stream *stream, uint16_t value)
Writes a little-endian uint16_t.
void bj_destroy_stream(struct bj_stream *stream)
Destroy a stream and release its memory.
bj_bool bj_read_stream_u16_le(struct bj_stream *stream, uint16_t *value)
Reads a little-endian uint16_t.
bj_bool bj_read_stream_u32_le(struct bj_stream *stream, uint32_t *value)
Reads a little-endian uint32_t.
bj_bool bj_write_stream_u32_le(struct bj_stream *stream, uint32_t value)
Writes a little-endian uint32_t.
bj_bool bj_write_stream_u32_be(struct bj_stream *stream, uint32_t value)
Writes a big-endian uint32_t.
struct bj_stream * bj_create_stream(void)
Create an empty stream in memory, which reads and writes, and grows as it is written.
bj_bool bj_read_stream_i16_le(struct bj_stream *stream, int16_t *value)
Reads a little-endian int16_t.
bj_bool bj_read_stream_u32_be(struct bj_stream *stream, uint32_t *value)
Reads a big-endian uint32_t.
bj_stream_status
Why the last read or write of a stream fell short.
Definition stream.h:150
@ BJ_SEEK_BEGIN
The beginning of the stream.
Definition stream.h:115
@ BJ_STREAM_STATUS_END
The data ran out, or a fixed-size stream is full.
Definition stream.h:152
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
Header file for struct bj_stream struct and related functions.
#define MAGIC
int main(void)