Simple hash table of arbitrary keys to values. More...

#include <table.h>

Public Member Functions
void	krk_initTable (KrkTable *table)
	Initialize a hash table. More...

void	krk_freeTable (KrkTable *table)
	Release resources associated with a hash table. More...

void	krk_tableAddAll (KrkTable from, KrkTable to)
	Add all key-value pairs from 'from' into 'to'. More...

struct KrkString *	krk_tableFindString (KrkTable table, const char chars, size_t length, uint32_t hash)
	Find a character sequence in the string interning table. More...

int	krk_tableSet (KrkTable *table, KrkValue key, KrkValue value)
	Assign a value to a key in a table. More...

int	krk_tableGet (KrkTable table, KrkValue key, KrkValue value)
	Obtain the value associated with a key in a table. More...

int	krk_tableGet_fast (KrkTable table, struct KrkString str, KrkValue *value)
	Obtain the value associated with a string key in a table. More...

int	krk_tableDelete (KrkTable *table, KrkValue key)
	Remove a key from a hash table. More...

int	krk_tableDeleteExact (KrkTable *table, KrkValue key)
	Remove a key from a hash table, with identity lookup. More...

void	krk_tableAdjustCapacity (KrkTable *table, size_t capacity)
	Preset the size of a table. More...

int	krk_tableSetIfExists (KrkTable *table, KrkValue key, KrkValue value)
	Update the value of a table entry only if it is found. More...

KrkNative *	krk_defineNative (KrkTable table, const char name, NativeFn function)
	Attach a native C function to an attribute table. More...

KrkNative *	krk_defineNativeProperty (KrkTable table, const char name, NativeFn func)
	Attach a native dynamic property to an attribute table. More...

void	krk_attachNamedValue (KrkTable *table, const char name[], KrkValue obj)
	Attach a value to an attribute table. More...

void	krk_attachNamedObject (KrkTable table, const char name[], KrkObj obj)
	Attach an object to an attribute table. More...

Data Fields
size_t	count

size_t	capacity

size_t	used

KrkTableEntry *	entries

ssize_t *	indexes

Detailed Description

Simple hash table of arbitrary keys to values.

Definition at line 28 of file table.h.

Member Function Documentation

◆ krk_attachNamedObject()

void krk_attachNamedObject	(	KrkTable *	table,
		const char	name[],
		KrkObj *	obj
	)

Attach an object to an attribute table.

Manages the stack shuffling and boxing of the name string when attaching an object to an attribute table. Rather than using krk_tableSet, this is the preferred method of supplying fields to objects from C code.

This is a convenience wrapper around krk_attachNamedValue.

Note that since this inserts values directly into tables, it skips any mechanisms like __setattr__ or descriptor __set__. If you need to support these mechanisms, use krk_setAttribute. If you have an instance and would like to emulate the behavior of object.__setattr__, you may also wish to use krk_instanceSetAttribute_wrapper.

Warning: As this function takes a C string, it does not support setting attributes; with names containing nil bytes. Use one of the other mechanisms if you; do not have full control over the attribute names you are trying to set.

Parameters

table	Attribute table to attach to, such as `&someInstance->fields`
name	Nil-terminated C string with the name to assign
obj	Object to attach.

Definition at line 808 of file vm.c.

◆ krk_attachNamedValue()

void krk_attachNamedValue	(	KrkTable *	table,
		const char	name[],
		KrkValue	obj
	)

Attach a value to an attribute table.

Manages the stack shuffling and boxing of the name string when attaching a value to an attribute table. Rather than using krk_tableSet, this is the preferred method of supplying fields to objects from C code.

Note that since this inserts values directly into tables, it skips any mechanisms like __setattr__ or descriptor __set__. If you need to support these mechanisms, use krk_setAttribute. If you have an instance and would like to emulate the behavior of object.__setattr__, you may also wish to use krk_instanceSetAttribute_wrapper.

