General syntax for variable initialisation

As can be seen in the chapter on basic Ocelet instructions, it is possible to declare a constant with the fix keyword, and a variable with the letkeyword, and at the same time give an initial value to the constant or the variable.

The general syntax for providing this initial value is as follows:

identifier = new type ( initial values )

Here are some examples of constant and variable initialisations with this syntax:

let temperature = new Double(25.0)
fix lis_altitudes = new List<Double>()
let isActive = new Boolean(true)
fix nb_yeras = new Integer(12)
fix contour = new Polygon()

In practice, this syntax is not compulsory. Other functions and methods exist for providing initial values, but they vary according to whether the types are simple, composite or are collections.

Simple types, Composite types, Collections, and variable initialisation

We distinguish three kinds of types when explaining the differences in the way variables (or entity properties) are initialised.

Simple types

These are types that contain only one value:

• Boolean
• Double
• Float
• Integer
• Long
• String

Simple type variable or constant initialisation can be shortened, without the need for the new keyword or even naming the type. Ocelet will try to guess the type from the content written after the =. This mechanism is called type inference.

For example we can write:

let temp = 34.7
fix name = "Bellecombe"
let isActive = true

instead of

let temp = new Double(34.7)
fix name = new String("Bellecombe")
let isActive = new Boolean(true)

In order for the inference to be correct, care must however be taken in the way the variable is initialised. For example, if we write let g = 0, variable g will be considered an Integer. If we need that variable to be of type Double it must be initialiser with 0.0. You can refer to the detailed documentation on each of the types to have the correct syntax that will ensure the right inferred type.

Composite types

These types contain a finite number (known in advance) of values. These values can be of a simple type, a composite type or a collection. The composite types of Ocelet are:

• Color
• Date
• Line and MultiLine
• Point and MultiPoint
• Polygon and MultiPolygon

In addition to these predefined composite types, user-defined types called Structure can also be used. The entities, relations and datafacers defined in a model can also be considered composite types, at least because the rules that apply for variable creation and initialisation are the same.

In the general case, it is possible to create a variable (or a constant) without any initialisation value, in which case default values will be used. As no arguments are passed within brackets, the latter can be removed.

For example we can write:

let now = new Date
let mycolor = new Color
let contour = new Polygon

The default value depends of course on the type. Here, the variable now will contain the data and time when the instruction is executed, mycolor will contain light grey and contour will be an empty polygon (that does not contain any point).

Certain composite types have specific initialisation functions

The syntax for using these functions is as follows;

identifier = type | initialisation function ( function arguments)

Note the absence of the keyword newin this case. Here are some examples of initialisation of this form:

let start = Date|fromString("dd-MM-YYYY","01-02-2016")
let mycolor = Color|rgba(255,230,230,128)
let position = Point|xy(570680.0,4832818.0)

Please refer to the documentation on each type to get the list of available initialisation functions and their respective arguments.

It is to be noted that you can write your own initialisation function for the entities that you define. Please refer to the documentation on the entities (see init keyword).

Collections

These are types that contain a certain number of values that is not known in advance. These collection types are:

• List
• Keymap
• Group

The collection is created empty, and objects are added afterwards. When creating a new collection, one has to specify the type of the objects to be put in the collection.

The syntax is as follows:

identifier = new collection type < content type>

For example a list of integers can be prepared with:

fix series = new List<Integer>

and values are added with:

series.add(5)
series.add(8)
series.add(3)

The function used for adding values depend on the collection type. For instance, the function add() is present for List and Group but not for Keymap.

In the example above, note that the list was created as a constant (using fix rather than let). This is because the list itself (the container) is not meant to change, and adding and removing objects from the list will remain possible. That said, it is still possible to put a list in a variable (using let) if it is necessary replace that list with another list in that variable. In that case, it means that a container (the first list) is replaced by another container (the second list).

Finally, just as other composite types, the List and Group collection types have an initialisation function called of() which allows creating a collection and filling it with content in the same instruction. The type of the content is deduced from what is added, and of course, all objects added must be of the same type.

