|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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 } |
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.
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.
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.
A wrapper belongs to one thread at a time, as its stream does.
| typedef enum bj_text_line_ending bj_text_line_ending |
Definition at line 75 of file text_wrapper.h.
| enum bj_text_line_ending |
The line ending a wrapper's line writes append.
Definition at line 68 of file text_wrapper.h.
| void bj_clear_text_wrapper_status | ( | struct bj_text_wrapper * | wrapper | ) |
Sets the wrapper's status back to BJ_STREAM_STATUS_OK.
| wrapper | The wrapper, or 0, which does nothing. |
| 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.
| stream | The stream to wrap, or 0, which gives 0. |
stream is 0, is already locked, or when memory runs out.Referenced by main().
| 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.
| wrapper | The wrapper to destroy. 0 is ignored. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which gives BJ_FALSE. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which previews nothing. |
| character | Receives the previewed character. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which reads nothing. |
| chunk | Receives the delivered text. |
| max_bytes | How many bytes to deliver at most, 0 to probe. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which reads nothing. |
| line | Receives the delivered line. |
| max_bytes | The most bytes to deliver, 0 for no cap. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which does nothing. |
| ending | One bj_text_line_ending. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which gives BJ_TEXT_LINE_ENDING_LF. |
| 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.
| wrapper | The wrapper, or 0, which gives BJ_STREAM_STATUS_ERROR. |
Referenced by main().
| 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.
| wrapper | The wrapper, or 0, which writes nothing. |
| text | The text to write. |
| 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.
| wrapper | The wrapper, or 0, which writes nothing. |
| text | The text to write. |
Referenced by main().