Warning: As this function takes a C string, it does not support setting attributes; with names containing nil bytes. Use one of the other mechanisms if you; do not have full control over the attribute names you are trying to set.

Parameters

table	Attribute table to attach to, such as `&someInstance->fields`
name	Nil-terminated C string with the name to assign
obj	Value to attach.

Definition at line 794 of file vm.c.

◆ krk_defineNative()

KrkNative * krk_defineNative	(	KrkTable *	table,
		const char *	name,
		NativeFn	function
	)

Attach a native C function to an attribute table.

Attaches the given native function pointer to an attribute table while managing the stack shuffling and boxing of both the name and the function object. If name begins with a '.', the native function is marked as a method. If name begins with a ':', the native function is marked as a dynamic property.

Parameters

table	Attribute table to attach to, such as `&someInstance->fields`
name	Nil-terminated C string with the name to assign
function	Native function pointer to attach

Returns: A pointer to the object representing the attached function.

Definition at line 155 of file vm.c.

◆ krk_defineNativeProperty()

KrkNative * krk_defineNativeProperty	(	KrkTable *	table,
		const char *	name,
		NativeFn	func
	)

Attach a native dynamic property to an attribute table.

Mostly the same as krk_defineNative, but ensures the creation of a dynamic property. The intention of this function is to replace uses of defineNative with ":" names, and replace specialized methods with KrkProperty* objects.

Parameters

table	Attribute table to attach to, such as `&someInstance->fields`
name	Nil-terminated C string with the name to assign
func	Native function pointer to attach

Returns: A pointer to the property object created.

Definition at line 1227 of file builtins.c.

◆ krk_freeTable()

void krk_freeTable ( KrkTable * table )

Release resources associated with a hash table.

Frees the entries array for the table and resets count and capacity.

Parameters

table Hash table to release.

Definition at line 41 of file table.c.

◆ krk_initTable()

void krk_initTable ( KrkTable * table )

Initialize a hash table.

This should be called for any new hash table, especially ones initialized in heap or stack space, to set up the capacity, count and initial entries pointer.

Parameters

table Hash table to initialize.

Definition at line 33 of file table.c.

◆ krk_tableAddAll()

void krk_tableAddAll	(	KrkTable *	from,
		KrkTable *	to
	)

Add all key-value pairs from 'from' into 'to'.

Copies each key-value pair from one hash table to another. If a key from 'from' already exists in 'to', the existing value in 'to' will be overwritten with the value from 'from'.

Parameters

from	Source table.
to	Destination table.

Definition at line 202 of file table.c.

◆ krk_tableAdjustCapacity()

void krk_tableAdjustCapacity	(	KrkTable *	table,
		size_t	capacity
	)

Preset the size of a table.

Reserves space for a large table.

Parameters

table	Table to resize.
capacity	Target capacity.

Definition at line 115 of file table.c.

◆ krk_tableDelete()

int krk_tableDelete	(	KrkTable *	table,
		KrkValue	key
	)

Remove a key from a hash table.

Scans the table 'table' for the key 'key' and, if found, removes the entry, replacing it with a tombstone value.

Parameters

table	Table to delete from.
key	Key to delete.

Returns: 1 if the value was found and deleted, 0 if it was not present.

Definition at line 238 of file table.c.

◆ krk_tableDeleteExact()

int krk_tableDeleteExact	(	KrkTable *	table,
		KrkValue	key
	)

Remove a key from a hash table, with identity lookup.

Scans the table 'table' for the key 'key' and, if found, removes the entry, replacing it with a tombstone value.

Parameters

table	Table to delete from.
key	Key to delete.

Returns: 1 if the value was found and deleted, 0 if it was not present.

Definition at line 249 of file table.c.

◆ krk_tableFindString()

struct KrkString * krk_tableFindString	(	KrkTable *	table,
		const char *	chars,
		size_t	length,
		uint32_t	hash
	)

Find a character sequence in the string interning table.

