Collections for EasyLanguage

Introduction
The ELCollections library supports two kinds of collections: Lists and Maps. A List is an ordered list of values. Values can be pushed onto the front or back of the list, and they can be popped off the front or back. They can also be inserted or re oved at any position in the list. A value can be accessed by an inde! "like an array#, or by lookin$ at the front or back of the list. Lists can be %$rown& on de and by addin$ or insertin$ values. A Map associates keys and values. A key is a piece of data for which you want to store an associated value. 'or e!a ple, suppose you want to store the last closin$ price for each sy bol. (ou can put this infor ation in a ap, which can be represented conceptually like this:
CSCO -> 19.74 IBM -> 93.37 MSFT -> 29.77 ORCL -> 13.34

)n this case, the sy bol na e is the key, and the closin$ price is the value. Althou$h this e!a ple associates strin$s with nu bers, you can also associate nu bers with nu bers, nu bers with strin$s, and strin$s with strin$s. )n fact, you can even associate strin$s or nu bers with other collections. This is a powerful capability which will be e!plained in ore detail later. All of the collection functions use the followin$ na in$ convention:
ListX.Method(ID ...) or M !X".Method(ID ...)

where List or Map indicates the collection type X and Y indicate the type"s# of data in the collection: * "nu ber#, + "strin$#, or C "collection# Method indicates the action to perfor on the collection ID is the identifier of the ap or list )n the case of a List, X indicates the type of data in the list. )n the case of a Map, X indicates the key type, and Y indicates the value type.
Examples
Co#$t % List&.Co#$t('(i)eList)*

Gets the number of values in a list of numbers (PriceList)

+ ,#e1 % ListS.'#shB )-(S./0o,List1 2etS./0o,& /e)*

Pushes the symbol name onto the back of a list of strin!s ("ymbolList)
'(i)e % M !S&.2et('(i)eM !1 2etS./0o,& /e)*

Gets the price associated #ith the current symbol from a map (PriceMap) that associates strin!s #ith numbers
Valid Types

The followin$ collection types are valid: List*, List+, ListC, Map**, Map*+, Map*C, Map+*, Map++, and Map+C. MapC* and MapC+ are not valid types because a collection is not a valid key type.

Creating a Collection
There are two ways to create a collection: the *ew ethod and the +hare ethod. -oth of these ethods return a nu eric ). for the new collection. This ). ust be stored in a variable and passed to any functions that operate on the collection. The $e# ethod creates a collection that is visible only to the current study or strate$y. )t does not take any ar$u ents. The "hare ethod creates a collection that can be shared by ultiple studies or strate$ies. )t takes a sin$le ar$u ent, which is a uni/ue na e that identifies the collection. )f no collection with that na e e!ists, it is created0 otherwise, the ). of the e!istin$ collection is returned. *ote that a collection can only be shared within a sin$le application. Chartin$, 1adar+creen, and 2ption+tation are different applications, so a collection cannot be shared across the .
Examples
ListID % List&.&e3* 44 )(e tes ListID % ListS.&e3* 44 )(e tes M !ID % M !S&.&e3* 44 )(e tes M !ID % M !&S.&e3* 44 )(e tes ,ist o5 $#/0e(s ,ist o5 st(i$6s / ! o5 st(i$6s to $#/0e(s / ! o5 $#/0e(s to st(i$6s

44 )(e te sh (ed ,ist o5 $#/0e(s ) ,,ed 7'(i)es8 ListID % List&.Sh (e(7'(i)es8)* 44 )(e te sh (ed / ! o5 $#/0e(s->$#/0e(s ) ,,ed 7Dist(i0#tio$8 M !ID % M !&&.Sh (e(7Dist(i0#tio$8)*

)f a collection i$ht be used on any bar of a study "as is usually the case#, a $ood practice is to create the collection in the variable declaration, like this:
+ (s9 S./0o,List(ListS.&e3)1 DistM !(M !&&.Sh (e(7Dist(i0#tio$8))*

1e e ber that variables are initiali4ed on the first bar, before any other code is e!ecuted. 5hen the variable is initiali4ed, the e!pression inside the parentheses is evaluated and assi$ned to the variable. Thus, the declaration of +y bolList above causes a new list to be created "by evaluatin$ List+.*ew#, and the resultin$ List ). is assi$ned to the +y bolList variable. +ince this happens on the first bar, the list is available for all the bars of the chart or 1adar+creen, and its ). can be easily accessed via the +y bolList variable. Likewise, the declaration for .istMap above causes the %.istribution& ap to be created on the first bar "or to be shared if it already e!ists#, and the resultin$ Map ). is assi$ned to the .istMap variable so that it can be easily accessed anywhere in the study or strate$y.

List Functions
+ince EasyLan$ua$e re/uires functions to return a value, all of the ELCollections functions ust be assi$ned to a variable, even thou$h any of the perfor an operation rather than returnin$ a eanin$ful value. )n the followin$ descriptions, if the return value is irrelevant, the function will be assi$ned to Value,. )f the function returns a eanin$ful value, it will be assi$ned to a na ed variable such as MyValue. +o e of the followin$ functions re/uire an inde!. The inde! of the first value in a List is ,.
Value1 = ListX.Clear(ID);

Clears all the values fro

the list and frees the

e ory used by the .

Value1 = ListX.Resize(ID, NewSize);

+ets the si4e of the list to $e#"i%e. )f $e#"i%e is less than the current si4e, the e!cess values at the end of the list will be deleted. )f $e#"i%e is $reater than the current si4e, 4eroes or e pty strin$s will be added to the end of the list until it is the re/uested si4e. 6nlike the List7.Clear function, the List7.1esi4e function does not free all the e ory used by the list. )t will free any e ory used by the values the selves "such as strin$s#, but the space in the list will be reserved and reused if the list $rows a$ain. Thus, even thou$h List7.1esi4e")., 8# results in an e pty list, it is not e!actly e/uivalent to List7.Clear").#.
N = ListX.Count(ID);

1eturns the nu ber of values in the list.

MyValue = ListX. et(ID, In!e");

1eturns the value in the list at the position specified by Inde&.

Value1 = ListX.#ut(ID, In!e", Value);

9uts 'alue into the position specified by Inde&, replacin$ the old value.
MyValue = ListX.$ront(ID);

1eturns the value at the front of the list, i.e. the first value.

MyValue = ListX.%a&'(ID);

1eturns the value at the back of the list, i.e. the last value.
Value1 = ListX.Set%a&'(ID, Value);

+ets the back of the list to 'alue, replacin$ the old value.
Value1 = ListX.#us($ront(ID, Value);

Adds 'alue to the front of the list. This auto atically increases the si4e of the list by one.
Value1 = ListX.#us(%a&'(ID, Value);

Adds 'alue to the back of the list. This auto atically increases the si4e of the list by one.
Value1 = ListX.#o)$ront(ID);

1e oves the value at the front of the list. *ote that this function does not return the value. )f you need to know the value, call 'ront before callin$ 9op'ront.
Value1 = ListX.#o)%a&'(ID);

1e oves the value at the back of the list. *ote that this function does not return the value. )f you need to know the value, call -ack before callin$ 9op-ack.
Value1 = ListX.Insert(ID, In!e", Value);

)nserts 'alue at the position indicated by Inde&. All e!istin$ values startin$ with Inde& are shifted up. This auto atically increases the si4e of the list by one.
Value1 = ListX.Re*o+e(ID, In!e");

1e oves 'alue at the position indicated by Inde&. All values above Inde& are shifted down.
Value1 = ListX.Rewin!(ID);

9repares to step throu$h the values in the list usin$ the List7.*e!t function.
Continue = ListX.Ne"t(ID, Value);

;ets the ne!t value in the list. )f there are any re ainin$ values, the function sets 'alue to the ne!t value and returns true. 2therwise, the function returns false. +ee below for an e!a ple of usin$ this function to traverse a list.
Value1 = ListX.Co)y$ro*List(ID, ,t(erList, -))en!);

Copies the contents of (therList into the list. )f )ppend is true, the contents of (therList are appended to the end of the current list0 otherwise, they replace the contents of the current list. This function is not available for a ListC.
Value1 = ListX.Co)yMa).eys(ID, Ma)ID, -))en!);

