Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Text Wrapper

Typedefs

typedef enum bj_text_line_ending bj_text_line_ending

Enumerations

enum  bj_text_line_ending { BJ_TEXT_LINE_ENDING_NATIVE = 0x00 , BJ_TEXT_LINE_ENDING_CR = 0x01 , BJ_TEXT_LINE_ENDING_LF = 0x02 , BJ_TEXT_LINE_ENDING_CRLF = BJ_TEXT_LINE_ENDING_CR | BJ_TEXT_LINE_ENDING_LF }

Functions

struct bj_text_wrapper * bj_create_text_wrapper (struct bj_stream *stream)
void bj_destroy_text_wrapper (struct bj_text_wrapper *wrapper)
bj_bool bj_read_text_wrapper (struct bj_text_wrapper *wrapper, struct bj_str *chunk, size_t max_bytes)
bj_bool bj_read_text_wrapper_line (struct bj_text_wrapper *wrapper, struct bj_str *line, size_t max_bytes)
bj_bool bj_peek_text_wrapper (struct bj_text_wrapper *wrapper, struct bj_str *character)
bj_bool bj_write_text_wrapper (struct bj_text_wrapper *wrapper, struct bj_str text)
bj_bool bj_write_text_wrapper_line (struct bj_text_wrapper *wrapper, struct bj_str text)
bj_bool bj_flush_text_wrapper (struct bj_text_wrapper *wrapper)
enum bj_stream_status bj_text_wrapper_status (const struct bj_text_wrapper *wrapper)
void bj_clear_text_wrapper_status (struct bj_text_wrapper *wrapper)
void bj_set_text_wrapper_line_ending (struct bj_text_wrapper *wrapper, enum bj_text_line_ending ending)
enum bj_text_line_ending bj_text_wrapper_line_ending (const struct bj_text_wrapper *wrapper)

Detailed Description

Read and write UTF-8 text over any stream, line by line or chunk by chunk, with the buffering, the seam handling and the line semantics written once.

A text wrapper borrows a bj_stream and gives text operations over it. The caller keeps the stream: create the wrapper, read or write text through it, then destroy the wrapper before the stream.

While the wrapper lives, it locks its stream: the wrapper is the only reader and writer. A transfer that takes the locked stream directly moves nothing and records BJ_STREAM_STATUS_LOCKED. Pure queries, such as bj_stream_length, still answer.

Wrap a stream

BJ_STR("game.cfg"), BJ_STREAM_READ, 0);
struct bj_str line;
while (bj_read_text_wrapper_line(text, &line, 0)) {
// line borrows wrapper memory, valid until the next call
}
bj_destroy_text_wrapper(text); // release the lock, then destroy the file
struct bj_stream bj_stream
Definition api.h:374
struct bj_text_wrapper bj_text_wrapper
Definition api.h:378
struct bj_stream * bj_create_stream_from_path(struct bj_str path, uint32_t flags, struct bj_error **error)
Create a stream that reads, writes or creates a file.
@ BJ_STREAM_READ
The stream reads.
Definition stream.h:130
#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.
void bj_destroy_text_wrapper(struct bj_text_wrapper *wrapper)
Destroy a text wrapper and release its memory.

Read text

bj_read_text_wrapper_line reads one line, without its terminator. bj_read_text_wrapper reads a chunk of up to max_bytes bytes. bj_peek_text_wrapper previews one character without consuming. Each returns BJ_FALSE when the text ended, and only then.

Write text

bj_write_text_wrapper writes text, bj_write_text_wrapper_line appends the line ending, and bj_flush_text_wrapper pushes everything into the stream. Written text waits in the wrapper until the flush: the stream's length and position do not see it.

Threads

A wrapper belongs to one thread at a time, as its stream does.

Typedef Documentation

◆ bj_text_line_ending

Definition at line 75 of file text_wrapper.h.

Enumeration Type Documentation

◆ bj_text_line_ending

The line ending a wrapper's line writes append.

Enumerator
BJ_TEXT_LINE_ENDING_NATIVE 

The platform's convention, resolved when set.

BJ_TEXT_LINE_ENDING_CR 

A carriage return.

BJ_TEXT_LINE_ENDING_LF 

A line feed.

BJ_TEXT_LINE_ENDING_CRLF 

A carriage return, then a line feed.

Definition at line 68 of file text_wrapper.h.

Function Documentation

◆ bj_clear_text_wrapper_status()

void bj_clear_text_wrapper_status ( struct bj_text_wrapper * wrapper)

Sets the wrapper's status back to BJ_STREAM_STATUS_OK.

Parameters
wrapperThe wrapper, or 0, which does nothing.

◆ bj_create_text_wrapper()

struct bj_text_wrapper * bj_create_text_wrapper ( struct bj_stream * stream)

Create a text wrapper over a stream.

The wrapper borrows stream: the caller keeps it, and must destroy the wrapper first. While the wrapper lives, stream is locked: its transfers are refused and record BJ_STREAM_STATUS_LOCKED, and a second wrapper over the same stream, or a new span over it, gives 0.

The wrapper starts with the line ending BJ_TEXT_LINE_ENDING_LF and the status BJ_STREAM_STATUS_OK.

Parameters
streamThe stream to wrap, or 0, which gives 0.
Returns
A new bj_text_wrapper, or 0 when stream is 0, is already locked, or when memory runs out.
See also
bj_destroy_text_wrapper
Examples
text_wrapper.c.

Referenced by main().

◆ bj_destroy_text_wrapper()

void bj_destroy_text_wrapper ( struct bj_text_wrapper * wrapper)

Destroy a text wrapper and release its memory.

