Hamster-Scripts: Functions (built-in)

Lists

ListAlloc( <sorted>, <duplicates> )

...
ListAlloc

Creates a new list of strings and returns a unique handle for it. This handle is noted as <list> in the other list-functions described below and is valid until the list if freed again by "ListFree".

If <sorted> is set to TRUE (<>0), the list is automatically sorted when adding new entries (default is: not sorted).

If <duplicates> is set to TRUE (<>0), duplicate entries are allowed and will be accepted (default), otherwise they will be ignored, so each entry becomes unique. Note, that this only works for sorted lists.

Returns: >=0: list-handle, -1: too many lists.

$list = ListAlloc

ListFree( <list> )

Frees a list created by "ListAlloc".

Returns: 0: OK, -1: invalid list-handle

listfree( $list )

ListExists( <list>, <index> )

ListExists( <list> )

Checks, if <list> points to a valid list. If <index> is given, it also checks, if the list has an entry for this index.

Returns: 1/true: is valid; 0/false: invalid

sub DoSomethingWithList( $list )
   if( !ListExists( $list )
      error( "List expected!" )
   endif
   # ...
endsub

ListClear( <list> )

Deletes all entries in the given list.

Returns: 0: OK; -1: invalid list-handle

ListClear( $list )

ListCount( <list> )

Returns the number of list-entries.

Returns: number of list-entries

print( ListCount( $list ) )

ListGet( <list>, <index> )

Returns the string with the given <index>. Entries are numbered from 0 to (ListCount-1).

Returns: String (empty string, if list or index was invalid)

$i = 0
while( $i < ListCount($list) )
   print( $i, ": ", ListGet($list,$i) )
   inc( $i )
endwhile

ListSet( <list>, <index>, <value> )

ListSet( <list>, <index> )

Changes the value of the list-entry at <index>. If no <value> is given, it is set to an empty string.

If the list does not contain enough entries yet, they are automatically created as empty strings, so the list can be used like an open array of strings.

Returns: <value>

ListSet( $list, 42, "The answer!" )

ListGetTag( <list>, <index> )

Returns the "Tag"-value of the string at the given <index>. A "Tag"-value is just a number associated with each entry.

Returns: Integer

$entry_itself = ListGet( $list, 42 )
$tag_of_entry = ListGetTag( $list, 42 )

ListSetTag( <list>, <index>, <tag> )

Sets the "Tag"-value of the string at the given <index>.

Returns: <tag>

$index = ListAdd( $list, "The answer!" )
ListSetTag( $list, $index, 42 )

ListGetKey( <list>, <key> )

If the list contains strings in the form "key=value", this command returns the value of key <key>.

Returns: String

# see example under ListSetKey

ListSetKey( <list>, <key>, <value> )

ListSetKey( <list>, <key> )

If the list contains strings in the form "key=value", this command sets the value of key <key>. If no value is given, it is set to an empty string.

Returns: <value>

$list = ListCreate
ListSetKey( $list, "RTFM", "Read the f... manual!" )
ListSetKey( $list, "SCNR", "Sorry, could not resist!" )
print( ListGetKey( $list, "SCNR" ) )

ListAdd( <list>, <value> )

ListAdd( <list> )

Appends a new entry with the given <value> (default: empty string).

Returns: Index of new entry.

$index = ListAdd( $list, $text )

ListDelete( <list>, <index> )

Deletes the entry with the given <index>.

Returns: 0

$index = ListAdd( $list, $text )

ListInsert( <list>, <index>, <value> )

ListInsert( <list>, <index> )

Inserts a new entry with the given value (default: empty string) at the given <index>.

Returns: 0

ListInsert( $list, 0, $text )

ListSort( <list> )

Sorts the given list by its values.

Returns: 0

ListSort( $list )

ListSetText( <list>, <text> )

Clears the list and adds an entry for each line of <text>, which is separated by CR+LF.

Returns: <text>

ListSetText( $list, $article )
print( ListGet( $list, 0 ) )  # -> first line of $article

ListGetText( <list> )

Returns a CR/LF-separated text containing all list-entries.

Returns: String

$article = ListGetText( $list )

ListIndexOf( <list>, <value> )

Returns the index of the list-entry, which equals <value>.

Returns: >=0: index, -1: not found

ListSetText( $list, $article )
$EndOfHdr = ListIndexOf( $list, "" )

ListLoad( <list>, <textfile> )

Loads the given <textfile> and creates a list-entry for each line of the file.

Returns: 0: OK, -1: list invalid, -2 file access error

ListLoad( $list, "MyScript.cfg" )

ListSave( <list>, <textfile> )

Saves the list in the given <textfile>.

Returns: 0: OK, -1: list invalid, -2 file access error

ListSave( $list, "MyScript.cfg" )

ListAppend( <list>, <textfile> )

Appends the list to the given <textfile>.

Returns: 0: OK, -1: list invalid, -2 file access error

ListAppend( $list, "MyLogfile.log" )

ListFiles( <list>, <filemask>, <fullpath> )

ListFiles( <list>, <filemask> )

Fills the list with the filenames selected by <file-mask>.

If <fullpath> is given and TRUE (<>0), all files are expanded with their pathname, otherwise only the filenames are returned.

Returns: >=0: OK (number of files),<0: list invalid or file not found

ListFiles( $list, HamPath + "Mails\Mail.Out\*.msg", true )

ListDirs( <list>, <filemask>, <fullpath> )

ListDirs( <list>, <filemask> )

Fills the list with the directory-names selected by <file-mask>.

If <fullpath> is given and TRUE (<>0), all directory-names are expanded with their pathname, otherwise only the names are returned.

Returns: >=0: OK (number of files),<0: list invalid or file not found

ListDirs( $list, HamPath + "Mails\*." )

ListRasEntries( <list> )

Fills the list with the names of all RAS phonebook entries.

Returns: >=0: OK (number of entries),<0: list invalid or error

varset( $RasList, ListAlloc )
if( ListRasEntries($RasList) > 0 )
   # ...
endif
ListFree( $RasList )

[www.elbiah.de Hamster Playground Documentation]