Copies the keys fro the specified ap into the list "in sorted order#. )f )ppend is true, the keys are appended to the end of the current list0 otherwise, they replace the contents of the

<

current list. MapID ust be the ). of a ap with keys of the sa e type as the list "Map*C, Map**, or Map*+ for a List*0 Map+C, Map+*, or Map++ for a List+#. This function is not available for a ListC.
Value1 = ListX.Co)yMa)Values(ID, Ma)ID, -))en!);

Copies the values fro the specified ap into the list. )f )ppend is true, the values are appended to the end of the current list0 otherwise, they replace the contents of the current list. MapID ust be the ). of a ap with values of the sa e type as the list "Map** or Map+* for a List*0 Map*+ or Map++ for a List+#. This function is not available for a ListC.
Value1 = ListX.Swa)Contents(ID, ,t(erList);

+waps the contents of the list with (therList. This operation is perfor ed very /uickly by the ELCollections .LL = it takes a s all a ount of ti e no lon$er how bi$ the lists are. This is a fairly advanced function, but it is useful for solvin$ certain types of proble s efficiently. This function is not available for a ListC.
Value1 = ListX.Sort(ID, Re+erse);

+orts the list. )f 1everse is false, the list is sorted in ascendin$ order. )f 1everse is true, the list is sorted in descendin$ order. This function is not available for a ListC.
Value1 = ListX.Sort%yMa)(ID, SortMa), Re+erse);

+orts the list usin$ the associated values in "ortMap. 'or each ite in the list, this function looks up the associated value in "ortMap, and the function sorts the list ite s by the associated values "rather than by the ite values the selves#. )f *everse is true, the list is sorted in descendin$ order. +ee below for ore infor ation about this function. This function is not available for a ListC.
Value1 = ListX.Sort%y/Ma)s(ID, SortMa)1, Re+erse1, SortMa)/, Re+erse/);

+orts the list usin$ the associated values in "ortMap+ and "ortMap,. This function works like List7.+ort-yMap, but if two ite s in the list have the sa e associated values in "ortMap+, the function uses the associated values in "ortMap, to break the tie. *everse+ specifies the sort order for "ortMap+, and *everse, specifies the sort order for "ortMap,. This function is not available for a ListC.
Value1 = ListX.Sort%yNMa)s(ID, SortMa)s, Re+erse$la0s);

+orts the list usin$ the associated values in "ortMaps. This function is a $enerali4ation of List7.+ort-y3Maps to any nu ber of aps. "ortMaps is a list of the aps to use. )t will >

nor ally be a ListC, but it can also be a List* that holds the ).s of the aps. "This is useful if these aps are already owned by another collection.# *everse-la!s is a List* of nu eric fla$s which specify the sort order for each correspondin$ ap. A value of 8 in this list indicates ascendin$ order, and a value of , indicates descendin$ order. (ou ay also pass a 4ero for this ar$u ent instead of a List*0 this tells the function to use ascendin$ order for all the aps. 5hen two ite s in the list have the sa e associated values in the first sort ap, the function tries to use the associated values in the second sort ap to break the tie. )f these associated values are also the sa e, the function tries to use the third sort ap to break the tie, and so on. This function is not available for a ListC.
Sorte! = ListX.IsSorte!(ID);

1eturns true if the list is known to be sorted, which is the case when the list is e pty, when it has ?ust been sorted by List7.+ort, and when all odifications to the list after either of these two conditions have kept the list sorted. This function is not available for a ListC.
In!e" = ListX.InsertSorte!(ID, Value);

)nserts Value into the correct location in a sorted list in order to keep it sorted. The function will raise a runti e error if the list is not already sorted. The function returns the inde! where Value was inserted. This function is not available for a ListC.
$oun! = ListX.Loo'u)(ID, Value, In!e",ut);

