Display and save text

Formatting numeric values: format(...)

This function is for setting the display format of a numeric variable. It is used for example to choose how many decimal places to display.

Syntax:

String format(Number n, String pattern)

The type Number used in this syntax represent one of the numeric types (Integer, Double, Float, etc).

Le motif est une série de symboles qui permet de spécifier le format d'affiThe pattern is a series of symbols that specifies the display format:

• 0 : Display a number (including a leading zero).
• # : Display a number, without leading zeros.
• . : Decimal separator
• - : Minus sign
• , : Digit grouping separator
• E : Separates the mantissa and the exponent in scientific notation
• % : Multiply by 100 and display as percentage
• ' : Character to put before and after any of the previous symbols to include them in the display

Examples:

let n=PI
println("PI ="+n)
println("PI ="+format(n,"#.##"))
println("PI ="+format(n,"00.###"))
println("PI ="+format(n,"00.###E0"))

let m=1.0/4.0
println("m is equal to "+format(m,"#.###%"))

will display:

PI =3.141592653589793
PI =3.14
PI =03.142
PI =31.416E-01
m is equal to 25%

Syntax for country format:

String format(Number n, String motif, String country)

This alternate form of the format(...) function is to specify that the display format of a given language is to be followed. The language is specified with the two-letter code according to ISO 630-1. The default convention is English.

Example:

let price=1250000
println("Prix :"+format(price,"###,###,###.00 €","fr"))
println("Price :"+format(price,"$ ###,###,###.00","en"))

will display:

Prix :1 250 000,00 €
Price :$ 1,250,000.00

print(...)

Displays a text on the screen and remains on the same line.

Syntax:

String print(String text)

Example:

print("Simulation ... ")
print("ends.")

will display the text:

Simulation ... ends.

println(...)

Displays a text on the screen and moves to the next line

Syntax:

String println(String text)

Example:

println("Simulation ... ")
println("ends.")

will display the text:

Simulation ... 
ends.

To display the content of a variable, + the text concatenation operator can be used:

let temp = 20
println("The temperature is "+temp+"°C")

will display: The temperature is 20°C

printToFile(...)

will record one line of text in a file. Each call to this function will append one line to the file indicated. If the file does not exist, it will be created.

Syntax: printToFile(String FileName, String lineofText)

Files and folders

In Ocelet, file creation is usually done through the use of datafacers. Some datafacers also propose functions for deleting files. The functions described in this section are thus additional: they are basic functions to create and delete folders, and to delete files outside datafacers.

Add a folder : createDir()

Function for adding a new directory at the given location. If the path contains several sub-folders which do not exist yet, they will all be created. According to the configuration of the system used, it may be possible that deletion is refused if the user do not have appropriate rights.

Syntax:

Boolean createDir(String path_and_name)

Creates a folder at path and with the specified name. This function returns true if the folder has been created, or false otherwise.

Example:

createDir("output/indicators")
printToFile("output/indicators/results.txt","Temperature"+temp)

These two instructions will add a folder indicators to the output folder of the project, then create a file resultats.txt in this folder.

Delete a folder : removeDir()

Delete a folder and all its content.

N.B. this function will not request confirmation before deletion and it is impossible to revert back. The path must be set with care. According to the configuration of the system used, it may be possible that deletion is refused if the user do not have appropriate rights.

Syntax:

removeDir(String path_and_name)

Exemple :

removeDir("output/indicators")

This instruction deletes the indicators folder located in the output folder. The content of the indicators folder is also deleted.

Delete a file: removeFile()

Delete the file indicated.

N.B. this function will not request confirmation before deletion and it is impossible to revert back. The path must be set with care. According to the configuration of the system used, it may be possible that deletion is refused if the user do not have appropriate rights.

Syntaxe :

removeFile(String path_and_name)

Exemple

removeFile("output/indicators/results.txt")

This instruction deletes tha results.txt file which is in the output/indicators folder.

Tests on files and folders

The fileExists(String file_name) function allows to inform on whether the filename corresponds to an existing file or not. This function returns true if the name supplied refer to an existing file, but also if it is an existing folder name.

The functions isDir(String file_name) or isFile(String file_name) can be used to inform on whether the filename corresponds to a file or a folder.

Mathematical functions

Most of the mathematical functions available in Ocelet come from Java (from the java.lang.Math package to be precise).

They can be used directly in the instructions of a scenario, entity services or interaction functions.

Exampl :

let radius = 12.5
let angle = 170  // degres

let distance_x = radius * cos(toRadians(angle))
let distance_y = radius * sin(toRadians(angle))

List of available functions

Each time a function can be applied indifferently with the numeric types Double, Float, Integer, and Long, we have replaced the type indicator by Number. A chaque fois qu'une fonction peut s'appliquer indifféremment avec les types numériques Double, Float, Integer, et Long, nous avons remplacé l'indication du type par Number.

