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
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../foldersrc/nst_string.c