symbol.h File Reference

Interned symbol type with BST-accelerated lookup. More...

#include "x-type.h"

Go to the source code of this file.

Macros
#define	X_TYPE_SYMBOL_NAME   "SYMBOL"
Predicates
#define	x_obj_type_issymbol(B, X)   x_obj_is_type((B), (X), X_TYPE_SYMBOL_NAME)
Accessors
#define	x_symbolval(X)   x_firststr((X))
#define	x_symbolname(X)   x_firststr((X))
Type Data Accessors
#define	x_symbol_data   x_type_field_data
#define	x_symbol_data_list(X)   x_0(x_symbol_data((X)))
Constructors
#define	x_mksymbol(B, S)   x_make_symbol((B), X_OBJ_FLAG_NONE, (S))
#define	x_mkfsymbol(B, F, S)   x_make_symbol((B), (F), (S))
#define	x_mksymbolown(B, S)   x_make_symbol((B), X_OBJ_FLAG_OWN, (S))
#define	x_mkfsymbolown(B, F, S)   x_make_symbol((B), X_OBJ_FLAG_OWN | (F), (S))

Functions
x_obj_t *	x_make_symbol (x_obj_t *p_base, x_obj_flag_t flags, x_char_t *s)
x_obj_t *	x_type_symbol_struct (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_register (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_init (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_make (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_find (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_eval (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_write (x_obj_t *p_base, x_obj_t *p_args)

Detailed Description

Interned symbol type with BST-accelerated lookup.

Symbols are atom objects keyed by their string name. All symbols with the same name share the same object (interning), which enables fast pointer-identity comparison during evaluation. An internal BST index provides O(log n) lookup by name.

Author

Jon Ruttan (jonru.nosp@m.ttan.nosp@m.@gmai.nosp@m.l.co.nosp@m.m)

Copyright

2021 Jon Ruttan @license MIT No Attribution (MIT-0)

Macro Definition Documentation

x_mkfsymbol

#define x_mkfsymbol	(		B,
			F,
			S
	)		x_make_symbol((B), (F), (S))

Intern or create a symbol with explicit flags.

x_mkfsymbolown

#define x_mkfsymbolown	(		B,
			F,
			S
	)		x_make_symbol((B), X_OBJ_FLAG_OWN | (F), (S))

Intern or create an owning symbol with extra flags.

x_mksymbol

#define x_mksymbol	(		B,
			S
	)		x_make_symbol((B), X_OBJ_FLAG_NONE, (S))

Intern or create a symbol with default flags.

x_mksymbolown

#define x_mksymbolown	(		B,
			S
	)		x_make_symbol((B), X_OBJ_FLAG_OWN, (S))

Intern or create an owning symbol.

x_obj_type_issymbol

#define x_obj_type_issymbol	(		B,
			X
	)		x_obj_is_type((B), (X), X_TYPE_SYMBOL_NAME)

Test whether X is a SYMBOL object.

x_symbol_data

#define x_symbol_data   x_type_field_data

Access the type-level data field for the SYMBOL type.

x_symbol_data_list

#define x_symbol_data_list

(

X

)

x_0(x_symbol_data((X)))

Get the interned symbol list from the type data.

x_symbolname

#define x_symbolname

(

X

)

x_firststr((X))

Alias for x_symbolval – get the symbol's name.

x_symbolval

#define x_symbolval

(

X

)

x_firststr((X))

Get the symbol's string value.

X_TYPE_SYMBOL_NAME

#define X_TYPE_SYMBOL_NAME   "SYMBOL"

Canonical type name.

Function Documentation

x_make_symbol()

x_obj_t * x_make_symbol	(	x_obj_t *	p_base,
		x_obj_flag_t	flags,
		x_char_t *	s
	)

Allocate (or retrieve interned) SYMBOL for string s.

Allocate (or retrieve interned) SYMBOL for string s.

Packs the string and flags into stack-allocated args and delegates to x_type_symbol_make(), which handles interning.

Parameters

p_base	Base (execution context).
flags	Object flags (e.g. X_OBJ_FLAG_OWN).
s	Null-terminated symbol name.

Returns

Interned SYMBOL object.

x_type_symbol_eval()

x_obj_t * x_type_symbol_eval	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-system eval handler – 3-step environment lookup.

Evaluate a symbol: the value bound to it in the current environment or an ancestor.

The environment is a chain of (bindings . parent) pairs ending at the root, whose bindings are a tree; x_env_lookup walks it. An unbound symbol is an error naming the symbol.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – Eval args: (symbol . env)

Returns

The bound value, or NULL on error.

See also

x_env_lookup

x_type_symbol_find()

x_obj_t * x_type_symbol_find	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Look up an interned symbol by name (BST-accelerated).

Look up an interned symbol by name using the BST index.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element wraps the name string.

Returns

BST node containing the symbol, or NULL if not interned.

x_type_symbol_init()

x_obj_t * x_type_symbol_init	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Initialize the SYMBOL type's intern table.

x_type_symbol_make()

x_obj_t * x_type_symbol_make	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-system make handler – intern or allocate a new SYMBOL.

Type-system make handler – intern or allocate a new SYMBOL.

If a symbol with the same name already exists, returns the existing interned object. Otherwise allocates a new one, appends it to the intern list, and inserts it into the BST. Ownership of the source string is transferred when the source has X_OBJ_FLAG_OWN set.

Interning sequence:

1. Calls x_type_symbol_find which does a BST lookup (O(log n)) on the type's intern BST. If the symbol already exists, the existing heap-allocated symbol object is returned immediately – no allocation.
2. On miss, allocates a new symbol atom via x_obj_make, prepends it to the linear intern list (x_symbol_data_list), and inserts it into the intern BST (x_symbol_bst) for future lookups.
3. String ownership: if the source atom has X_OBJ_FLAG_OWN, that flag is transferred to the new symbol and cleared on the source, ensuring exactly one owner for the malloc'd string.

Parameters

p_base	Base (execution context).
p_args	Argument list: (name-atom [flags-atom]).

Returns

Interned SYMBOL object.

Note

TODO: allow the symbol list to be optionally supplied by argument.

See also

x_type_symbol_find for the BST lookup path

sym_bst_insert for the intern BST insertion (mutating, not path-copying)

x_type_symbol_register()

x_obj_t * x_type_symbol_register	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Register (or retrieve) the SYMBOL type and init its data field.

Register (or retrieve) the SYMBOL type and initialize its data field.

On first call, allocates the intern list and BST root in the type's data slot.

Parameters

p_base	Base (execution context).
p_args	Unused.

Returns

The registered SYMBOL type object.

x_type_symbol_struct()

x_obj_t * x_type_symbol_struct	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Build the SYMBOL type struct descriptor.

x_type_symbol_write()

x_obj_t * x_type_symbol_write	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-system write handler – delegates to sexp symbol writer.