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

Read and write UTF-8 text over a stream through one wrapper.

Read and write UTF-8 text over a stream through one wrapper.Banjo's streams move bytes. This example wraps one in a bj_text_wrapper, writes a small configuration file through it, then reads it back line by line, the way a program reads its settings:

  • The line writer appends the line ending the wrapper carries, and the ending can change at any time, as the CRLF setting here does.
  • Unflushed text waits in the wrapper: the stream's length does not see it until bj_flush_text_wrapper runs.
  • Reading one line at a time strips the terminator, and bj_peek_text_wrapper previews a character without consuming it.
  • The probe, a chunk read of 0 bytes, tells whether text remains without consuming any.
  • Destroying the wrapper releases the lock it holds on the stream, so the caller can keep using the stream afterwards.
#include <banjo/memory.h>
#include <banjo/stream.h>
#include <banjo/string.h>
#include <banjo/log.h>
#include <stdio.h>
int main(void) {
// Write a configuration file into a growable stream.
struct bj_stream* settings = bj_create_stream();
if (settings == 0) {
bj_err("cannot create the stream");
return 1;
}
struct bj_text_wrapper* writer = bj_create_text_wrapper(settings);
if (writer == 0) {
bj_err("cannot create the text wrapper");
bj_destroy_stream(settings);
return 1;
}
bj_write_text_wrapper_line(writer, BJ_STR("[player]"));
bj_write_text_wrapper_line(writer, BJ_STR("name=Banjo"));
// A file with mixed endings: the policy changes mid-stream.
// While the wrapper holds it, nothing has reached the stream yet.
bj_info("%zu bytes in the stream before the flush", bj_stream_length(settings));
bj_info("%zu bytes in the stream after the flush", bj_stream_length(settings));
// Read the file back through the same wrapper: seek, then read.
struct bj_str line;
int count = 0;
while (bj_read_text_wrapper_line(writer, &line, 0)) {
++count;
bj_info("line %d: %.*s", count, (int)line.len, line.data);
}
// The probe: does any text remain, without consuming any?
struct bj_str rest;
const bj_bool more = bj_read_text_wrapper(writer, &rest, 0);
bj_info("text remains after the lines: %s", more ? "yes" : "no");
// A peek previews the first character of the next read, which is
// nothing here: the text ended.
struct bj_str character;
const bj_bool seen = bj_peek_text_wrapper(writer, &character);
bj_info("a character to peek: %s", seen ? "yes" : "no");
// The status the reads left behind says why the text ended.
bj_info("status at the end: %d", (int)bj_text_wrapper_status(writer));
// Destroy the wrapper: its lock on the stream is released, and the
// stream, with its settings, survives for the caller to keep using.
bj_destroy_stream(settings);
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
struct bj_text_wrapper bj_text_wrapper
Definition api.h:378
#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
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.
void bj_destroy_stream(struct bj_stream *stream)
Destroy a stream and release its memory.
struct bj_stream * bj_create_stream(void)
Create an empty stream in memory, which reads and writes, and grows as it is written.
@ BJ_SEEK_BEGIN
The beginning of the stream.
Definition stream.h:115
size_t len
Number of bytes in the view.
Definition string.h:59
const char * data
Pointer to the first byte, or NULL for an empty view.
Definition string.h:58
#define BJ_STR(literal)
Create a view of a string literal.
Definition string.h:75
A borrowed view of a sequence of bytes.
Definition string.h:57
bj_bool bj_read_text_wrapper_line(struct bj_text_wrapper *wrapper, struct bj_str *line, size_t max_bytes)
Reads one line, without its terminator.
struct bj_text_wrapper * bj_create_text_wrapper(struct bj_stream *stream)
Create a text wrapper over a stream.
enum bj_stream_status bj_text_wrapper_status(const struct bj_text_wrapper *wrapper)
Why the last read or write of the wrapper fell short.
void bj_set_text_wrapper_line_ending(struct bj_text_wrapper *wrapper, enum bj_text_line_ending ending)
Sets the line ending the wrapper's line writes append.
bj_bool bj_flush_text_wrapper(struct bj_text_wrapper *wrapper)
Pushes the wrapper's text into the stream, then relays the stream's own flush.
bj_bool bj_read_text_wrapper(struct bj_text_wrapper *wrapper, struct bj_str *chunk, size_t max_bytes)
Reads a chunk of text of up to max_bytes bytes.
bj_bool bj_write_text_wrapper_line(struct bj_text_wrapper *wrapper, struct bj_str text)
Writes text, then the wrapper's line ending.
void bj_destroy_text_wrapper(struct bj_text_wrapper *wrapper)
Destroy a text wrapper and release its memory.
bj_bool bj_peek_text_wrapper(struct bj_text_wrapper *wrapper, struct bj_str *character)
Previews the next character without consuming it.
@ BJ_TEXT_LINE_ENDING_CRLF
A carriage return, then a line feed.
@ BJ_TEXT_LINE_ENDING_LF
A line feed.
Logging utility functions.
All memory-related functions, including custom allocators.
Header file for struct bj_stream struct and related functions.
UTF-8 string views and owning strings.
int main(void)
Header file for struct bj_text_wrapper and related functions.