9erfor s a fast search for Value in a sorted list. The function will raise a runti e error if the list is not sorted. )f Value is in the list, the function returns true and sets )nde!2ut to the inde! of Value. )f Value is not in the list, the function returns false and sets )nde!2ut to the inde! where Value should be inserted to keep the list in sorted order. This function is not available for a ListC.
In!e" = ListX.$in!(ID, Value);

9erfor s a linear search for the first occurrence of 'alue in a list. )f 'alue is found, the function returns its inde!0 otherwise, the function returns 4ero. 6nlike List7.Lookup, this function does not re/uired the list to be sorted. ")f you know that the list is sorted, you should use List7.Lookup instead, since it is uch faster.# This function is not available for a ListC.

Traversing a List with Rewind and Next

(ou can step throu$h all the values in a list usin$ the 1ewind and *e!t functions:
+ ,#e1 % List&.Re3i$d(ID)* 3hi,e List&.&e:t(ID1 &#/0e() 0e6i$ 44 do so/ethi$6 3ith &#/0e( e$d*

(ou can also step throu$h a list usin$ a for loop:

5o( I$de: % 1 to List&.Co#$t(ID) 0e6i$ &#/0e( % List&.2et(ID1 I$de:)* 44 do so/ethi$6 3ith &#/0e( e$d*

The 1ewindA*e!t techni/ue is provided for consistency with aps. A ap can be traversed with 1ewindA*e!t but not with a for loop "since aps are accessed by arbitrary keys rather than by an inde!#.
orting !y a "ap

The List7.+ort-yMap function is a very powerful function, but it is easier to understand with an e!a ple. +uppose you have a list called +y bolList:
S./0o,List9 CSCO1 IBM1 MSFT1 ORCL

+uppose you also have a

CSCO -> 19.74 IBM -> 93.37 MSFT -> 29.77 ORCL -> 13.34

ap called 9riceMap:

*ow suppose you want to sort the +y bolList by the associated prices rather than by the sy bol na es. (ou can do this with +ort-yMap:
+ ,#e1 % ListS.So(tB.M !(S./0o,List1 '(i)eM !1 5 ,se)*

The +y bolList will now have the followin$ order:

S./0o,List9 ORCL1 CSCO1 MSFT1 IBM

(ou can sort by ore than one ap usin$ the List7.+ort-y3Maps or List7.+ort-y*Maps functions. )f the associated values in the first ap are the sa e, these functions use one or ore additional aps to break the tie. +ee the descriptions of these functions above for details about how to call the .

"ap Functions
Value1 = Ma)X1.Clear(ID);

Clears all the keyCvalue pairs fro

N = Ma)X1.Count(ID);

the

ap and frees the ap.

e ory used by the .

1eturns the nu ber of keyCvalue pairs in the

MyValue = Ma)X1. et(ID, .ey);

1eturns the value associated with .ey. 1e e ber that the key and value types depend on the ap type. 'or e!a ple, for a Map+*, .ey should be a strin$ "+# and My'alue should be a nu ber "*#. 'or a Map*+, .ey should be nu ber "*# and My'alue should be a strin$ "+#. There are two ap types that can hold other collections: Map*C and Map+C. +ince collections are represented by nu eric ).s, these ap types re/uired a nu eric variable for My'alue.
Value1 = Ma)X1.#ut(ID, .ey, Value);

Associates 'alue with .ey. )f .ey is already in the ap, the old associated value is replaced with 'alue. )f .ey is not in the ap, the .ey/'alue pair is added to the ap.
Value1 = Ma)X1.Re*o+e(ID, .ey);

1e oves the keyCvalue pair for .ey fro

Is2(ere = Ma)X1.3"ists(ID, .ey);

the

ap. ap.

1eturns true if .ey is in the

ap and false if it is not in the

Value1 = Ma)X1.Rewin!(ID);

9repares to step throu$h the keyCvalue pairs in the

Continue = Ma)X1.Ne"t(ID, .ey, Value);

ap usin$ the Map7(.*e!t function.

;ets the ne!t keyCvalue pair in the ap. )f there are any re ainin$ pairs, the function sets .ey to the ne!t key and 'alue to its associated value and returns true. 2therwise, the function returns false. +ee below for an e!a ple of usin$ this function to traverse a ap.
Traversing a "ap with Rewind and Next