The wrapper pushes the text it holds into the stream, then returns the stream to the position its delivered text reached, when the stream can seek. The stream's lock is released, and the stream itself survives.

Parameters
wrapperThe wrapper to destroy. 0 is ignored.
See also
bj_create_text_wrapper
Examples
text_wrapper.c.

Referenced by main().

◆ bj_flush_text_wrapper()

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.

A push that falls short keeps its remainder, and the next flush or write retries it.

Parameters
wrapperThe wrapper, or 0, which gives BJ_FALSE.
Returns
BJ_TRUE when the pipeline drained, BJ_FALSE with bj_text_wrapper_status saying why.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_peek_text_wrapper()

bj_bool bj_peek_text_wrapper ( struct bj_text_wrapper * wrapper,
struct bj_str * character )

Previews the next character without consuming it.

The delivered character is a borrowed view of wrapper memory, valid until the next call that takes the wrapper. The preview is the first character the next read would deliver: malformed bytes preview as U+FFFD, as a read delivers them.

Parameters
wrapperThe wrapper, or 0, which previews nothing.
characterReceives the previewed character.
Returns
BJ_TRUE when a character was previewed, BJ_FALSE at the end of the text.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_read_text_wrapper()

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.

The delivered text is a borrowed view of wrapper memory, valid until the next call that takes the wrapper, and never ends inside a character. The read delivers text and returns BJ_TRUE, or reaches the end of the text and returns BJ_FALSE, and only that.

A max_bytes of 0 probes: it returns BJ_TRUE when text remains, BJ_FALSE at the end, and consumes nothing either way.

Parameters
wrapperThe wrapper, or 0, which reads nothing.
chunkReceives the delivered text.
max_bytesHow many bytes to deliver at most, 0 to probe.
Returns
BJ_TRUE when text was delivered or remains, BJ_FALSE at the end of the text, with bj_text_wrapper_status saying BJ_STREAM_STATUS_END, or why nothing came.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_read_text_wrapper_line()

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.

The reader recognizes LF, CRLF (as one terminator) and a lone CR in every file, and delivers the line's content without its terminator: an empty line is an empty view. A final line without a terminator is delivered like any other.

The delivered line is a borrowed view of wrapper memory, valid until the next call that takes the wrapper. A line longer than max_bytes is delivered as segments of up to max_bytes bytes, cut on a character boundary, and the next call continues the same physical line.

A max_bytes of 0 means no cap: whole lines, however long.

Parameters
wrapperThe wrapper, or 0, which reads nothing.
lineReceives the delivered line.
max_bytesThe most bytes to deliver, 0 for no cap.
Returns
BJ_TRUE when a line was delivered, BJ_FALSE at the end of the text, with bj_text_wrapper_status saying BJ_STREAM_STATUS_END, or why nothing came.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_set_text_wrapper_line_ending()

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_TEXT_LINE_ENDING_NATIVE resolves to the platform's convention at the moment it is set, so bj_text_wrapper_line_ending never reports it.

Parameters
wrapperThe wrapper, or 0, which does nothing.
endingOne bj_text_line_ending.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_text_wrapper_line_ending()

enum bj_text_line_ending bj_text_wrapper_line_ending ( const struct bj_text_wrapper * wrapper)

The line ending the wrapper's line writes append.

Parameters
wrapperThe wrapper, or 0, which gives BJ_TEXT_LINE_ENDING_LF.
Returns
The current ending, always a concrete value.

◆ bj_text_wrapper_status()

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.

The wrapper reports the stream status values it shares with reading and writing: BJ_STREAM_STATUS_OK, BJ_STREAM_STATUS_END, BJ_STREAM_STATUS_NOT_READY, BJ_STREAM_STATUS_ERROR, BJ_STREAM_STATUS_READ_ONLY and BJ_STREAM_STATUS_WRITE_ONLY. The status is sticky, as the stream's is: a read that delivers text clears a soft status, and nothing but bj_clear_text_wrapper_status clears a hard one.

Parameters
wrapperThe wrapper, or 0, which gives BJ_STREAM_STATUS_ERROR.
Returns
The status of the last operation.
Examples
text_wrapper.c.

Referenced by main().

◆ bj_write_text_wrapper()

bj_bool bj_write_text_wrapper ( struct bj_text_wrapper * wrapper,
struct bj_str text )

Writes text, sanitizing malformed bytes.

The bytes are processed at the call: a malformed sequence becomes one U+FFFD, as in bj_create_string. The accepted text waits in the wrapper, invisible to the stream, until bj_flush_text_wrapper, a later push, or the wrapper's destruction.

On a stream that can seek and holds both BJ_STREAM_READ and BJ_STREAM_WRITE, the write lands at the position the reads reached, overwriting what the stream holds there. On a stream that cannot seek, reading and writing interleave freely.

Parameters
wrapperThe wrapper, or 0, which writes nothing.
textThe text to write.
Returns
BJ_TRUE when the text is in the wrapper's keeping; BJ_FALSE when the stream lacks BJ_STREAM_WRITE, with the status BJ_STREAM_STATUS_READ_ONLY, or when memory runs out.

◆ bj_write_text_wrapper_line()

bj_bool bj_write_text_wrapper_line ( struct bj_text_wrapper * wrapper,
struct bj_str text )

Writes text, then the wrapper's line ending.

The ending is the one bj_text_wrapper_line_ending reports, LF by default. BJ_TEXT_LINE_ENDING_NATIVE resolves to the platform's convention at the moment it is set.

Parameters
wrapperThe wrapper, or 0, which writes nothing.
textThe text to write.
Returns
BJ_TRUE when the text is in the wrapper's keeping; BJ_FALSE as bj_write_text_wrapper reports.
Examples
text_wrapper.c.

Referenced by main().