Examples:

fix series = List|of(5,8,3)
fix week = List|of("Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday")

Numeric types

Double

Double precision (64-bit format) decimal numbers. This is the default type used in Ocelet during declaration of a variable initialised with a decimal number. But a numeric value can also be forced to be of type Double by adding a letter D at the end:

let t = 0.12
let u = 2D
let v = 0.1546D
let h = 1.234e4

t, u,v and h will all be of type Double. The value 1.234e4 is expressed in scientific notation and is equal to 1.234 x 10000 = 12340.0

When defining a property of an entity or of a relation, the property is not initialised directly, therfore the required type must be given:

entity Station {
  property Double temp
}

Float

Simple precision (32-bit format) decimal numbers. To initialise a variable with a Float type decimal number, a letter F has to be added in the end:

let u = 2F
let h = 1.234e4
let v = 0.1546F

u,v and h are all of type Float. In this example the value 1.234e4 in expressed in scientific notation and is equal to 1.234 x 10000 = 12340.0

When defining a property of an entity or of a relation, the property is not initialised directly, therfore the required type must be given:

entity Station {
  property Float temp
}

Integer

Integer (32-bit format). This is the default in Ocelet during declaration of a variable initialised with a whole number:

let u = 2
let h = 4e5

u and h will be of type Integer. In this example the value 4e5 is expressed in scientific notation and is equal to 4 x 100000 = 400000

When defining a property of an entity or of a relation, the property is not initialised directly, therfore the required type must be given:

entity Station {
  property Integer temp
}

Long

Long integer (64-bit format). It is not the default type when declaring a variable initialised with a whole number. To initialise a variable with a long integer the letter L has to be added at the end:

let u = 2L

u will be of type Long.

When defining a property of an entity or of a relation, the property is not initialised directly, therefore the required type must be given:

entity Station {
  property Long temp
}

Conversion of numeric types

It happens that when manipulating variables of different numeric types conflicts arise that need to be resolved. This can be done using type conversion functions.

Such a conflict arises when for example when we try to round a Double type number and assign it to an Integer type variable:

let t=112.5  // t is of type Double
let f=0      // f is of type Integer
f=round(t)   // type conflict

The round() function does return a whole number, but as t is of type Double, round() returns a Long type number. The conflict is due to the fact that when assigning a Long variable to an Integer, there is a risk of loss of information if the number is too large. You will therefore need to force a type conversion if that risk does not exist in your program. In this case, the conversion function intValue() is to be used:

let t=112.5  // t is of type Double
let f=0      // f is of type Integer
f=round(t).intValue()   // No type conflit, an Integer is obtained

The type conversion functions are:

• Double doubleValue()
• Float floatValue()
• Integer intValue()
• Long longValue()

Initialisation functions of numeric types

These functions are used to create a numeric type value without giving that value directly. They are available for all numeric types.

• valueOf( Double number )
• valueOf( String text )

Example:

let t = 25  // t is of type Integer
let u = Double|valueOf(t) // u will be a Double
let v = Double|valueOf("240")  // Creates a Double from the text "240"

Thematic types

Boolean

Type representing a binary state: either true or false.

let v=true

A variable of type Boolean can be used in a test :

if (v) println("Ok.") else println("Not ok.")

Color

Type used to contain a color. Variables of type Color are particularly useful when defining the styles used in the maps that are produced during simulations.

Color is a composite type, that is, it contains several components. A Color type variable declared without initial values will have a default colour (light grey):

let defautColor = new Color

In order to choose colour components, initialisation functions are necessary.

    Initialisation functions

• rgb(Integer red, Integer green, Integer blue): red, green, blue are integers between 0 and 255. They represent the components of colour required.
• rgba(Integer red, Integer green, Integer blue, Integer alpha): alpha is also an integer between 0 and 255 and represents the opacity level (also known as alpha channel). Value 0 is completely transparent, value 255 is completely opaque.