(ou can step throu$h all the keyCvalue pairs in a

ap usin$ the 1ewind and *e!t functions:

+ ,#e1 % M !S&.Re3i$d('(i)eM !)* 3hi,e M !S&.&e:t('(i)eM !1 S./1 '(i)e) 0e6i$ 44 do so/ethi$6 3ith S./ $d '(i)e e$d*

Cleaning #p Collections
*or ally you donEt have to worry about cleanin$ up collections yourself: the ELCollections utility will do it for you auto atically when a study or strate$y is unloaded. Fowever, there ay be ti es when you want to create a te porary collection, do so e work with it, and then delete it to save e ory. (ou can do this with the 1elease function:
+ ,#e1 % ListX.Re,e se(ID) or + ,#e1 % M !X".Re,e se(ID)

)f you release a local collection "created with *ew#, it will be deleted i ediately. )f you release a shared collection "created with +hare#, it will be deleted only when it has been released by all studies and strate$ies that use it. FereEs a function called ;et+y bol+et that creates a shared ap of sy bols by readin$ the sy bols fro a te!t file. "1eadin$ fro a file is discussed below.# )n this case, the values associated with the sy bols are not i portant = the ap is ?ust used to see whether the sy bol is present usin$ the Map7(.E!ists function. This is uch faster than searchin$ throu$h the list every ti e. +ince the list is only needed once in order to build the ap, it is released as soon as we are done with it:
I$!#ts9 Set& /e(St(i$6Si/!,e)1 Fi,e& /e(St(i$6Si/!,e)* + (s9 S./0o,Set(M !S&.Sh (e(Set& /e))1 44 )(e te / ! o( sh (e it i5 it e:ists Te/!List(;)1 S./(<<)* 44 O$,. (e d the 5i,e the 5i(st ti/e1 i.e. 3he$ the / ! is e/!t. i5 M !S&.Co#$t(S./0o,Set) % ; the$ 0e6i$ Te/!List % ListS.&e3* 44 )(e te te/!o( (. ,ist o5 st(i$6s + ,#e1 % ListS.Re dFi,e(Te/!List1 Fi,e& /e)* 44 (e d s./0o,s 5(o/ 5i,e + ,#e1 % ListS.Re3i$d(Te/!List)* 44 st (t 5(o/ 0e6i$$i$6 o5 ,ist 3hi,e ListS.&e:t(Te/!List1 S./) 0e6i$ 44 ,oo! th(o#6h the s./0o,s + ,#e1 % M !S&.'#t(S./0o,Set1 S./1 ;)* 44 !#t S./->; ! i( i$ / ! e$d* + ,#e1 % ListS.Re,e se(Te/!List)* 44 de,ete the te/!o( (. ,ist e$d* 2etS./0o,Set % S./0o,Set* 44 (et#($ the / ! o5 S./0o,->; ! i(s

*ote that this function ?ust stores 4ero in the ap for every sy bol. )n this case, we are not interested in the values which are paired with the sy bols0 the ap si ply provides a fast way to see if a sy bol is present. Maps are desi$ned to provide fast access to arbitrary keys, so lookin$ up a sy bol in a ap is uch faster than searchin$ throu$h a list of strin$s. 2nce you have created a %sy bol set& with the ;et+y bol+et function, you can ?ust use Map+*.E!ists to deter ine whether a sy bol is in the set:
S./0o,Set % 2etS./0o,Set(7= s.ToBo((o381 7C9>Te/!>=B.t:t8)*

= s.ToBo((o3 % M !S&.=:ists(S./0o,Set1 2etS./0o,& /e)*

The ;et+y bol+et function de onstrates a $ood use for the 1elease function. The function only uses the list once "when the ap is populated with data#, so it akes sense to delete the list when the function is done with it. )f you want to use a list or ap on ore than one bar, but you donEt want to save the values across bars, a better solution is to call List7.Clear or Map7(.Clear after processin$ the collection. This clears all the values, but the collection is still available to use on subse/uent bars. This approach is uch ore efficient that creatin$ the collection on every bar. The $eneral rule of thu b is this: if you only need a collection once, you can 1elease it when you are done with it "althou$h you donEt have to#. )f you want to reCuse a collection without savin$ the values fro bar to bar, call Clear when you are done with it.

Collections of Collections
)t is possible to create a collection that contains other collections. 'or e!a ple, you can create a Map of Lists, a Map of Maps, a List of Maps, or a List of Lists. This allows you to create sophisticated data structures to solve all kinds of proble s. Fere is an e!a ple of a Map of Lists. The keys in the ap are the dateAti e of each bar. The values in the lists are the open, hi$h, low, and close. Thus, the ap represents a series of price bars:
72;;441;4;1 ;?3@8 -> (1;.@;1 1;.?@1 1;.4;1 1;.?;) 72;;441;4;1 ;?4;8 -> (1;.@@1 1;.?;1 1;.@;1 1;.@A) 72;;441;4;1 ;?4@8 -> (1;.?21 1;.?71 1;.@31 1;.?@)

(ou could also represent this as a Map of Maps:

72;;441;4;1 ;?3@8 -> (O!e$->1;.@;1 Bi6h->1;.?@1 Lo3->1;.4;1 C,ose->1;.?;) 72;;441;4;1 ;?4;8 -> (O!e$->1;.@@1 Bi6h->1;.?;1 Lo3->1;.@;1 C,ose->1;.@A) 72;;441;4;1 ;?4@8 -> (O!e$->1;.?21 Bi6h->1;.?71 Lo3->1;.@31 C,ose->1;.?@)

Note: Heep in ind that a ap is a collection of keyCvalue pairs. )n each set of parentheses above, there are four keyCvalue pairs, and to$ether they co prise a ap. Thus, the three lines shown above would constitute a sin$le % aster& ap containin$ three subC aps. .onEt be confused because the pairs in the % aster& ap are shown in vertical se/uence while the pairs in the three subC aps are shown in hori4ontal se/uence. )t doesnEt atter whether we $roup our pairs vertically or hori4ontally. %9airs is pairsI& To create a list of collections, use ListC.*ew or ListC.+hare. To create a ap of collections, use Map+C.*ew, Map+C.+hare, Map*C.*ew, or Map*C.+hare. ap or list, you can add collections to it usin$ the *ew ethod.

2nce you have created such a

Note: .o not use the +hare ethod to create the collections which you add to a ap or list. ELCollections will raise a runti e error if you try to add a shared collection to a collection. ,8

Fere is how you

i$ht create the

ap of lists shown above:

+ (s9 M !ID(M !SC.&e3)1 ListID(;)* ListID + ,#e1 + ,#e1 + ,#e1 + ,#e1 + ,#e1 ListID + ,#e1 + ,#e1 + ,#e1 + ,#e1 + ,#e1 ListID + ,#e1 + ,#e1 + ,#e1 + ,#e1 + ,#e1 % % % % % % % % % % % % % % % % % % List&.&e3* List&.'#shB List&.'#shB List&.'#shB List&.'#shB M !SC.'#t(M List&.&e3* List&.'#shB List&.'#shB List&.'#shB List&.'#shB M !SC.'#t(M List&.&e3* List&.'#shB List&.'#shB List&.'#shB List&.'#shB M !SC.'#t(M )-(ListID1 1;.@;)* )-(ListID1 1;.?@)* )-(ListID1 1;.4;)* )-(ListID1 1;.?;)* !ID1 72;;441;4;1 ;?3@81 ListID)* 44

dd ,ist to / !

)-(ListID1 1;.@@)* )-(ListID1 1;.?;)* )-(ListID1 1;.@;)* )-(ListID1 1;.@A)* !ID1 72;;441;4;1 ;?4;81 ListID)* 44

