List information

From HEWIKI
Jump to: navigation, search
Note: There are two list types, Lists and Lookup Lists. Each type is handled very differently.

Lists are one of the Data Types for fields or variables. A list can contain any number of elements of a specific type (such as string). The elements are kept in order, and can be accessed by their position. Every element must be the type specified for that list. Element types can be any of the valid Data Types, from simple integers to combinations of classes and other lists. It's even possible to add a list of things to itself!

A list starts out with zero elements, and more can be added by referencing the first nonexistent element. The indexer starts at 1 for the beginning of the list (rather than 0 as in some programming languages).

Lists can contain node references; however, Associations may be a better choice in most circumstances. The problem with storing node references in a list occurs when the node is deleted. The list will still contain the reference, but using the reference will produce a Script Error.

Lists can be modified fairly easily via HeroScript commands, and with difficulty via the CLI.

Contents

Adding lists to lists

It is possible to add lists to lists as long as the elements are of the same type. When a list is added to an existing list, copies of the elements in the source list are added to the destination list.

If a list is added to itself, every element of the source list being added will have a copy in the destination list.

For example, if listA is (1, 2, 3, 4). If this list is inserted into the middle of itself, the result is: (1, 2, 1, 2, 3, 4, 3, 4).


HeroScript Commands for Lists

The following HeroScript commands exist for modifying a list:

ADD <FRONT | BACK> <item> TO <list> Add an item to the beginning or end of a list
CLEAR <listVar> [[KEEP | DESTROY]] Clear a list, with the option of deleting the associated nodes
INSERT <item | list> TO <list> AT <location> Insert an item or list into a list
REMOVE <list> AT <location> [[KEEP | DESTROY | COUNT]] Remove an item from a list
SORT <list> Sort the elements of a list


Creating a List

The syntax is LIST OF {type} such as LIST OF INTEGER or some other type. It is also possible to have lists of other types, such as LIST OF LIST OF INTEGER.

In HeroScript, to define a list newlist

  newlist as list of integer

Adding items to a list

A list starts out with zero elements. The first element of a list will be number 1.

add back 10 to newlist    // Adds the value 10 to the end of the list
add front 20 to newlist   // Adds the value 20 to the beginning of the list

or

  insert 27 to newlist at 2  // Insert the value 27 to position 2 in the list

Checking List Length

The number of elements in a list can be checked with the .length property:

   println("There are " + newList.length + " elements in newList.")

Sorting a List

The elements of a list can be sorted with the SORT command. Elements will be organized in ascending order, alphabetically or numerically as appropriate. The sort would be case-sensitive, so uppercase letters would be sorted before lowercase. It is not clear how strings that begin with spaces or punctuation would be treated.

  sort fruitList

Removing items from a list

  remove newlist at 3

remove newList at 2 count 6

Finding and removing a value from a list

foundAt as Integer
loop i from 1 to theList.length
  if (theList[i] = theValue)
    foundAt = i
    break
  .
.
if (foundAt > 0)
  remove theList at foundAt
.

Adding lists to a list

list1 as list of string
list2 as list of string
...
add back list1 to list2
insert list2 to list1 at 3
// using the same list is also acceptable
insert list1 to list1 at 3

Clearing / Destroying node references from a list

When an element is removed from a list of node references, or a list of node references is entirely cleared, it is possible to specify that this automatically deletes the associated node entirely. This is done with the KEEP or DESTROY arguments. If KEEP or DESTROY is not specified, the default is KEEP.

When dealing with lists that are of other datatypes, the KEEP/DESTROY arguments are not relevant.

clear listVar    
clear nodeList destroy  
 
remove listVar at 2
remove nodeList at 3 keep
 
remove nodeList at 5 destroy
 
remove nodeList at 5 count 4 keep
remove nodeList at 2 count 6 keep

List Manipulation via the CLI

Making changes to a list via the CLI (Command Line Interface) is cumbersome, and not all techniques that exist in HeroScript can be replicated via the CLI. What *can* be done is that the CLI can be used to define a field that is a list; however, data could not be added to the list until a node was defined that used that field. Then data could be added to the list with the "Modify Node" command, MN:

: CFD fruitlist, list of string  // Create Field Definition
: CCD listbasket , fruitlist     // Create Class Definition
: CNFC listbasket 1 on           // Creates node #2
: MN 2 ; fruitlist[1] = "apple"
: MN 2 ; fruitlist[2] = "orange"
: MN 2 ; fruitlist[3] = "banana"
: MN 2 ; fruitlist[4] = "kiwi"

There is not currently any way via the CLI to add elements to the beginning of a list, or to remove a list entry. The best that can be done is to clear or change an existing entry, or to add additional elements to the end of a list:

: MN 2 ; fruitlist[3] = ""
: MN 2 ; fruitlist[2] = "Valencia Orange"
: MN 2 ; fruitlist[5] = "watermelon"

In general, when dealing with lists, it is better to stick to HeroScript.

Lookup Lists

This is a field Data Type that correlates a key with a value. The underlying data structure is a hashmap. An analogy is that of a dictionary which can be used to look up specific entries.

The following are valid key (index) types:

Any type defined in the DOM is valid to be the value of the lookup list.

The LOOKUPLIST maintains a group of key/value pairs. For each value there is an associated key that is used to look up that value. For any given key in the list, there is exactly one value.


The syntax to define a lookup list is:

fruitlist as lookuplist indexed by integer of string    // define fruitlist as a lookup list
mountainlist as lookuplist indexed by string of string
 
mountainlist["a"]="Everest"
mountainlist["b"]="Shasta"
mountainlist["c"]="Mount Doom"
 
println(mountainlist["b"])    // Would print "Shasta"
 
 
favoritecolors as lookuplist indexed by string of string
 
favoritecolors["Elonka"] = "purple"
favoritecolors["Bryan"]="blue"
 
name as string="Elonka"                   
 
println(favoritecolors[name])   // Would print "purple"

When using a lookuplist, you may check and see if a particular key has a value via the has operator. It is important to note that if you attempt to access the value at a key, the key will be inserted into the map if it did not previously exist there with its value as the default (i.e. NONE, "", 0 etc). Using the has operator provides you with a means to avoid the accidental insertion of keys.

dumptrucklist as lookuplist indexed by string of string
 
dumptrucklist["JerrysTruck"] = "gravel"
 
if (dumptrucklist has "JerrysTruck")
  var contents = dumptrucklist["JerrysTruck"]
else
  // where did he go?
.

HAS

The HAS operator is used to determine whether or not a list has a specified key or not. This is necessary because simply referencing the key as in the example below will add it to the list.

mylookuplist as lookuplist indexed by string of string
if mylookuplist["blah"] = "something"  // if blah was not in mylookuplist, it is added here
  // do something
.

Use the HAS operator to test for the existance of an element in a lookuplist like so.

mylookuplist as lookuplist indexed by string of string
if mylookuplist HAS "blah"
  // do something
else
  // do something because blah is not in the lookuplist
.

To remove a key from a lookuplist:

REMOVE <key> FROM <lookuplist>

Examples:

if mylookuplist has "blah"
  remove "blah" from mylookuplist
.

foreach key in myLookupList
  if (someCondition == true)
    remove key from myLookupList
  .
.
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox