SMAUG has a nice amount of
wrappers that allow for easy creation of stuff. For example if you want to create a new obj, you would do like
this:
OBJ_DATA *obj;
CREATE(obj, OBJ_DATA, 1);
nice and simple right? now
you’ve got a new obj that’s been allocated and is free to edit. I’m going to run down a list of
wrappers/functions that is included in SMAUG and try to explain them
CREATE( pointer, data_type,
amount) - allocates memory for data_type and assigns pointer the address of the
memory it creates
LINK (node, first_node,
last_node, next, prev); will insert node in the doubly linked list, at the end
of it.
UNLINK(node, first_node,
last_node, next, prev); will remove node from the doubly linked list it’s in.
INSERT(node, node_before,
first_node, next, prev); will insert node, before node_before in a doubly
linked list.
DISPOSE(pointer); frees
pointer that was created with CREATE
Here comes the fun part
hashed/unhashed strings. If you don’t
understand what hashing is, let’s just say it’s a way to improve the speed of
finding things. For instance if you
have a linked list, and you want to find something you may have to go through
the whole list, or the first item, so your average amount is number of linked
lists / 2. Hast improves this by using
ways of ‘sorting’ the list, so when you
search for a string, it has to go through less to find the string. Although the worst and best case scenarios
are the same as a linked list, the average time it takes to find it, is much
less.
QUICKLINK: increments the
internal usage counter for a hashed string and
returns a pointer to said
string
STRALLOC: duplicates a
string. searches the string hash table
for the
string, and if it exists,
performs the equivalent of a QUICKLINK.
if it
doesn’t exist, it adds it to
the hash table and returns a pointer to the
new (hashed) copy of the
string. can use this on either hashed
or
unhashed strings, but it
returns a hashed string.
STRFREE: frees a hashed
string.
QUICKMATCH: compares two
hashed strings ("quickly") by comparing their
memory addresses. it wont crash you if you use it on an
unhashed string, but it will always return false. (hashed strings share memory which is why this works for them,
and the whole purpose of hashing in the first place really)
fread_string: reads a
tilde-terminated(~) string from a file, hashes it,
and returns a pointer to the
string
str_dup: duplicates a
string. can be used on either hashed or
unhashed,
but returns an unhashed
string.
fread_string_nohash: does
the same as fread_string, but the string doesn’t get hashed.
Altrag was the one who wrote
those explanations of the functions, you can find the email in the SMAUG
Mailing list archives.
It is important to know
whether a string is hashed or not, because if you used the wrong functions, you
can end up with problems, and I know this first hand.