dd ,ist to / !

)-(ListID1 1;.?2)* )-(ListID1 1;.?7)* )-(ListID1 1;.@3)* )-(ListID1 1;.?@)* !ID1 72;;441;4;1 ;?4@81 ListID)* 44

dd ,ist to / !

2f course, itEs usually ore useful to build such a ap al$orith ically rather than anually. The followin$ code will populate a shared ap of lists with price bars fro a chart. )t assu es that we have a -ar.ateTi e function that returns dateAti e strin$s like those above:
+ (s9 M !ID(M !SC.Sh (e(2etS./0o,& /e C 7DB (s8))1 ListID(;)* 44 This )ode (#$s o$ 44 o5 OBLC E ,#es to ListID % List&.&e3* + ,#e1 % List&.'#shB + ,#e1 % List&.'#shB + ,#e1 % List&.'#shB + ,#e1 % List&.'#shB + ,#e1 % M !SC.'#t(M eEe(. 0 (1 so it 3i,, the / ! o$ eEe(. 0 (. dd $e3 ,ist

)-(ListID1 O!e$)* )-(ListID1 Bi6h)* )-(ListID1 Lo3)* )-(ListID1 C,ose)* !ID1 B (D teTi/e1 ListID)* 44

dd ,ist to / !

'inally, the followin$ code will populate a shared

ap of

aps with price bars:

+ (s9 M !ID(M !SC.Sh (e(2etS./0o,& /e C 7DB (M !8))1 '(i)eB ((;)* 44 This )ode (#$s o$ eEe(. 0 (1 so it 3i,, 44 o5 OBLC E ,#es to the / ! o$ eEe(. 0 (. '(i)eB ( % M !S&.&e3* dd $e3 / !

,,

+ + + + +

,#e1 ,#e1 ,#e1 ,#e1 ,#e1

% % % % %

M M M M M

!S&.'#t('(i)eB !S&.'#t('(i)eB !S&.'#t('(i)eB !S&.'#t('(i)eB !SC.'#t(M !ID1

(1 7O!e$81 O!e$)* (1 7Bi6h81 Bi6h)* (1 7Lo381 Lo3)* (1 7C,ose81 C,ose)* B (D teTi/e1 '(i)eB ()* 44

dd '(i)eB ( to / !

To access the hi$h fro

a specific bar in the

ap of lists, you could use the followin$ code:

+ (s9 M !ID(M !SC.Sh (e(2etS./0o,& /e C 7DB (s8))1 ListID(;)* ListID % M !SC.2et(M !ID1 72;;441;4;1 ;?4;8)* '(i$t(7Bi6h % 81 List&.2et(ListID1 2))* 44 1-4 % OBLC1 !e( ,ist , .o#t

To access the hi$h fro

a specific bar in the

ap of

aps, you could use the followin$ code:

+ (s9 M !ID(M !SC.Sh (e(2etS./0o,& /e C 7DB (M !8))1 '(i)eB ((;)* '(i)eB ( % M !SC.2et(M !ID1 72;;441;4;1 ;?4;8)* '(i$t(7Bi6h % 81 M !S&.2et('(i)eB (1 7Bi6h8))*

)n su

ary, here are the $uidelines for usin$ collections of collections:

,. Create the collection with one of the followin$ keywords: ListC.*ew, ListC.+hare, Map+C.*ew, Map+C.+hare, Map*C.*ew, or Map*C.+hare. 3. To add a collection to the ap or list, create the collection with one of the *ew functions, and then add it to the ap or list in the usual way "e.$. 9ut or 9ush-ack#. :. To access a collection within a ap or list, use one of the usual ethods "e.$. ;et or -ack# to retrieve the Collection ). into a variable. Then pass that ). to a collection function to perfor the desired operation on the subCcollection.

Type Chec$ing
All collections have a %type& that is specified when you create the collection with *ew or +hare. 'or e!a ple, if you create a collection with Map+*.*ew, then that collection has a type of %Map+*& = a ap that associates strin$s with nu bers. )f you create a collection with Map+C.+hare, then that collection has a type of %Map+C& = a ap that associates strin$s with collections. 2nce you have created a collection of a specific type, you ust always use the correct type prefi! when accessin$ that collection. )f you donEt, the ELCollections utility will issue a runti e error which will appear in the Trade+tation Events Lo$. 'or e!a ple, if you create a list usin$ List*.*ew, then you ust use List*.;et to $et a value fro that list. )f you atte pt to use List+.;et instead, it will tri$$er a runti e error essa$e. ,3

)f you have the ). of a collection, you can find out the type of the collection by callin$ ELC.CollectionType").#. This returns a strin$ that describes the collection type. 'or e!a ple:
+ (s9 Fi(stID(List&.&e3)1 Se)o$dID(M !SC.&e3)1 T.!e1(78)1 T.!e2(78)* T.!e1 % =LC.Co,,e)tio$T.!e(Fi(stID)* 44 (et#($s 7List&8 T.!e2 % =LC.Co,,e)tio$T.!e(Se)o$dID)* 44 (et#($s 7M !SC8

(ou donEt nor ally need to use the ELC.CollectionType function, since you have usually created the collection in your code and therefore already know its type. Fowever, this function can be useful if you have loaded a collection of collections fro a file "see below#, and you need to find out the types of the subCcollections.

File %perations
There are a nu ber of functions available which allow you to read a collection fro write it to a te!t file. a te!t file or

These functions are very useful, but it should be stressed that they donEt allow you to read and write every kind of collection. The variety of possible collection structures is virtually unli ited "since you can create collections of collections#, so the ELCollections utility doesnEt atte pt to support the all. )nstead, it allows you to read and write the ost co on structures, includin$ certain for s of a ap of lists or a list of lists. Fere is a description of the file functions, alon$ with the supported file for at for each function.
Value1 = ListN.Rea!$ile(ID, $ileNa*e);

1eads a list of nu bers fro a te!t file into the List specified by ).. The file should contain one nu ber on each line, like this:
17.3 1A.4 2;.7@ 1@

Value1 = ListS.Rea!$ile(ID, $ileNa*e);

1eads a list of strin$s fro a te!t file into the List specified by ).. The file should contain one strin$ on each line, like this:
CSCO IBM MSFT ORCL

,:

Value1 = ListC.Rea!$ile(ID, $ileNa*e);

1eads a co a deli ited te!t file into the List specified by ).. The data is represented as a list of lists, where each colu n in the te!t file is i ported as a subClist. 'or e!a ple, suppose you have the followin$ te!t file:
Foh$1&e3 "o(-131 F $e1F,o(id 12@ C (,os1O(e6o$119 Leti)i 1C ,i5o($i 142

This would be read into the followin$ list of lists "where the nu ber on the left represents the inde! in the outer list#:
19 Foh$1 F $e1 C (,os1 Leti)i 29 &e3 "o(-1 F,o(id 1 O(e6o$1 C ,i5o($i 39 311 2@1 191 42

The first and second subClists would be of type List+, since the first and second colu ns in the te!t file contain strin$s. The third subClist would be of type Lis*, since the third colu n in the te!t file contains nu bers. The 1ead'ile function auto atically deter ines the type of list based on the first 38 values in the colu n.
Value1 = Ma)NN.Rea!$ile(ID, $ileNa*e);

1eads a list of keyCvalue pairs fro a te!t file into the Map** specified by ).. Each line of the file should contain a nu eric key and a nu eric value, separated by a co a:
3.71@.2 4.?17.1 @.31A.2

Value1 = Ma)NS.Rea!$ile(ID, $ileNa*e);

1eads a list of keyCvalue pairs fro a te!t file into the Map*+ specified by ).. Each line of the file should contain a nu eric key and a strin$ value, separated by a co a:
3;12ood 1;1B d 2;1I$di55e(e$t

Value1 = Ma)SN.Rea!$ile(ID, $ileNa*e);

1eads a list of keyCvalue pairs fro a te!t file into the Map+* specified by ).. Each line of the file should contain a strin$ key and a nu eric value, separated by a co a:
2ood13; B d11; I$di55e(e$t12;

Value1 = Ma)SS.Rea!$ile(ID, $ileNa*e);

1eads a list of keyCvalue pairs fro a te!t file into the Map++ specified by ).. Each line of the file should contain a strin$ key and a strin$ value, separated by a co a: ,<

CSCO1Lo$6 ORCL1Sho(t MSFT1F, t

Value1 = Ma)SC.Rea!$ile(ID, $ileNa*e);

1eads a co aCdeli ited te!t file into the Map+C specified by ).. The first line of the te!t file should contain colu n headin$s. The data is represented as a ap of lists, where each colu n headin$ in the te!t file is a key, and the rest of the colu n is i ported as a list associated with that key. 'or e!a ple, suppose you have the followin$ te!t file:
& /e1St te1G6e Foh$1&e3 "o(-131 F $e1F,o(id 12@ C (,os1O(e6o$119 Leti)i 1C ,i5o($i 142