• text(String rgb): this initialisation function has been added to allow returning a colour directly from a textual representation of its components, as can be found in some file formats such as CSS (Cascading Style Sheet) for example. These two expressions are valid:

  • "#RRVVBB" : components red, green and blue are expressed in hexadecimal. For each component, 00 is the minimum and FF is the maximum.
  • "#RRVVBBAA" components red, green, blue and opacity are expressed in hexadecimal.

Examples:

let color1 = Color|rgb(255,255,168)      // produces pale yellow completely opaque
let color2 = Color|rgba(255,128,255,128) // produces a rose color with 50% transparency
let color3 = Color|text("#FF80FF80")     // produces a rose color with 50% transparency

    Useful functions

Once we have a variable of type Color, the following functions can be applied to it:

• Color darker( Double proportion ) : Produces a new color, darker than the original color, according to the specified proportion. proportion is a value of type Double between 0 and 1.
• Color lighter( Double proportion ) : Produces a new color, lighter than the original color, according to the specified proportion. proportion is a value of type Double between 0 and 1.
• List<Color> colorRange( Integer number_of_colors , Color another_color ) : Produces a color gradient as a list of colors (of type List< Color >). The number of colors is an integer that specifies the number of intermediate colors in the list. The color gradient is obtained between the color to which the function is applied and another color.
• String toString() : Returns the color in text format as "rgb(r,g,b)"

Examples:

let color1 = Color|rgb(255,255,168) // pale yellow
let color4 = color1.darker(0.5)     // beige: rgb(127,127,84)
let degrad = color1.colorRange(8,Color|rgb(0,128,255)) // colour gradient from yellow to blue in 8 colours

DateTime

Type for manipulating dates and time. This type is convenient for integrating temporal information fields into data resulting from simulations.

_Note: The DateTime type only exists in Ocelet since version 2.0. It replaces the Date type which was used until then. The Date type is now considered obsolete and the Ocelet editor will cross out the Date type when we try to use it, in a way to remind that it is preferable to use the DateTime type instead. The main difference between the Date and DateTime types is that the functions used for changing the date or time directly affect the content of the Date type variables, but do not affect the content of DateTime type variables. With the DateTime type, it is no longer necessary to clone the date to make a copy of it. But, in return, the results of the functions modifying the date or time must now be retrieved (see example below).

It is possible to create a DateTime variable without initialising its content, in which case it will contain the date and time the function is called:

let now = new DateTime

DateTime is a composite type, that is, it is composed of several components: year, month, day, hour, minutes, seconds and milliseconds. The initialisation of a variable of type DateTime must be done using an initialisation function.

Initialisation functions

• ymd(Integer year, Integer month, Integer day) : Returns a DateTime from the three integers representing the year, month and day. In this case the time will be 00:00:00.
• fromString(String format , String date ) Returns a DateTime from a text in a format following a pattern. The pattern is composed of characters referring to the different elements of dates and time. See the Format pattern table.

Examples:

let date1 = DateTime|ymd(2010, 12, 25)  // DateTime returned: 25 dec. 2010 00:00:00
let date2 = DateTime|fromString("yyyy-MM-dd kk:mm","2010-12-25 15:30") // DateTime returned: 25 dec. 2010 15:30:00

    Useful functions

There are many functions available for the type DateTime. They are presented hereby in groups of similar functions.

Adding time to a date

As indicated by the return type of these functions, all of them return a new DateTime variable. The variable on which one of these functions is applied is not affected. In other words, if the content of the variable needs to be changed, the variable must be assigned the result returned.

• DateTime addYears(Integer nb_years) : Adds a number of years to a given date and time
• DateTime addMonths(Integer nb_month) : Adds a number of months
• DateTime addWeeks(Integer nb_weeks) : Adds a number of weeks
• DateTime addDays(Integer nb_days) : Adds a number of days
• DateTime addHours(Integer nb_hours) : Adds a number of hours
• DateTime addMinutes(Integer nb_minutes) : Adds a number of minutes
• DateTime addSeconds(Integer nb_seconds) : Adds a number of seconds

Example:

let date3 = DateTime|fromString("yyyy-MM-dd","2010-01-20")
date3 = date3.addWeeks(2) // Adding 2 weeks => 3 Feb. 2010

Reading a date element

All these functions return an integer that corresponds to one of the elements of a date and time. The name of the function indicates the element returned.

• Integer getYear() : Returns the year of a date variable
• Integer getMonth() : Returns the month
• Integer getDayOfWeek() : Returns the day of the week
• Integer getDayOfMonth() : Returns the day of the month
• Integer getDayOfYear() : Returns the day of the year
• Integer getHour() : Returns the hour
• Integer getMinute() : Returns the minute
• Integer getSecond() : Returns the second
• Integer getMillisecond(): Returns the millisecond
• Long getTimeAsMilliseconds() : Returns a long integer that correspond to the number of milliseconds since midnight on that date. In other words, the current time is converted in milliseconds.

Changing a date or time element

All these functions take in an integer as parameter and return a new DateTime variable. The variable on which the function is called is not changed. The name of the function indicates the element concerned.

• DateTime withYear(Integer annee) : Changes the year of a date variable
• DateTime withMonth(Integer mois) : Changes the month
• DateTime withDayOfWeek(Integer jour) : Changes the day of the week
• DateTime withDayOfMonth(Integer jour) : Changes the day of the month
• DateTime withDayOfYear(Integer jour) : Changes the day of the year
• DateTime withHour(Integer heures) : Changes the hour
• DateTime withMinute(Intger minutes) : Changes the minutes
• DateTime withSecond(Integer secondes) : Changes the seconds
• DateTime withMillisecond(Integer milliseconds) : Changes the milliseconds

Exemple :

let date3 = DateTime|fromString("yyyy-MM-dd","2010-01-20")
date4 = date3.withMonth(5) // Change the month: date4 = 20 May 2010
// In this example the result is assigned to  date4
// The date and time of variable date3 is not changed.

Comparing DateTimes

• Boolean isAfter(DateTime date) : Returns a value of type Boolean. Returns true if the date provided is after the date to which the function is applied.
• Boolean isBefore(DateTime date) : Returns true if the date provided is before the date to which the function is applied.

Example:

let date1 = DateTime|fromString("yyyy-MM-dd","2010-01-20")
let date2 = DateTime|fromString("yyyy-MM-dd","2010-02-22")
date1.isAfter(date2)  // => false
date1.isBefore(date2) // => true

Time difference

The time lapse between two DateTime can be obtained in a chosen time unit (year, month, day, hour, minute, second, millisecond). The functions available to access them:

yearsDifference(DateTime d)
monthsDifference(DateTime d)
daysDifference(DateTime d)
hoursDifference(DateTime d)
minutesDifference(DateTime d)
secondsDifference(DateTime d)
millisecondsDifference(DateTime d)

If DateTime d passed as argument is after the DateTime on which the function is applied, the result is positive, otherwise, it is negative.

Example :

fix date1 = DateTime|ymd(2010, 12, 25)
fix date2 = DateTime|fromString("yyyy-MM-dd kk:mm","2010-12-27 15:30")

println("Number of months between date1 and date 2: "+date1.monthsDifference(date2))
println("Number of days between date1 and date 2: "+date1.daysDifference(date2))
println("Number of hours between date1 and date 2: "+date1.hoursDifference(date2))
println("Number of minutes between date1 and date 2: "+date1.minutesDifference(date2))

will give:

Number of months between date1 and date 2: 0
Number of days between date1 and date 2: 2
Number of hours between date1 and date 2: 63
Number of minutes between date1 and date 2: 3810

Conversion to String

• String toString() : Returns a text with the date and time following the default format
• String toString( String format ) : Returns a text with the date and time following the format specified with the pattern provided. The pattern is composed of characters that represent elements of dates and time. See the Format pattern table.

Example:

let date1 = DateTime|fromString("dd/MM/yy","22/02/10")
println("Date : "+date1.toString("yyyy-MM-dd"))  // Text displayed => Date : 2010-02-22

