gmSCStandardListClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

The StandardList Service Class

The service class StandardList processes data stored in standard lists. Much of the information within the language description file is stored in standard lists. The advantage of standard lists is that they can be easily initialized in C-source code with a structure that is identical to the form they take in language description files. The list of entries itself (StandardList) has the following structure:

Byte Description of content
0 The number of entries in the list
1+ The actual entry information vectors, each laid out as follows:

Byte Description of content
0 Length in bytes of this entry information vector
1+ Actual characters making up the entry name
2 Null-byte marking the end of the entry name
3+ Entry associated information or sequence number of entry


Since byte storage is used for lists no list entry can exceed 255 bytes and no list can have more than 255 entries. Though there are no requirements for the content of the list associated information, there is a convention that if there is a unique byte-valued value associated with the list then that value is always first in the entry associated information vector. This value is referred to as the entry identifier. A primary use of standard lists is to provide a quick and dirty way to equate a set of related names with a set of unique numeric values. Lists are quick because they are always relatively short and are easy to either define in the C-source or in a long memory area and they are dirty because they are searched sequentially. This search can either be by name to find the entry associated information of by identifier to find the entry name.

The method StandardList_AddEntry

Prototype


int StandardList_AddEntry(UBYTE* List,int nList,char* Entry,int Length,UBYTE* Info,int nInfo);
The StandardList_AddEntry method adds a new entry to the back of a standard list and optionally associates with it bytes of information or its sequence number (1-based) in the list. This method makes no effort to ensure that the entry is unique relative to other entries in the list. Its parameters are as follows:

Parameter Description
List Contains the list of entries stored in standard list form, as described above. It is updated as part of the operation of this method. It is up to the caller to ensure that the storage allocated is sufficient to contain the new entry.
nList Specifies the length of the list information stored in the standard list already. When the list is initially being created this value should be set to zero. On subsequent calls, it should always equal the previous return value from this method.
Entry Contains the name of the entry to be stored in the list. It need not be null-terminated.
Length Specifies the length of the entry name in characters.
Info Contains the actual information to be associated with the entry. If it is NULL, then the sequence number of the entry in the list is associated with it; else the specified byte vector is stored with the entry.
nInfo Specifies the number of bytes in the information being associated with the entry. If the associated information vector is NULL, then this must equal one.

The method returns the length of the list storage area after the new entry has been added. This value must then become the new value of the nList parameter on the next call to this method.

The method StandardList_FindByIdent

Prototype


UBYTE* StandardList_FindByIdent(UBYTE* StandardList,int Identifier,int nInfo)
The StandardList_FindByIdent method searches a list of entries in a standard list to determine whether an entry exists that has a specified identifier -- i.e., a simple byte value stored in the first byte of its entry associated information. Note that this method does assume that all list entries have the same amount of associated entry information. The length of the information vector may be specified by the caller or can be computed by this method. The computation looks at the total length of the first entry less the length of the name. Its parameters are as follows:

Parameter Description
StandardList contains a list of symbols stored in standard list form as described above to be searched for the index.
Identifier Specifies the index value used to search for the particular corresponding entry. Note that its value must be between 0 and 255.
nInfo Specifies the length of the information vector associated with the entries in the list. If it is greater than zero, then each entry is assumed to have the same specified length. If it is zero, then each entry is assumed to have the same information length as the first entry.

If there is an entry whose first information byte matches the specified index, then a byte pointer to the first such entry is returned. If no matching entry is found, then a NULL is returned.

The method StandardList_FindByName

Prototype


int StandardList_FindByName(UBYTE* StandardList,char* Name,int Length);
The StandardList_FindByName method searches a list of symbols to determine whether a given name is within that list. This method does a case insensitive comparison. Its parameters are as follows:

Parameter Description
StandardList contains a list of symbols stored in standard list form, as described above.
Name Contains the entry name to be located in null-terminated string form.
Length Specifies the length of entry name in characters. If this is zero then the length of the list entry is used for each comparison.

If the name is located then this method returns the byte offset in the standard list of the entry associated information for the name; else it returns a zero.
Table of Contents