This would be read into the followin$

ap of lists:

& /e -> (Foh$1 F $e1 C (,os1 Leti)i ) St te -> (&e3 "o(-1 F,o(id 1 O(e6o$1 C ,i5o($i ) G6e -> (311 2@1 191 42)

The *a e and +tate subClists would be of type List+, since these colu ns in the te!t file contain strin$s. The A$e subClist would be of type Lis*, since this colu n in the te!t file contains nu bers. The 1ead'ile function auto atically deter ines the type of list based on the first 38 values in the colu n.
Value1 = ListN.4rite$ile(ID, $ileNa*e);

5rites the specified list of nu bers to a te!t file. The file is written in the sa e for at used by List*.1ead'ile.
Value1 = ListS.4rite$ile(ID, $ileNa*e);

5rites the specified list of strin$s to a te!t file. The file is written in the sa e for at used by List+.1ead'ile.
Value1 = ListC.4rite$ile(ID, $ileNa*e);

5rites the specified list of lists to a co aCdeli ited te!t file. The file is written in the sa e for at used by ListC.1ead'ile. )n order to write the list, it ust eet the followin$ conditions: The list contains only nu eric lists "List*# or strin$ lists "List+#. All of the subClists contain the sa e nu ber of values.
Value1 = Ma)NN.4rite$ile(ID, $ileNa*e);

5rites the specified Map** to a te!t file. The file is written in the sa e for at used by Map**.1ead'ile.

,>

Value1 = Ma)NS.4rite$ile(ID, $ileNa*e);

5rites the specified Map*+ to a te!t file. The file is written in the sa e for at used by Map*+.1ead'ile.
Value1 = Ma)SN.4rite$ile(ID, $ileNa*e);

5rites the specified Map+* to a te!t file. The file is written in the sa e for at used by Map+*.1ead'ile.
Value1 = Ma)SS.4rite$ile(ID, $ileNa*e);

5rites the specified Map++ to a te!t file. The file is written in the sa e for at used by Map++.1ead'ile.
Value1 = Ma)SC.4rite$ile(ID, $ileNa*e);

5rites the specified ap of lists to a co aCdeli ited te!t file. The file is written in the sa e for at used by Map+C.1ead'ile. )n order to write the ap, it ust eet the followin$ conditions: The ap contains only nu eric lists "List*# or strin$ lists "List+#.

All of the subClists contain the sa e nu ber of values.

Value1 = Ma)SC.SetColu*n,r!er(ID, ColList);