Date and time format patterns

String

This type represents a string of characters that form a text. It is possible to initialise a variable of type String directly with a text, by inserting the text between the character ".

Example:

let nom = "Curepipe"

    Useful functions

• Integer compareTo( String text ) : Compares a text with another text provided as parameter. The comparison differentiates upper from lower cases.
  • Returns 0 if the two texts are identical.
  • Returns an integer less than 0 if the text is before the one provided as parameter(in alphabetical order).
  • Returns an integer greater than 0 if the text is after the one provided as parameter(in alphabetical order).
• Integer compareToIgnoreCase( String text ) : Compares a text with another text provided as parameter without differentiating upper and lower cases.
  • Returns 0 if the two texts are identical.
  • Returns an integer less than 0 if the text is before the one provided as parameter(in alphabetical order).
  • Returns an integer greater than 0 if the text is after the one provided as parameter(in alphabetical order).
• String concat( String text ) : To the end of the text, add the provided as parameter.
• Boolean endsWith( String text ) : Returns true the text ends with the text provided as parameter.
• Boolean equals( String text ) : Returns true if the text is identical to the one provided as parameter. The comparison differentiates upper from lower cases.
• Boolean equalsIgnoreCase( String text ) : Returns true if the text is identical to the one provided as parameter, without differentiating upper and lower cases.
• Integer indexOf( String text ) : Returns the position of the provided text in the text, or -1 if the text provided is not present.
• Integer indexOf( String text , Integer index ) : Returns the position of the provided text in the text, starting the search from the provided index, or -1 if the text provided is not present.
• Integer lastIndexOf( String text ) : Returns the position of the last occurrence of the provided text within the text.
• Integer lastIndexOf( String text , Integer index ): Returns the position of the last occurrence of the provided text within the text, starting the search from the provided index.
• Integer length() : Gives the number of characters in the text.
• Boolean startsWith(String prefix) : Returns true if the text starts with the provided text.
• Boolean startsWith(String prefix, Integer index) : Returns true if the provided text is found at the provided index within the text.
• String substring(Integer index) : Returns the end of the text starting from the provided index.
• String substring(Integer beginning, Integer end) : Returns the part of the text found between the beginning and end indices.
• String toLowerCase() : Sets the text to lower case.
• String toUpperCase() : Sets the text to upper case.
• String trim() : Remove blanks at the beginning or end of the text (if any).

Geometric types

Geometric types allow manipulating the spatial components of geographical information. These can be point, linear or surface types, with for each, a simple and a multiple type. Each geometric type has its own initialisation functions. The usual functions are common to all (but one) of them and are presented after the types.

Line

Simple geometry of type line.

    Initialisation functions

• points(Point p1, ...): Builds an element of type Line from a variable number of points provided as parameter.
• points(List<Point> points): Builds an element of type Line from a list of points provided as parameter.

Examples:

let segment = Line( Point|xy(100d,50d) , Point|xy(320.4, 55d) )

let lp = new List<Point>
lp.add(Point|xy(100.0,100.0))
lp.add(Point|xy(200.0,100.0))
lp.add(Point|xy(100.0,200.0))
let line2 = Line|points(lp)

    Useful functions

• List<Point> asListOfPoints(): Gives access to a list of points that correspond to the coordinates of the Points in the line object.

MultiLine

Multiple line geometry. This type groups several linear elements in the same variable.

    Initialisation functions

• lines(Line l1, ...): Builds an element of type MultiLine from a variable number of Lines provided as parameter.
• lines(List<Line> lines) : Builds an element of type MultiLine from a list of Lines provided as parameter.

    Useful functions

• List<Line> asListOfLines(): Gives access to a list of Lines representing the content of the MultiLine.

Point

Simple point geometry.

    Initialisation functions

• xy(Double x, Double y): Builds a Point from coordinates provided as arguments.
• xyz(Double x, Double y, Double z): Builds a Point from coordinates provided as arguments, z representing an altitude.

MultiPoint

Multiple point geometry. This type groups Point elements in the same variable.

    Initialisation functions

