index<--

EVE Collections

Collections are composite types represents groups of multiple elements of the same type. In EVE collections are actually generics. Usually we declare collections using "gradual typing" technique but it is possible to use full type declaration.

Bookmarks:

List
Set
Map
String
Text
Exception

List

A list is a consecutive sequence of elements having a dynamic capacity.

Syntax:

#declare same list twice
locals
    List[elementType] list_name;   //  new empty list of "elementType"
    List list_name := [value, ...]; //  new list with type inferrence

Notes:

The elements of a list have the same type;
Access to eacg element is sequential not direct;

Examples:

# full type declarations
locals
    List[Integer] n_list; 
    List[Object ] o_list; 
    List[String ] s_list;

list literals

List literals enclosed in square brackets,
Elements are separated by comma,
All elements are having the same type.

Examples:

Literals can be used for initialization of variables:

# initialized list with type inference
locals
    List c_list = ['a', 'b', 'c'];
    List n_list = [1, 2, 3];

Literals can be used in assign expressions:

# Defer initialization
driver defer_initial:
    ** define empty list if native types
    List[Integer] c_list;
process
    ** initialize list using  ":=" assign
    c_list := [1,2,3]; 
return;

Set

In mathematics a set is an abstract data structure that can store certain values, in random order, but has no repeated values. Sets are fast collections for search, add update with new values. However, you have to know the element value in order to search for it or to remove it from a set.

global Set[type] set_name = {}; //empty Set but not Null

Empty set

An empty set is represented like this: {} and can be assigned to a set if you wish to remove all elements of the set. A set that is not initialized is Null. Empty set allocated but not Null. It is a difference.

Set restrictions

All elements of a set must have the same type
Set elements can have only comparable types: {Numeric, String, Ordinal}.

Mutability

A set can be modified during run-time using operators.

+= for append
-= for delete
:= for replace

Example:

#demo for using a set
driver set_demo:

global Set[Integer] my_set = {0,2,3}; //initialized set of integers
    
process
    ** append element 1
    my_set += 1;  
    expect my_set == {0,1,2,3};

    ** remove element 2
    my_set -= 2;  
    expect my_set == {0,1,3};
    
    ** modify all elements
    my_set[*] := 0;  
    expect my_set == {0,0,0};
    
    ** remove all elements  
    my_set := {}; 
    expect my_set == {};
return;

Union

Use union operator to combine two sets.

# combine two sets using "|" = (or)
driver set_union_demo:

locals
    Set first = {0,1,2,3,4,5,6,7,8,9};
    Set[Integer] second; // Null set    
    
process
    store  second := first || {0,1,2,10}; // create set
    expect second == {0,1,2,3,4,5,6,7,8,9,10};
return;

Intersection

Intersect operator & find common elements:

# Create intersection using &&
driver set_intersection_demo:

global Set test; // Null set

process
    store test := {1,2,3,4} && {3,4,5}; 
    print test; //  {3,4}
return;

Map

It is also called "hash-map" due to similar letter H representing a connection between two columns: the key column and value column. Collections are ordered by key. This helps to find elements fast using a binary search. That's the idea, so in Python these collections are called Dictionaries.

Maps are sets of (key:value) pairs;
The key must be sortable: { Number, String, Ordinal};

Syntax:

# define some hash-map variables
locals
    Map {String:String} mapName; // define map with string:key and value 
    Map m = {(key:value), ...};  // use type inference to create a map

Example:

#demo how to initialize a Map
driver map_init_demo:
    ** Null table (require initialization)
    Map{String,Integer} table; 
process
    ** initialize table
    table := {('one':1), ('two':2)}; 
return;

String

In EVE There are two types of strings. Single quoted and double quoted strings. They are using different internal representation: Single quoted strings are ASCII strings while double quoted string is called "Text" and has UTF8 internal encoding. Single quoted strings has a limited capacity. Double quoted strings can store multiple lines of text and it has unlimited capacity.

Single quoted string, has default capacity 1024 bytes;
Double quote strings have unrestricted capacity;

String declaration

String can be initialized with a constant literal using single quotes or double quotes. It is an error to declare string and initialize with the double quotes and also is wrong to declare Text and initialize with single quotes.

Syntax:

# define some hash-map variables
locals
    String strName;             // define Null string with default capacity 
    String(capacity) lmString;  // define a limited capacity string
    Text text_name;             // define Null text with unrestricted capacity

Example:

# examples of strings 
locals
    String(100) short_string = ''; //this string can hold 100 symbols
    String string_name       = ''; //default capacity 256 ASCII symbols
    Text text_name           = ""; //variable capacity Unicode string

String mutability

In EVE strings are mutable. If you use ":=" the string object is replaced. If you use a modifiers:"<+" the double quoted string resized automatically. For single quoted strings, if the capacity is over the limit you will get an error: "capacity overflow".

Example:

# working with strings
driver test_string:

locals
    String str = 'First value'; //mutable string
    String ref = 'First value'; //mutable string
process  
    expect (str == ref);     //  same value
    expect (str is not ref); //  different locations  
    
    ** assign := work by reference not by value
    ref := str;   //  reset ref
    expect (str == ref); //  same value
    expect (str is ref); //  same reference 
    
    ** if we modify "str" then "ref" will appear modified
    str <+ ":"; //  mutate string "str"
    expect str == 'First value:'; //  modified
    expect ref == "First value:"; //  also modified
    expect str is ref; // the reference is holding
    
    ** if we recreate str, reference is reset
    str := 'First value:'; //  new string location
    expect str == ref;     //  same value
    expect str is not ref; //  different location

    ** ref is pointing to a different location
    ref  := 'New value:'
    print ref;  //  New value: (modified)
    print str;  //  First value: (initial value)
return;

Note:

You can create garbage in EVE if you loose references to strings;
Provision for large capacity strings is not recommended, use Text instead;

String comparison

Two strings are compared using relation operators: { ==, !=, <, >, >=, <= };
Two strings that have identical characters are equivalent regardless of quotation;
The length of the string is the number of represented symbols:
Empty string '' is has length 0;
The capacity of a string is always greater or equal to the length.

Example:

# compare strings
driver compare_strings:
    expect('this' == 'this');   //  true (same value)
    expect("this" == 'this');   //  true (same value)
    expect(' this' != 'this');  //  true (not same value)
    expect("this " != "this");  //  true (not same value)
return;

Null strings

We can test if a string is Null using "is Null" expression.

# null string demo
driver null_string:

locals 
    String str;      //Null string (not initialized)
    String btr = ''; //Not Null (default capacity)   
process
    ** null string
    expect (str == Null); 
    expect (str != '');   
    expect (str != "");  
    
    ** initialized string
    expect (btr is not Null);        
    expect (btr == "");       
    expect (btr == '');           
return;

Text

Text can contain multiple lines separated with end of line character. A text use Unicode symbols and is optimized for faster search of internal words and symbols. Text is iterable collection, each item is a smaller Text. Default separation is the end of line.

Literal

A text literal can be defined on multiple lines and will preserve the end of line but will cut the indentation. Text literal is enclosed in double quotes. "..." and it may contain symbol "'" without escape. Double quoted Symbol (") must be escaped using notation (\").

# declaration of a text literal
driver text_literal:
    global Text my_text;    
process
    my_text:=
       "Opportunity is missed by most people 
        because it is dressed in overalls 
        and looks like work.";
    print (my_text);
return;

Output:

Oportunity is missed by most people 
because it is dressed in overalls 
and looks like work.

Unicode

The Unicode is a standard for representation of writing for all human languages. An Unicode string is a set of code points using symbols from universal character set (UCS). Unicode is more difficult to represent then ASCII. There are many encoding techniques available. Java uses UTF-16. We will probably use UTF-8 to be more efficient.

Example:

# text typehas unicode support
driver unicode_text:
    Text us = "I can write Greek: \αβγδ\.";
process
    print us;
return;

Output:

I can write Greek: "αβγδ".

To edit source code containing Unicode literals one must use a specific font and UTF-8 source files. The preferred font for EVE programming is "DejaVu Sans Mono".

Exception

Exception is interrupting the current logical flow and jump to the recover region in current section or parent section. In EVE all exceptions are considered errors.

The exception is a variable of type Object that is created when exception is raised and is available in the recover block. System variable @error contains several members that are fill-in by the EVE program when exception is created:

** system exception type
type .Exception = { 
     Integer code 
    ,String  message 
    ,String  routine_name 
    ,String  module_name 
    ,String  line_number  
} <: Object;

** system variables for last error is predefined
global Exception: @error;

Run-time errors

Exceptions can be system exceptions or user defined exceptions.

system exception System exceptions are predefined and created during the program execution when there is a "run-time error" and program can not continue.

User defined exceptions

There are two alternative statements to create user defined exceptions.

** raise exception
when condition do
  raise (code,"message");
done;

** conditional 
raise (code,"message") if condition;

Exception handling

Recover: region define an "exception handling region" for a routine.

In this region developer can use control statements like "switch","case" to analyze the #Error. Developer can decide to stop the program, print a message and resume the program using resume keyword.

Example:

#using recover
driver recover_demo:
    global Double a = 0.00;
process  
    a := 1/0;
recover
    print @error.message;
return;

Output:

error: numeric division by zero.

Using expect

The expect statement check a condition and raise an error if condition is false. Error message is default: "Unexpected error in line: N".

Pattern:

** precondition (short version)
expect condition;
  
** equivalent (longer version)
raise "Unexpected error in line \n" ? 
       @error.line_number if condition;

Nots:

can be used as pre-condition
can be used as post-condition
unexpected error has code = 0

Read next: Control Flow