(ou can call this function i ediately before callin$ Map+C.5rite'ile in order to set the order of the colu ns in the output file. ")f you do not call this function first, the colu ns will be written in the alphabetical order of the keys.# 0olList should be the ). of a List+ which contains the ap keys in the desired colu n order. )t is not necessary to include all of the ap keys in the colu n list. Any keys that are included will be written first in the specified order, and any re ainin$ keys will be written as additional colu ns in alphabetical order. )f the colu n list contains any na e that is not a valid key in the ap, then the colu n list is i$nored and the colu ns are written in the default alphabetical order. *ote that it is fine to release the colu n list "via List+.1elease# i Map+C.+etColu n2rder. ediately after callin$

Value1 = Ma)SC.%uil!RowMa)(ID, RowMa)ID, Colu*nNa*e);

This is not strictly a file function, but it was desi$ned to work in con?unction with Map+C.1ead'ile. 2nce a file has been read into a ap of lists, it ay be desirable to use one of the colu ns "lists# as an inde! into the rows. 'or e!a ple, once we have read the sa ple file above, we i$ht want to use the %*a e& colu n as an inde!, so that we can /uickly look up a row by na e. The -uild1owMap function followin$ ar$u ents: akes it easy to build a ap of any colu n. Just pass the

,@

 The ). of the

ap which was read with Map+C.1ead'ile.

A 1owMap)., which is the ). for a Map+* or Map** that will ap the colu n values to the row nu bers. )f the inde! colu n contains strin$s, you should pass a Map+*. )f the inde! colu n contains nu bers, you should pass a Map**. The na e of the colu n that you want to use as an inde!. 2nce the row ap has been built, you can look up the row nu ber for any value in the inde! colu n. Then you can use this row nu ber to retrieve values for the sa e row fro other colu ns. )f you read in a lar$e file, this is uch faster than a linear search throu$h the colu n for the desired value. FereEs an e!a ple for the sa ple file above:
+ (s9 'eo!,eM !(M !SC.&e3)1 Ro3M !(M !S&.&e3)1 Co,List(;)1 Ro3&#/(;)* + ,#e1 % M !SC.Re dFi,e('eo!,eM !1 7C9>Te/!>'eo!,e.t:t8)* + ,#e1 % M !SC.B#i,dRo3M !('eo!,eM !1 Ro3M !1 7& /e8)* Co,List % M !SC.2et('eo!,eM !1 7G6e8)* 44 6et the G6e )o,#/$ Ro3&#/ % M !S&.2et(Ro3M !1 7C (,os8)* 44 6et the (o3 5o( C (,os '(i$t(List&.2et(Co,List1 Ro3&#/))* 44 !(i$t the 6e o5 C (,os

Value1 = ListS.Rea!5ea!in0s(ID, $ileNa*e);

1eads the first line of a tabular te!t file "in C+V for at#, parses the line into colu n headin$s, and populates the list with the headin$s. This function is useful if you want to re e ber the colu n order of a tabular te!t file so that you can later write the data back with the sa e order. 'or e!a ple, the followin$ code reads a te!t file into a Map+C and saves the colu n headin$s in a List+. Later on, it uses the List+ to set the colu n order, and then it writes the Map+C to another te!t file. This ensures that the new te!t file will have the sa e colu n order as the ori$inal te!t file. "1e e ber that without the Map+C.+etColu n2rder call, the colu ns will be written in alphabetical order.#
+ (s9 I$!#tFi,e(7C9>Te/!>D t 1.)sE8)1 O#t!#tFi,e(7C9>Te/!>D t 2.)sE8)1 M.M !(M !SC.&e3)1 Co,#/$Be di$6s(ListS.&e3)* 44 Re d the 5i,e $d the )o,#/$ he di$6s + ,#e1 % M !SC.Re dFi,e(M.M !1 I$!#tFi,e)* + ,#e1 % ListS.Re dBe di$6s(Co,#/$Be di$6s1 I$!#tFi,e)*

,B

44 '(o)ess M.M ! i$ so/e 3 . ... 44 H(ite the / ! to 5i,e #si$6 the s /e )o,#/$ o(de( + ,#e1 % M !SC.SetCo,#/$O(de((M.M !1 Co,#/$Be di$6s)* + ,#e1 % M !SC.H(iteFi,e(M.M !1 O#t!#tFi,e)*

Value1 = ListS.$in!$iles(ID, $ile#attern);

9opulates a list with all the file na es that atch the specified file pattern. (ou can use this function to perfor a directory search. The pattern should use the standard .2+ wildcards K and L. 'or e!a ple, the followin$ code fills the .ata'iles list with the na es of all the files in the C:MTradin$ directory that atch the .ataK.csv pattern:
+ (s9 D t Fi,es(ListS.&e3)* + ,#e1 % ListS.Fi$dFi,es(D t Fi,es1 7C9>T( di$6>D t I.)sE8)*

*ote that the file na es which are added to the list will not include the directory path = they only include the na e and file e!tension "e.$. %.ata,8C33C8<.csv&#.

peciali&ed Functions
This section describes functions which are speciali4ed for certain list types.
ListN Functions Result = ListN.Su**ation(ID, $ro*In!e", 2oIn!e");

1eturns the su

of the values between -romInde& and 1oInde& in the list.

Result = ListN.-+era0e(ID, $ro*In!e", 2oIn!e");

1eturns the avera$e of the values between -romInde& and 1oInde& in the list.
Result = ListN.Varian&e(ID, $ro*In!e", 2oIn!e");

1eturns the population variance of the values between -romInde& and 1oInde& in the list.
Result = ListN.St!De+(ID, $ro*In!e", 2oIn!e");

1eturns the population standard deviation of the values between -romInde& and 1oInde& in the list.
Result = ListN.Ma"i*u*(ID, $ro*In!e", 2oIn!e");

1eturns the 1eturns the

a!i u ini u

of the values between -romInde& and 1oInde& in the list. of the values between -romInde& and 1oInde& in the list.

Result = ListN.Mini*u*(ID, $ro*In!e", 2oIn!e");

,D

Result = ListN.#er&entile(ID, $ro*In!e", 2oIn!e", #&tRan');

1eturns the specified percentile of the values between -romInde& and 1oInde& in the list. Pct*ank should be a value between 8 and ,. 'or e!a ple, use 8.D to calculate the D8th percentile.
Result = ListN.Re0ression(ID, $ro*In!e", 2oIn!e", Slo)e, Inter&e)t);

9erfor s a linear re$ression on the values between -romInde& and 1oInde& in the list, and returns the results in the "lope and Intercept ar$u ents. The intercept is considered to fall at the be$innin$ of the ran$e "correspondin$ to -romInde&#.
List Functions Value1 = ListS.#arseStrin0(ID, Sour&eStr, Deli*iter);

9arses a source strin$ usin$ the specified deli iter and populates a list with the resultin$ substrin$s. This allows you to use a strin$ input to an indicator as a convenient way to specify a short list of strin$s. 'or e!a ple:
I$!#ts9 S./0o,s(7CSCO1IBM1MSFT1ORCL8)* + (s9 S./List(ListS.&e3)* + ,#e1 % ListS.' (seSt(i$6(S./List1 S./0o,s1 718)* 44 Do so/ethi$6 3ith S./List ...

"ap C Functions Value1 = Ma)SC.Sort%yCol(ID, .eyColNa*e, Re+erse);

+orts the %rows& in a ap by the values in one of the %colu ns&. This function can be used to sort a ap of lists, where each key in the ap represents a colu n headin$ and the associated list represents the values in that colu n. All of the lists ust contain the sa e nu ber of ite s. "This is the sa e for at used by Map+C.1ead'ile and Map+C.5rite'ile. +ee the description of Map+C.5rite'ile above for an e!a ple of this for at.# This function perfor s the e/uivalent of sortin$ a data table in a spreadsheet by one of its colu ns. .ey0ol$ame is the na e of the colu n that you want to sort by. )f *everse is true, the rows will be sorted in descendin$ order0 otherwise, they will be sorted in ascendin$ order. )f the ap contains any collections which are not lists, they will si ply be i$nored, and all of the lists will be sorted by the key colu n.

,G

Value1 = Ma)SC.Sort%y/Cols(ID, .eyColNa*e1, Re+erse1, .eyColNa*e/, Re+erse/);

This function sorts the %rows& in a ap by the values in two of its %colu ns&. )t is si ilar to Map+C.+ort-yCol, but if two values in the first key colu n are the sa e, the function uses the values in the second key colu n to break the tie.
Value1 = Ma)SC.Sort%yNCols(ID, .eyColNa*es, Re+erse$la0s);

This function is a $enerali4ation of Map+C.+ort-y3Cols to any nu ber of key colu ns. .ey0ol$ames is a List+ containin$ the na es of the key colu ns. *everse-la!s is a List* of nu eric fla$s which specify the sort order for each correspondin$ colu n. A value of 8 in this list indicates ascendin$ order, and a value of , indicates descendin$ order. (ou ay also pass a 4ero for this ar$u ent instead of a List*0 this tells the function to use ascendin$ order for all the colu ns. 5hen two rows have the sa e value in the first key colu n, the function tries to use the values in the second key colu n to break the tie. )f these values are also the sa e, the function tries to use the third key colu n to break the tie, and so on.

#tility Functions
The ELCollections library also provides so e $eneral utility functions. All of these functions are na ed with a prefi! of %ELC.&.
C(arStr = 3LC.-s&ii2oStr(-s&iiCo!e);

Converts the specified A+C)) code to a strin$. This is useful for creatin$ characters that cannot nor ally be included in EasyLan$ua$e strin$s. 'or e!a ple, you can use ELC.AsciiTo+tr"G# to create a tab character and ELC.AsciiTo+tr":<# to create a /uote character.
2y)eStr = 3LC.Colle&tion2y)e(ID);