• points(Point p1, ...): Builds an element of type MultiPoint from a variable number of Points provided as parameter.
• points(List<Point> points) : Builds an element of type MultiPoint from a list of Points provided as parameter.

    Useful functions

• List<Point> asListOfPoints(): Gives access to a list of Points that constitute the MultiPoint.

Polygon

Simple surface geometry.

    Initialisation functions

• points(Point p1, ...): Builds an element of type Polygon from a variable number of Points provided as parameter.
• points(List<Point> points): Builds an element of type Polygon from a list of Points provided as parameter.

    Useful functions

• List<Point> asListOfPoints(): Gives access to a list of Points that constitute the external contour of the Polygon.

MultiPolygon

Multiple surface geometry. This type groups several surface elements in the same variable.

    Initialisation functions

• polygons(Polygon l1, ...): Builds an element of type MultiPolygon from a variable number of Polygons provided as parameter.
• polygons(List<Polygon> polys): Builds an element of type MultiPolygon from a list of Polygons provided as parameter.

    Fonction d'usage

• List<Polygon> asListOfPolygons() : Donne accès à une liste des Polygon contenus dans ce MultiPolygon.

Useful functions common to all geometric types

These functions can be applied to variables of all types of geometry. For sake of simplification when describing these functions, we use the term Geom which generically stands for Point, MultiPoint, ..., MultiPolygon (but the type Geom cannot be used as such in an Ocelet program).

• Geom buffer(Double width) : Produces a buffer zone around the object whose width is specified as parameter.
• Boolean contains(Geom object) : Tests if the object completely contains the object provided as parameter, and returns true if it is the case.
• Boolean disjoint(Geom object) : Tests if the object and the one provided as parameter are disjoint, and returns true if it is the case.
• Double distance(Geom object) : Returns the distance the object and the one provided as parameter.
• Double getArea() : Returns the surface area of the object. Of course, only surface geometries will return values greater than 0.
• Line getBoundary() : Returns the linear object that forms the external boundary of a given object.
• Point getCentroid() : Returns the Point object that is located at the barycenter of a given object. Note that the centroid of a polygon is not necessarily inside the polygon.
• Integer getDimension(): Returns the spatial dimension of the object:
  • 0 for a point object
  • 1 for a linear object
  • 2 for a surface object
  • 3 if the coordinates used also contain an information on altitude
• Point getEndPoint() : Returns the last Point of the object.
• Geom getEnvelope() : Returns the bounding box of a given object.
• Point getInteriorPoint(): Returns a Point located inside the object. Much slower then the getCentroid() function.
• Integer getNumPoints() : Returns the number of Points the objects is made of.
• Point getpointN(Integer index): Returns the Point found in the position specified in the index, following the order of the points the object is made of.
• Point getStartPoint() : Returns the first Point of the object.
• Boolean intersects(Geom object) : Tests whether the object provided as argument intersects the one to which the function is applied, and returns true if this is the case.
• Boolean isValid() : tests if the geometry of the object is valid, and returns true if this is the case. This test is pertinent only for surface objects, and are valid if:
  • The external boundary is closed (the first and last points are identical).
  • There is no crossing over: the external boundaries of the elements that compose the object do not cross each other.
  • When present, the holes must be found entirely inside the external boundary of the object.
• Geom intersection(Geom object) : Returns a new object whose geometry results from the intersection of the given object with the object provided as argument.
• Geom move(Double dx, Double dy) : Displaces the object by distances dx and dy passed as arguments. The object displaced at a new position is returned by this function.
• Geom rotate(Double angle, Double anchorx, Double anchory) : Rotates the object around an anchor point of coordinates anchorx, anchory and by an angle angle passed as arguments. The rotated object is returned by the function.
• Geom scale(Double xfactor, Double yfactor) : Homothetic transformation of the object by a scale factor of xfactor and yfactor passed as arguments. The scaled object resulting from the transformation is returned by the function.
• Geom union(Geom object) : Returns a new object whose geometry results from the union of the given object and the object provided as argument.

Structure

Situations arise when it is required to store in the same variable several values of possibly different types, that we wish to keep together. We then need to define our own composite type. This is what structures allow to do.

A structure must be defined in a model, at the same level as an entity, a relation or a scenario.

Syntax for defining a new structure

structure Name {

definitions of the variables that make up the structure

}

As many variables as needed can be included. Each variable is defined by:

Type identifier

The Type is either an Ocelet type ( Integer, Double, Point, etc. ), or a user-defined composite type structure.

The Name of the structure and of the identifiers of the variables it is made of must necessarily begin with a letter, but can eventually be followed by numbers, and not contain blanks or special characters. The Name of the structure must start in upper case.

Using it in a scenario

The definitions of structures are found outside scenarios. Inside a scenario, reference are made to these definitions to create one or more variables with a structure of that type.

The internal variables of a structure can be accessed directly by inserting a . between the name of the variable and the name of the internal variable.

Example

structure Displacement {
  Double direction
  Double velocity
}

scenario MyModel {
  let dep = new Displacement
  dep.direction = 0.0
  dep.velocity=2.4
  d.direction = 0.3    // change of direction
  println("Direction of displacement :" + d.direction)
  println("Velocity of displacement :" + d.velocity)
}

It is possible to initialise part or all of the variables inside the structure when it is created, using the following syntax:

indentifier = new name of the structure => [ variables assignment ]

The scenario in the above example can thus be shortened:

scenario MyModel {
  let dep = new Displacement => [direction=0.0 velocity=2.4]
  dep.direction = 0.3    // change of direction
  println("Direction of displacement :" + dep.direction)
  println("Velocity of displacement :" + dep.velocity)
}

Collections

Collections are types that allow keeping together a series of elements of the same type. Three such types exist in Ocelet: Group, List et KeyMap.

• Group corresponds to a set: the elements contained are unique and are not ordered.
• List corresponds to an ordered set, where eventually an element may appear more than once.
• KeyMap is an associative array to store a collection of pairs of (key, value), where each key appears only once.

All collections have initialisation functions, and usual functions are detailed separately below. In the rest of this section T stands for the type of the elements in a collection, which may be any of the Ocelet types.

Group

The Group type corresponds the idea of unordered set with only unique elements. All the elements of a Group must be of the same type, which must be specified when declaring the variable that will contain the group. For example, for a group of Points, the variable is declared in this way:

fix gpts = new Group<Point>

    Initialisation functions

T represents the type of the elements stored in the group.

• of(T object1, T object2, ...): Adds to the group each of the objects specified as arguments. All the objects must be of the same type as the one declared for the Group.

Example:

fix gint = Group|of(13,67,34,89,1,0,5,6)
fix gpts = Group|of(Point|xy(12.0,45.3),Point|xy(13.5,43.46))

    Useful functions

