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

Runtime-owned sparse array objects for SNOBOL4. More...

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

Go to the source code of this file.

Classes

struct  array_entry
 A single entry in the sparse array. More...
struct  snobol_array
 Sparse array state. More...

Macros

#define ARRAY_INITIAL_CAPACITY   16
 Initial capacity for a new array.

Typedefs

typedef struct array_entry array_entry_t
 A single entry in the sparse array.
typedef struct snobol_array snobol_array_t
 Sparse array state.

Functions

snobol_array_t * snobol_array_create (int32_t bounds_hint)
 Create a new sparse array.
snobol_array_t * snobol_array_retain (snobol_array_t *array)
 Retain (increment refcount) an array.
void snobol_array_release (snobol_array_t *array)
 Release (decrement refcount) an array; frees when refcount reaches 0.
bool snobol_array_set (snobol_array_t *array, int32_t key, const char *value)
 Set a value at the given key.
const char * snobol_array_get (const snobol_array_t *array, int32_t key)
 Get the value at a given key.
bool snobol_array_set_ex (snobol_array_t *array, int32_t key, const char *value, size_t value_len)
 Set a value at the given key (NUL-safe byte-exact variant).
const char * snobol_array_get_ex (const snobol_array_t *array, int32_t key, size_t *out_len)
 Get the value at a given key (NUL-safe).
bool snobol_array_has (const snobol_array_t *array, int32_t key)
 Check whether a key has an active entry.
bool snobol_array_delete (snobol_array_t *array, int32_t key)
 Delete the entry at a given key (marks as tombstone).
void snobol_array_clear (snobol_array_t *array)
 Clear all entries from the array (resets to empty).
size_t snobol_array_size (const snobol_array_t *array)
 Return the number of active entries.
int32_t * snobol_array_keys (const snobol_array_t *array, size_t *out_count)
 Get all active keys.
char ** snobol_array_values (const snobol_array_t *array, size_t *out_count)
 Get all active values.

Detailed Description

Runtime-owned sparse array objects for SNOBOL4.

Provides an integer-keyed sparse array with get/set/delete/size operations. Arrays use reference counting for safe sharing across pattern executions. Keys are int32_t; values are strings (copied on insert).

Ownership/Lifetime Rules:

  • Arrays are created with snobol_array_create() and must be freed with snobol_array_release()
  • Arrays use reference counting for safe sharing
  • When reference count reaches 0, the array and all entries are freed
  • A NULL value indicates a deleted entry (tombstone)

Definition in file array.h.

Macro Definition Documentation

◆ ARRAY_INITIAL_CAPACITY

#define ARRAY_INITIAL_CAPACITY   16

Initial capacity for a new array.

Definition at line 30 of file array.h.

Typedef Documentation

◆ array_entry_t

typedef struct array_entry array_entry_t

A single entry in the sparse array.

◆ snobol_array_t

typedef struct snobol_array snobol_array_t

Sparse array state.

Function Documentation

◆ snobol_array_clear()

void snobol_array_clear ( snobol_array_t * array)

Clear all entries from the array (resets to empty).

Parameters
arrayTarget array.

◆ snobol_array_create()

snobol_array_t * snobol_array_create ( int32_t bounds_hint)

Create a new sparse array.

Parameters
bounds_hintExpected key range hint (may be 0).
Returns
New array, or NULL on allocation failure.

◆ snobol_array_delete()

bool snobol_array_delete ( snobol_array_t * array,
int32_t key )

Delete the entry at a given key (marks as tombstone).

Parameters
arrayTarget array.
keyInteger key.
Returns
true on success, false if the key was not found.

◆ snobol_array_get()

const char * snobol_array_get ( const snobol_array_t * array,
int32_t key )

Get the value at a given key.

Parameters
arrayTarget array.
keyInteger key.
Returns
Pointer to internal value string (owned by array, do not free), or NULL if the key is not set or is a tombstone.

◆ snobol_array_get_ex()

const char * snobol_array_get_ex ( const snobol_array_t * array,
int32_t key,
size_t * out_len )

Get the value at a given key (NUL-safe).

Parameters
arrayTarget array.
keyInteger key.
out_lenSet to the byte length of the returned value (may be NULL).
Returns
Pointer to internal value string (owned by array, do not free), or NULL if the key is not set or is a tombstone.

◆ snobol_array_has()

bool snobol_array_has ( const snobol_array_t * array,
int32_t key )

Check whether a key has an active entry.

Parameters
arrayTarget array.
keyInteger key.
Returns
true if the key exists and is not a tombstone.

◆ snobol_array_keys()

int32_t * snobol_array_keys ( const snobol_array_t * array,
size_t * out_count )

Get all active keys.

Parameters
arrayTarget array.
out_countSet to the number of keys returned.
Returns
Malloc'd array of keys (caller must free), or NULL on error.

◆ snobol_array_release()

void snobol_array_release ( snobol_array_t * array)

Release (decrement refcount) an array; frees when refcount reaches 0.

Parameters
arrayArray to release (NULL is safe).

◆ snobol_array_retain()

snobol_array_t * snobol_array_retain ( snobol_array_t * array)

Retain (increment refcount) an array.

Parameters
arrayArray to retain.
Returns
The same array pointer.

◆ snobol_array_set()

bool snobol_array_set ( snobol_array_t * array,
int32_t key,
const char * value )

Set a value at the given key.

Parameters
arrayTarget array.
keyInteger key.
valueNUL-terminated string value (copied internally).
Returns
true on success, false on allocation failure.

◆ snobol_array_set_ex()

bool snobol_array_set_ex ( snobol_array_t * array,
int32_t key,
const char * value,
size_t value_len )

Set a value at the given key (NUL-safe byte-exact variant).

Parameters
arrayTarget array.
keyInteger key.
valueString value (copied internally), or NULL to delete.
value_lenByte length of value (may contain NULs).
Returns
true on success, false on allocation failure.

◆ snobol_array_size()

size_t snobol_array_size ( const snobol_array_t * array)

Return the number of active entries.

Parameters
arrayTarget array.
Returns
Active entry count.

◆ snobol_array_values()

char ** snobol_array_values ( const snobol_array_t * array,
size_t * out_count )

Get all active values.

Parameters
arrayTarget array.
out_countSet to the number of values returned.
Returns
Malloc'd array of value strings (caller must free), or NULL on error.