1eturns a strin$ that describes the type of the collection represented by ID. 'or e!a ple, if the collection is a List*, the function will return %List*&.
Value1 = 3LC.Dire&toryCreate(Dire&tory#at();

Creates the specified directory. (ou ust specify the full directory path. 'or e!a ple, the followin$ code creates the directory C:MTe pM.ata:
+ ,#e1 % =LC.Di(e)to(.C(e te(7C9>Te/!>D t 8)*

Value1 = 3LC.Dire&toryDelete(Dire&tory#at();

.eletes the specified directory. The directory ust be e pty, and you ust specify the full directory path. 'or e!a ple, the followin$ code deletes the directory C:MTe pM.ata:
+ ,#e1 % =LC.Di(e)to(.De,ete(7C9>Te/!>D t 8)*

38

Value1 = 3LC.#at(3"ists($ile#at();

1eturns true if the specified file path e!ists. -ilePath can be either a file or a directory. 'or e!a ple, the followin$ code prints a essa$e if a sy bol file e!ists:
i5 =LC.' th=:ists(7C9>Te/!>S./0o,s.t:t8) the$ '(i$t(7Fo#$d s./0o, 5i,e8)*

The followin$ code prints a

essa$e if the specified directory e!ists:

di(e)to(. 5o#$d8)*

i5 =LC.' th=:ists(7C9>Te/!>D t 8) the$ '(i$t(7D t

Value1 = 3LC.Raise3rror(-))Na*e, 3rrorMessa0e);

1aises a runti e error. )pp$ame should be a short strin$ that describes your application. 2rrorMessa!e is a essa$e describin$ the proble . These strin$s will appear in the Trade+tation Event Lo$. )t is stron$ly reco ended that you use ELC.1aiseError rather than 1aise1unti eError in any code that uses the ELCollections library. The 1aise1unti eError can cause various proble s, includin$ loss of the ori$inal error essa$e. This can ake it very difficult to debu$ your code.

3,