Scans through the entries in a given table - usually vm.strings - to find an entry equivalent to the string specified by the 'chars' and 'length' parameters, using the 'hash' parameter to speed up lookup.

Parameters

table	Should always be `&vm.strings`
chars	C array of chars representing the string.
length	Length of the string.
hash	Precalculated hash value for the string.

Returns: If the string was found, the string object representation, else NULL.

Definition at line 260 of file table.c.

◆ krk_tableGet()

int krk_tableGet	(	KrkTable *	table,
		KrkValue	key,
		KrkValue *	value
	)

Obtain the value associated with a key in a table.

Scans the table 'table' for the key 'key' and, if found, outputs the associated value to *value. If the key is not found, then *value will not be changed.

Parameters

table	Table to look up.
key	Key to look for.
value	Output pointer to place resulting value in.

Returns: 0 if the key was not found, 1 if it was.

Definition at line 211 of file table.c.

◆ krk_tableGet_fast()

int krk_tableGet_fast	(	KrkTable *	table,
		struct KrkString *	str,
		KrkValue *	value
	)

Obtain the value associated with a string key in a table.

Same as krk_tableGet(), but only works for string keys. This is faster than using krk_tableGet() and should be used when referencing attribute tables or other places where keys are guaranteed to only be strings.

Parameters

table	Table to look up.
str	Key to look for.
value	Output pointer to place resulting value in.

Returns: 0 if the key was not found, 1 if it was.

Definition at line 219 of file table.c.

◆ krk_tableSet()

int krk_tableSet	(	KrkTable *	table,
		KrkValue	key,
		KrkValue	value
	)

Assign a value to a key in a table.

Inserts the key-value pair specified by 'key' and 'value' into the hash table 'table', replacing any value that was already preseng with the same key.

Parameters

table	Table to assign to.
key	Key to assign.
value	Value to assign to the key.

Returns: 0 if the key was already present and has been overwritten, 1 if the key is new to the table.

Definition at line 148 of file table.c.

◆ krk_tableSetIfExists()

int krk_tableSetIfExists	(	KrkTable *	table,
		KrkValue	key,
		KrkValue	value
	)

Update the value of a table entry only if it is found.

Searches the table for key and updates its value to value if found. If key is not found, it is not added to the table.

Warning: Note the return value of this function is inverted from krk_tableSet

Parameters

table	Table to assign to.
key	Key to assign.
value	Value to assign to the key.

Returns: 0 if the key was not present, 1 if it was found and updated.

Definition at line 194 of file table.c.

Field Documentation

◆ capacity

size_t KrkTable::capacity

Size (in items) of each of the entries/indexes arrays

Definition at line 30 of file table.h.

◆ count

size_t KrkTable::count

Number of actual items in the dict.

Definition at line 29 of file table.h.

◆ entries

KrkTableEntry* KrkTable::entries

Key-value pairs, in insertion order (with KWARGS_VAL(0) gaps)

Definition at line 32 of file table.h.

◆ indexes

ssize_t* KrkTable::indexes

Actual hash map: indexes into the key-value pairs.

Definition at line 33 of file table.h.

◆ used

size_t KrkTable::used

Next insertion index in the entries array

Definition at line 31 of file table.h.

The documentation for this struct was generated from the following files:

src/kuroko/table.h
src/kuroko/vm.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ krk_attachNamedObject()

◆ krk_attachNamedValue()

◆ krk_defineNative()

◆ krk_defineNativeProperty()

◆ krk_freeTable()

◆ krk_initTable()

◆ krk_tableAddAll()

◆ krk_tableAdjustCapacity()

◆ krk_tableDelete()

◆ krk_tableDeleteExact()

◆ krk_tableFindString()

◆ krk_tableGet()

◆ krk_tableGet_fast()

◆ krk_tableSet()

◆ krk_tableSetIfExists()

Field Documentation

◆ capacity

◆ count

◆ entries

◆ indexes

◆ used