• add(T object): Adds an object to the group
• addAll(List<T> elements) ; addAll(Group<T> elements) : These functions are for adding a series of elements that come from a list or a group provided as argument.
• clear() : erases the content.
• Boolean contains(T object) : Returns true if the group contains the object provided as argument.
• BooleanisEmpty(): Returnstrue` if the group is empty.
• remove(T object) : Removes from the group the object (if it exists) provided as argument.
• Integer size() : Returns the number of elements in the group.

Although this is not specific for collections, it is good to know that the instruction for(..) can be used to run through all the elements of a Group:

// i will successively take the value of all the elements of the group gint
for (i:gint) { println("Next integer: "+i) }

List

The type List corresponds to a series of ordered elements where eventually elements may appear more than once. All the elements present in the List must be of the same type, which must be specified when declaring the variable that will contain the list. For example, for a list of Points, the variable is declared in this way:

fix lpts = new List<Point>

In this section T stands for the type of the elements in a collection, which may be any of the Ocelet types.

    Initialisation functions

• of(T object1, T object2, ...): Adds to the list each of the objects specified as arguments. All the objects must be of the same type as the one declared for the List.

Example:

let days = List|of("Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday")

    Useful functions

• add(T object): Adds an object at the end of the list
• add(Integer position, T object): Adds the object at position position in the list.
• addAll(List<T> elements) ; addAll(Group<T> elements): These functions are for adding a series of elements that come from a list or a group provided as argument.
• addFill(Integer quantity, T value): Add value to the list as many times as the quantity given.
• addU(T object): Addition that preserves the unicity of the content. The object is added only if it is not already in the list.
• clear(): erases the content.
• Boolean contains(T object): Returns true if the list contains the object provided as argument.
• Integer frequency(T object): Returns the number of occurrences of the given object.
• T get(Integer position) : Returns the element found at position given as parameter. The first element is at position 0.
• Boolean isEmpty() : Returns true if the list is empty.
• Integer lastIndexOf(T object) : Returns the position of the last occurrence of the object provided as argument.
• remove(T objet) : Removes the first occurrence (if exists) of the object provided as argument.
• reverse() : Reverse the order of the elements in the list.
• rotate(Integer distance): Offset the elements in the list by the distance indicated. All the elements going out on one side are entered on the other. After a call to this function, elements at index i will be the elements that were at index (i-distance) modulo list.size for all the values of i between 0 and list.size-1 included. This function does not change the size of the list.
• set(Integer position, T object): Replace the element in the given position by the object provided in argument.
• shuffle() : Random change of the order of the elements in the list.
• Integer size() : Returns the number of elements in the list.
• swap(Integer i, Integer j) : Swap the elements at positions i and j given.

Although this is not specific for collections, it is good to know that the instruction for(..) can be used to run through all the elements of a List:

// j will successively take the value of all the elements of the list days
for (j:days) { println("Next day: "+j) }

KeyMap

This type is an associative array to store a collection of pairs associating a key to a value. There is no initialisation function for KeyMap. A variable of type KeyMap is created empty and pairs of key/value are added using the function put(). When the variable of type KeyMap is created, the type of the key and the type of the value must be specified:

let km = KeyMap<Integer,String>{}
km.put(1,"January")
km.put(7,"July")

There is no initialisation function for KeyMap.

    Useful functions

In this list of functions, K stands for the type of the key, and V for the type of value.

• clear() : Erases the content (keys and values).
• Boolean containsKey(key): returns true if the key given in argument is present in the KeyMap and false if it is not found.
• V get(K key) : Returns the value that correspond to the key provided as argument, or null is not in the KeyMap.
• put(K key, V value) : Adds a pair of key/value
• remove(K key) : Removes the pair key/value corresponding to the key provided as argument.
• Integer size() : Returns the number of pairs in the variable of type KeyMap.

Browsing keys and values

It is possible to run through the keys present in a variable of type KeyMap using the instruction for(...) and the function keySet() in this way (with km the variable defined above):

for(key:km.keySet()) {
  println("Next key : "+key)
}

Result:

Next key : 1
Next key : 7

Similarly, the function values() allows to run through the values:

for(val:km.values()) {
  println("Next value : "+val)
}

Result:

Next value : January    
Next value : July

Cell

The Cell type allows manipulating geographical information in the form of regular spatial representations. The latter are stored in raster - matrix format. There exists three regular pavings to represent space and have been attributed to the type Cell : the square (or rectangle), the equilateral triangle and the regular hexagon. When an entity has a cell type property, it can only have other properties of basic types: Double, Integer, Float, Byte, Boolean.

Cell

Regular cells to completely pave a space

    Useful functions

• getX() : Returns the X position in the matrix (or the number of columns)
• getY(): Returns the Y position in the matrix (or the number of lines)
• getCentroid(): Returns a Point with the coordinates (projected or in longitude/latitude) of the centre of the cell, in the geographical reference system used.
• toPolygon(): Returns a Polygon of the shape of the cell in projected coordinates or in longitude/latitude according to the geographical reference system used.
• distance(Cell cell): Returns the distance from a Cell type property.
• distance(Geometry geom): Returns the distance from a Geometry type property.