libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
Loading...
Searching...
No Matches
table.h File Reference

Runtime-owned associative table objects for SNOBOL4. More...

#include "snobol/snobol_attrs.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for table.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  table_entry
struct  snobol_table

Macros

#define TABLE_INITIAL_CAPACITY   16

Typedefs

typedef struct table_entry table_entry_t
typedef struct snobol_table snobol_table_t

Functions

snobol_table_t * table_create (const char *name)
 Create a new runtime table.
snobol_table_t * table_retain (snobol_table_t *table)
 Increment table reference count.
void table_release (snobol_table_t *table)
 Decrement table reference count and free if zero.
bool table_set (snobol_table_t *table, const char *key, const char *value)
 Insert or update a key-value pair.
const char * table_get (const snobol_table_t *table, const char *key)
 Look up a value by key.
bool table_has (const snobol_table_t *table, const char *key)
 Check if a key exists in the table.
bool table_delete (snobol_table_t *table, const char *key)
 Delete a key from the table.
bool table_set_ex (snobol_table_t *table, const char *key, size_t key_len, const char *value, size_t value_len)
 Insert or update a key-value pair (NUL-safe byte-exact variants).
const char * table_get_ex (const snobol_table_t *table, const char *key, size_t key_len, size_t *out_len)
 Look up a value by key (NUL-safe).
bool table_has_ex (const snobol_table_t *table, const char *key, size_t key_len)
 Check if a key exists in the table (NUL-safe).
bool table_delete_ex (snobol_table_t *table, const char *key, size_t key_len)
 Delete a key from the table (NUL-safe).
uint32_t table_hash_string (const char *str)
 Hash function for strings (FNV-1a).
uint32_t table_hash_bytes (const char *str, size_t len)
 Hash function for byte-exact strings (FNV-1a, NUL-safe).
void table_clear (snobol_table_t *table)
 Clear all entries from the table.
size_t table_size (const snobol_table_t *table)
 Get the number of active entries.
const char * table_name (const snobol_table_t *table)
 Get the table name (for debugging).

Detailed Description

Runtime-owned associative table objects for SNOBOL4.

Ownership/Lifetime Rules:

  • Tables are created with table_create() and must be freed with table_release()
  • Tables use reference counting for safe sharing across pattern executions
  • When reference count reaches 0, the table and all entries are freed
  • Table keys are strings (copied on insert)
  • Table values are strings (copied on insert)
  • NULL value indicates a deleted entry (tombstone)

Definition in file table.h.

Macro Definition Documentation

◆ TABLE_INITIAL_CAPACITY

#define TABLE_INITIAL_CAPACITY   16

Definition at line 28 of file table.h.

Typedef Documentation

◆ snobol_table_t

typedef struct snobol_table snobol_table_t

◆ table_entry_t

typedef struct table_entry table_entry_t

Function Documentation

◆ table_clear()

void table_clear ( snobol_table_t * table)

Clear all entries from the table.

Parameters
tableTable to clear

◆ table_create()

snobol_table_t * table_create ( const char * name)

Create a new runtime table.

Parameters
nameOptional name for debugging (can be NULL)
Returns
Pointer to new table, or NULL on failure

Ownership: Caller owns the returned table and must call table_release()

◆ table_delete()

bool table_delete ( snobol_table_t * table,
const char * key )

Delete a key from the table.

Parameters
tableTable to modify
keyKey to delete
Returns
true if key was found and deleted

◆ table_delete_ex()

bool table_delete_ex ( snobol_table_t * table,
const char * key,
size_t key_len )

Delete a key from the table (NUL-safe).

Parameters
tableTable to modify
keyKey to delete
key_lenByte length of key
Returns
true if key was found and deleted

◆ table_get()

const char * table_get ( const snobol_table_t * table,
const char * key )

Look up a value by key.

Parameters
tableTable to query
keyKey to look up
Returns
Pointer to value string, or NULL if not found

Ownership: Returned pointer is owned by the table, do not free The pointer remains valid until the entry is modified or deleted

◆ table_get_ex()

const char * table_get_ex ( const snobol_table_t * table,
const char * key,
size_t key_len,
size_t * out_len )

Look up a value by key (NUL-safe).

Parameters
tableTable to query
keyKey to look up
key_lenByte length of key
out_lenSet to the byte length of the returned value (may be NULL)
Returns
Pointer to value string, or NULL if not found

Ownership: Returned pointer is owned by the table, do not free The pointer remains valid until the entry is modified or deleted

◆ table_has()

bool table_has ( const snobol_table_t * table,
const char * key )

Check if a key exists in the table.

Parameters
tableTable to query
keyKey to check
Returns
true if key exists with a non-NULL value

◆ table_has_ex()

bool table_has_ex ( const snobol_table_t * table,
const char * key,
size_t key_len )

Check if a key exists in the table (NUL-safe).

Parameters
tableTable to query
keyKey to check
key_lenByte length of key
Returns
true if key exists with a non-NULL value

◆ table_hash_bytes()

uint32_t table_hash_bytes ( const char * str,
size_t len )

Hash function for byte-exact strings (FNV-1a, NUL-safe).

Parameters
strBytes to hash
lenByte length
Returns
32-bit hash value

◆ table_hash_string()

uint32_t table_hash_string ( const char * str)

Hash function for strings (FNV-1a).

Parameters
strString to hash
Returns
32-bit hash value

◆ table_name()

const char * table_name ( const snobol_table_t * table)

Get the table name (for debugging).

Parameters
tableTable to query
Returns
Table name or NULL if unnamed

◆ table_release()

void table_release ( snobol_table_t * table)

Decrement table reference count and free if zero.

Parameters
tableTable to release

When refcount reaches 0, all entries and the table itself are freed

◆ table_retain()

snobol_table_t * table_retain ( snobol_table_t * table)

Increment table reference count.

Parameters
tableTable to retain
Returns
Same table pointer for convenience

Use when sharing table ownership with another owner

◆ table_set()

bool table_set ( snobol_table_t * table,
const char * key,
const char * value )

Insert or update a key-value pair.

Parameters
tableTable to modify
keyString key (copied)
valueString value (copied), or NULL to delete
Returns
true on success, false on allocation failure

Ownership: Table takes ownership of copies of key and value

◆ table_set_ex()

bool table_set_ex ( snobol_table_t * table,
const char * key,
size_t key_len,
const char * value,
size_t value_len )

Insert or update a key-value pair (NUL-safe byte-exact variants).

Parameters
tableTable to modify
keyString key (copied)
key_lenByte length of key (may contain NULs)
valueString value (copied), or NULL to delete
value_lenByte length of value
Returns
true on success, false on allocation failure

Ownership: Table takes ownership of copies of key and value

◆ table_size()

size_t table_size ( const snobol_table_t * table)

Get the number of active entries.

Parameters
tableTable to query
Returns
Number of active (non-deleted) entries