• Number abs(Number a) : Returns the absolute value of the given value. The returned value is of the same type of the given value.
• Double acos(Double a) : Returns an angle between 0.0 and PI which corresponds to the inverse cosine of the given number.
• Double asin(Double a) : Returns an angle between -PI/2 and PI/2 which corresponds to the inverse sine of the given number.
• Double atan(Double a) : Returns an angle between -PI/2 and PI/2 which corresponds to the inverse tangent of the given number.
• Double atan2(Double y, Double x) : Returns the angle theta resulting from the conversion of rectangular coordinates (x,y) in polar coordinates (r,theta)
• Double cbrt(Double a) : Returns the cibic root of a given number.
• Double ceil(Double a) : Returns the nearest integer greater than or equal to the argument.
• Double copySign(Double magnitude, Double sign) : Returns a value with the magnitude the first argument and the sign of second argument.
• Double cos(Double a) : Returns the cosine of the angle (in radians) given.
• Double cosh(Double x) : Returns the hyperbolic cosine of the angle (in radians) given.
• Double exp(Double a) : Returns the exponential of value a given, that is E to the power of a.
• Double floor(Double a) : Returns the nearest integer less than or equal to the argument.
• Double hypot(Double x, Double y) : Returns the hypotenuse of a right-angled triangle of sides x and y. That is sqrt(x²+y²)
• Double log(Double a) : Returns the natural logarithm of the given value.
• Double log10(Double a) : Returns the decimal logarithm of the given value.
• Number max(Number a, Number b) : Returns the larger of the two values provided.
• Number min(Number a, Number b) : Returns the smaller of the two values provided.
• Double pow(Double a, Double b) : Returns the value of the first argument at the power of the second argument.
• Double random() : Returns a random number within the interval [0.0 .. 1.0[ .
• Long round(Double a) : Returns the value of a number rounded to the nearest long integer.
• Integer round(Float a) : Returns the value of a number rounded to the nearest integer.
• Double signum(Double d) : Returns -1.0 if value is negative, 0 if it is equal to 0 and 1.0 if it is positive.
• Float signum(Float f) : Returns -1.0 if value is negative, 0 if it is equal to 0 and 1.0 if it is positive.
• Double sin(Double a) : Returns the sine of the angle (in radians) given.
• Double sinh(Double x) : Returns the hyperbolic sine of the angle (in radians) given.
• Double sqrt(Double a) : Returns the square root of the given value.
• Double tan(Double a) : Returns the tangent of the angle (in radians) given.
• Double tanh(Double x) : Returns the hyperboli tangent of the angle (in radians) given.
• Double toDegrees(Double angrad) : Returns the angle (given in radians) converted into degrees.
• Double toRadians(Double angdeg) : Returns the angle (given in degrees) converted into radians.

Mathematical constant available

Some frequently used mathematical constants are predefined:

• E : Double which represents the base of natural logarithm. Its value is approximately 2.718281828459045

• PI : Double which represents number π. It is approximately 3.141592653589793

Colour lists

These functions readily provides lists of colours.

colorRange(...)

returns a List of colours from a gradient

Principle: it is to obtain a list of colours by specifying the number of colours and the gradient.

Three syntaxes are possible depending on the way the colour gradient is specified.

Syntax 1:

List<Color> colorRange(Integer number_of_colors, String col1, String col2)

The colour gradient is specified from the two colours col1 and col from which it is interpolated. Different ways of defining a colour are possible:

• "rgb(red,green,blue)" where red, green and blue represent the components of a colour expressed in whole numbers between 0 and 255.
• "rgba(red,green,blue,opacity)" where red, green, blue and opacity represent the components and the opacity of a colour expressed as whole numbers between 0 and 255.
• "#RRGGBB" where RR, GG and BB are the red, green and blue components of the colour expressed in hexadecimal.
• "#RRGGBBAA" where RR, GG, BB and AA are the red, green and blue components of the colour and the opacity expressed in hexadecimal.

Examples: the following definitions are equivalent. They return a variable containing a list of 5 colours representing a gradient between red and yellow. The variables lc1 and lc2 will have the same content.

let lc1 = colorRange(5,"rgb(250,20,20)","rgba(250,250,20,255)")

let lc2 = colorRange(5,"#FA1414","#FAFA14FF")

Syntax 2:

List<Color> colorRange(Integer number_of_colors, String name)

A file named gradients.ocg (in the folder config of your project) contains a series of colour gradient definitions, each with a name. This function allows accessing colour gradients through their names. The gradient is read from left to right, as defined in the file.

Exemple : let lc3 = colorRange(5,"dem")

Syntax 3:

List<Color> colorRange(Integer number_of_colors , String name, Boolean backward)

This syntax is identical to Syntax 2 but the colour gradient can be read from left to right (as defined in the file) or from right to left.

Examples:

let lc4 = colorRange(5,"dem",false) // reads the gradient from left to right

let lc5 = colorRange(5,"dem",true) // reads the gradient from right to left