binary_string_table.h File Reference

This files contains an implementation of a binary string table. More...

#include "defines.h"

Go to the source code of this file.

Data Structures
struct	binary_string_table_entry
struct	binary_string_table_header
struct	binary_string_table

Typedefs
typedef struct binary_string_table_entry	binary_string_table_entry
typedef struct binary_string_table_header	binary_string_table_header
typedef struct binary_string_table	binary_string_table

Functions
KAPI binary_string_table	binary_string_table_create (void)
KAPI binary_string_table	binary_string_table_from_block (void *block)
KAPI void	binary_string_table_destroy (binary_string_table *table)
	Destroys the provided binary string table. More...
KAPI u32	binary_string_table_add (binary_string_table *table, const char *string)
	Adds the given string to the provided table. String MUST be null-terminated. More...
KAPI const char *	binary_string_table_get (const binary_string_table *table, u32 index)
	Returns a null-terminated copy of the string from the table. Dynamically allocated and must be freed by the caller. More...
KAPI u32	binary_string_table_length_get (const binary_string_table *table, u32 index)
	Returns the length of the string, NOT accounting for null terminator. More...
KAPI void	binary_string_table_get_buffered (const binary_string_table *table, u32 index, char *buffer)
	Copies string into already-existing buffer. Use binary_string_table_length_get to obtain the length of an entry's string. More...
KAPI void *	binary_string_table_serialized (const binary_string_table *table, u64 *out_size)
	Serialize table to a single block of memory, tagged with MEMORY_TAG_BINARY_DATA. Should be freed by the caller. More...

Detailed Description

This files contains an implementation of a binary string table.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

A binary string table is used to hold strings in a contiguous block of memory in a way that is easily serialized and referenced. Strings are referenced by an index that is returned when an entry is added. This allows data structures that are to be serialized (for example) to simply store that index into this table, which itself can also be serialized into a binary block within the same file and can be referenced later during deserialization.

Note

: Any additions to a binary string table causes reallocations to occur by design. It's designed for (de)serialization, not runtime performance, and should only be used in non-performance-critical code.

Version

1.0

Date

2025-10-21

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2025

Typedef Documentation

binary_string_table

typedef struct binary_string_table binary_string_table

binary_string_table_entry

typedef struct binary_string_table_entry binary_string_table_entry

binary_string_table_header

typedef struct binary_string_table_header binary_string_table_header

Function Documentation

binary_string_table_add()

KAPI u32 binary_string_table_add	(	binary_string_table *	table,
		const char *	string
	)

Adds the given string to the provided table. String MUST be null-terminated.

Parameters

table	A pointer to the table to add to.
The	null-terminated string to be added.

Returns

The index of the added string.

binary_string_table_create()

KAPI binary_string_table binary_string_table_create

(

void

)

Creates a binary string table.

Returns

The newly-created binary string table.

binary_string_table_destroy()

KAPI void binary_string_table_destroy

(

binary_string_table *

table

)

Destroys the provided binary string table.

Parameters

table

A pointer to the table to be destroyted.

binary_string_table_from_block()

KAPI binary_string_table binary_string_table_from_block

(

void *

block

)

Creates a binary string table from the given block of memory. This should have been created by the binary_string_table_serialized() function for this to work correctly. Typically used when reading from a file.

Returns

The newly-created binary string table.

binary_string_table_get()

KAPI const char* binary_string_table_get	(	const binary_string_table *	table,
		u32	index
	)

Returns a null-terminated copy of the string from the table. Dynamically allocated and must be freed by the caller.

Parameters

table	A constant pointer to the table to search.
index	The index of the string to look up.

Returns

A null-terminated copy of the string at the given index.

binary_string_table_get_buffered()

KAPI void binary_string_table_get_buffered	(	const binary_string_table *	table,
		u32	index,
		char *	buffer
	)

Copies string into already-existing buffer. Use binary_string_table_length_get to obtain the length of an entry's string.

Parameters

table	A constant pointer to the table to search.
index	The index of the string to look up.
buffer	Allocated memory to hold the string data. Ideally should be length + 1 to account for a null terminator (although one is not added by this function)

binary_string_table_length_get()

KAPI u32 binary_string_table_length_get	(	const binary_string_table *	table,
		u32	index
	)

Returns the length of the string, NOT accounting for null terminator.

Parameters

table	A constant pointer to the table to search.
index	The index of the string to look up.

Returns

The length of the given entry, NOT counting the null terminator.

binary_string_table_serialized()

KAPI void* binary_string_table_serialized	(	const binary_string_table *	table,
		u64 *	out_size
	)

Serialize table to a single block of memory, tagged with MEMORY_TAG_BINARY_DATA. Should be freed by the caller.

Parameters

table	A constant pointer to the table to serialize.
out_size	A pointer to hold the total serialized block size.

Returns

A block of memory containing the serialized data.