NAME

str_to_id -- map string to unique integer id

PROTOTYPE

unitptr str_to_id( char *pcTable, char *pcOptions, unitptr uHost)

ARGUMENTS

char *pcTable
optional name of table to use, private table, if NULL
char *pcOptions
options to specify string matching. Can be NULL
unitptr uHost
host unit

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

INTERFACE OF CREATED UNIT:

X_in[*]:
(string input field 0) input string
CTL_in[1]:
(control field) if > 0, each new string will give rise to the allocation of a new id value an the id value is returned. if < 0, the returned id for new strings will be -1 and no new id value will be allocated.
X_out[1]:
(output field 0) the integer id of the input string
Y_out[1]:
the current nr of strings in the table

SYNOPSIS:

Map a string into an integer index, such that the contents of integer indexed objects, such as var_units, can be accessed by keys that are strings.

EXECUTION OF CREATED UNIT:

Maps input string to a integer id value. The id value will be taken from a table containing all previously 'seen' input strings. Depending on the sign of CTL_in, a new input string will be included into the table and given a new id (if CTL_in[0]>0), or the special id -1 for 'not known' is returned and the string is not included in the table (if CTL_in[0]<0). The range of returned id values is always 0 to one less than the number of (different) strings already 'seen'. If a string has an id of k (k=0,1,..) this means that this string was included into the table as the k-th string. String access is by a hashing scheme and therefore fast even for large numbers of keys.

SHARING TABLES:

Usually, each instance of the str_to_id unit will use its private table (therefore, different instances of of str_to_id do not necessarily return the same id values for the same input string). To obtain the same mapping in different places requires either to share a single instance of the str_to_id unit with the used_name unit, or to share the same mapping table among several str_to_id instances. The latter can be achieved by specifying a name for the table to be shared.

NEO NOTE:

Sharing of tables is even across different circuits in Neo!

INITIALIZATION:

NST_INIT:
this will clear the current table. If the table is shared with other units, their mappings will be cleared, too.

SEE ALSO:

var_units, switch_input, switch_output, read_file, read_data, read_image

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_string.c