Functional programming Reference

# Getting started

## Select functional programming profile

To undertake functional programming (FP) in Elan, you should first be reasonably familiar with procedural programming (PP) with Elan, and ideally, with object-oriented programming (OOP) with Elan. Then, switch to the functional profile from the menu at the top of the IDE. This changes two things:

1. The list of demo programs will now show only programs that use FP. A very good place to start is to look at the Snake - functional demo, which is functionally identical to the (procedural) original, but it written using FP design and coding patterns.
2. It will change some of the options available on the new code menus in the editor:
   - Within a function, the only type of instruction that you may add (above the fixed `returnreturnreturnreturnreturn` instruction) is a new instruction named let (plus, of course, comments).
   - Within a concrete or abstract class, you may add function methods, but not procedure methods.
   - Within a concrete or abstract class, there is a new kind of method named a with method. Actually, this is just a template for a specific form of function method which is particularly useful in FP.
   The rationale for disallowing some of the instructions you are used to in PP or OOP, and how to use the new instructions, will become clear as you read through this document.

In the following sections we will describe 10 principles that define the essence of FP, illustrated with example code - where possible from the demo programs.

# Principles of functional programming

Important. Every textbook on FP differs slightly in the definition of core principles, and every language that supports FP differs in the rules that it enforces. The following 10 principles are based on widely recognised best practices in FP. When coding with Elan, in whichever of the supported languages - Python, VB, C#, or Java (or the Elan Reference Language) - these principles are, wherever possible, enforced by the Elan tooling. The resulting code is always valid syntax for the chosen language - but may depend upon common library methods defined in the Elan library. Also, if you go on to write code in any of those languages outside Elan, you will find that the same principles are not necessarily enforced. Though that might appear to offer you more freedom, sticking voluntarily to the principles that you learned in Elan will result in better code and fewer problems.

## Functions must be pure

A pure function observes the following rules:

- The value returned by the function (which may be a data structure) must be derived solely and deterministically from the data provided in parameters. This means it may not depend on data obtained from user input, from a file, or from over the network, though such data may be obtained outside the function and passed into it in parameters.
- Similarly, within the function, you cannot make direct use of the system clock or system-generated random numbers. (There is a technique to generate random numbers  within a function, but this is best left until you have a thorough understanding of the basics of FP.)
- The function may not generate any side effects, that is changes to the state of the system that may be observed outside the function.
- When the function has completed its execution the only legitimate observable effect is its returned value.

Dedicated Functional Programming languages — such as Haskell — enforce these rules automatically. Common 'multi-paradigm' languages — including Python, VB, C#, and Java — do not enforce them. However, if any of those languages are used within Elan, then the Elan editor enforces the rules automatically.

This means that every function you see within Elan, and every function you have ever written within Elan (in Python, VB, C#, or Java), is a pure function. That is the reason why, even when you are using the procedural or object-oriented profiles and you are within a function, you cannot print or call a procedure, nor can you make use of system methods such as input, random, or clock. This experience gives you a huge advantage in transitioning to FP.

## As much of the code as possible should be in functions

When using FP in Python, VB, C#, or Java, every program still needs a main routine, which is necessarily procedural in nature, because it cannot work without dependencies on the system, and it generates side effects such as output to a display.

To avoid your main routine becoming difficult to read, and to avoid duplicated code, you may still define procedures (which also, inherently, use procedural programming to manage input/output and other system operations). But this second principle of FP implies that the main together with any necessary procedures should be kept as small as possible:

Any code within the main routine or procedures that performs calculation, evaluates logic, or transforms data in any way, should be delegated to functions.

Most procedural programs contain some functions, but a program written within the discipline of FP should consist almost entirely of functions.

This may seem logical when a program is obviously heavily dependent upon calculation, logic, or data transformation — as, for example, the Best Fit and Wordle solver demo programs. But what about an interactive game, where most of the logic is concerned with managing the user input and the display? Consider the two demo programs: Snake - procedural and Snake - procedural. The two programs behave identically when run. We recommend that you take the time to explore the these two programs in detail,but here's a summary of the key differences:

| Snake - procedural | Snake - functional
--- | --- | ---
Total instructions, excluding tests | 72 | 115
Number of procedures, including main | 4 | 1
Number of functions | 4 | 21 (incl. function methods within Classes)
Instructions within procedures, including main | 47 = 65% | 11 = 10%
Instructions within functions | 25 = 35% | 104 = 90%

## Every function can and should be unit tested

The idea of writing automated tests isn't restricted to Functional Programming. The tests offered by Elan are known as 'unit tests', and are designed to test functions.

Such tests are extremely easy to write, and run automatically when the program is loaded from a file, and then run again after every edit that results in code that compiles.

Unit tests give you huge confidence that your code does what it is supposed to do, and that subsequent changes, whether as a result of debugging or of implementing new requirements, do not break existing functionality. Without unit tests, bugs might go unnoticed and surface only later and less obviously.

On some platforms it is possible to write automated tests that also cover procedures (including the main routine). These are sometimes referred to as 'end to end tests', or 'UI tests' because they can simulate a user interacting with the program. But such tests are much harder to write than unit tests, and notoriously 'brittle' — meaning that a tiny change to code can break many existing tests and take hours to fix. Changes external to your program, such as a routine upgrade to the browser or operating system, can easily render such tests invalid. Elan does not currently support those kind of tests.

Note, however, that outside Elan, Python, VB, C#, and Java, have unit testing frameworks that can theoretically allow unit tests to run any method. This can be dangerous because running the tests might, without your awareness, be updating a file or database, or sending Internet messages. Unit tests are safe only when applied to safe (i.e. pure) functions.

It follows that the higher the percentage of a program's total instructions that exist within functions, the higher the percentage of your code that can be safely unit tested. The table below shows the percentage of instructions covered by tests for two of the demo programs that offer both procedural and functional implementations. You can verify this information by examining the demo code.

| Snake - procedural | Snake - functional | Life - procedural | Life - functional
--- | --- | --- | --- | ---
Total instructions, excluding tests | 72 | 115 | 78 | 76
Instructions covered by tests | 53% | 90% | 73% | 90%

### Note on demo program Best Fit

- The Best Fit demo defines a function and a Class for use in other programs. It has no main instruction, so comparison with the the unit testing in other programs would be misleading. The function and the operation of the Class are both 100% tested.

## The function body should consists of a 'return', plus optional let instructions only

In the FP demos you will see that a significant number of functions that simply `returnreturnreturnreturnreturn` an expression to be evaluated, for example:

+function gameOver name?(g as Game parameter definitions?) returns Boolean Type? 1 return g.body.contains(g.head) or hasHitEdge(g)value or expression?2 end function
+def gameOver name?(g: Game parameter definitions?) -> bool Type?: # function 1 return g.body.contains(g.head) or hasHitEdge(g)value or expression?2
+static bool Type? gameOver name?(Game g parameter definitions?) { // function 1 return g.body.contains(g.head) || hasHitEdge(g)value or expression?;2 } // function
+Function gameOver name?(g As Game parameter definitions?) As Boolean Type? 1 Return g.body.contains(g.head) Or hasHitEdge(g)value or expression?2 End Function
public class Global {
+static bool Type? gameOver name?(Game g parameter definitions?) { // function 1 return g.body.contains(g.head) || hasHitEdge(g)value or expression?;2 } // function
}

Other functions precede the `returnreturnreturnreturnreturn` by one or more let statements, for example

+function hasHitEdge name?(g as Game parameter definitions?) returns Boolean Type? 1 let x name? be g.head.x value or expression?2 let y name? be g.head.y value or expression?3 return (x is -1) or (y is -1) or (x is 40) or (y is 30)value or expression?4 end function
+def hasHitEdge name?(g: Game parameter definitions?) -> bool Type?: # function 1 x name? = g.head.x value or expression? # let 2 y name? = g.head.y value or expression? # let 3 return (x == -1) or (y == -1) or (x == 40) or (y == 30)value or expression?4
+static bool Type? hasHitEdge name?(Game g parameter definitions?) { // function 1 var x name? = g.head.x value or expression?; // let 2 var y name? = g.head.y value or expression?; // let 3 return (x == -1) || (y == -1) || (x == 40) || (y == 30)value or expression?;4 } // function
+Function hasHitEdge name?(g As Game parameter definitions?) As Boolean Type? 1 Dim x name? = g.head.x value or expression? ' let 2 Dim y name? = g.head.y value or expression? ' let 3 Return (x = -1) Or (y = -1) Or (x = 40) Or (y = 30)value or expression?4 End Function
public class Global {
+static bool Type? hasHitEdge name?(Game g parameter definitions?) { // function 1 var x name? = g.head.x value or expression?; // let 2 var y name? = g.head.y value or expression?; // let 3 return (x == -1) || (y == -1) || (x == 40) || (y == 30)value or expression?;4 } // function
}

A let statement works like a variable definition except that the named value created may not be reassigned. This may sound like a local constant, but a let statement differs from a constant in that:

- it may be defined by an expression rather than just by a literal value
- it may refer to a List or other data structure, where as the (global) constant instruction is limited to simple value types or a string.

In the four languages supported by Elan, let instructions are really just disguised variable definitions, executed sequentially. But in a pure FP language such as Haskell, OCAML, or F#, let instructions (some languages have 'let clauses') are executed lazily, meaning that execution of a function starts by evaluating the returned expression, and evaluates the sub-expressions defined in let instructions only when or if they are needed. So getting used to using let instructions in Elan leaves you better prepared to move onto a pure FP language at a future point.

A let statement defines a 'sub-expression' that will be used in another expression, for one (or more) of these reasons:

- To make a long expression easier to read
- To eliminate duplication — where the same sub-expression otherwise appears in full in more than one place.
- Within a test, because the 'actual' field does not support 'chained' expressions (expressions containing more than one 'dot')

When running in the functional profile, let statement is the only type of instruction that you may add within a function, and the only type in addition to an assert that may be added into a test. (You can still, of course, add comments.)

## Selection is implemented using 'conditional expressions'

When running in the Functional profile, you cannot add an if instruction into a function. Selection is handled by means of a 'conditional expression'.

All of the languages supported by Elan have their own custom syntax for conditional expressions. For simplicity, and understandability, Elan offers an if function that is used identically in all the languages. (Incidentally, the if function works the same way as it does in an Excel spreadsheet). Here are some examples of conditional expressions from the demo programs:

+function betterOf name?(wc1 as WordCount, wc2 as WordCount, possAnswers as List<of String>parameter definitions?) returns WordCount Type? 1 let isBetter name? be wc2.count < wc1.count value or expression?2 let isEqualAndPossAnswer name? be (wc2.count is wc1.count) and possAnswers.contains(wc2.word)value or expression?3 return if(isBetter or isEqualAndPossAnswer, wc2, wc1)value or expression?4 end function
+def betterOf name?(wc1: WordCount, wc2: WordCount, possAnswers: list[str]parameter definitions?) -> WordCount Type?: # function 1 isBetter name? = wc2.count < wc1.count value or expression? # let 2 isEqualAndPossAnswer name? = (wc2.count == wc1.count) and possAnswers.contains(wc2.word)value or expression? # let 3 return if(isBetter or isEqualAndPossAnswer, wc2, wc1)value or expression?4
+static WordCount Type? betterOf name?(WordCount wc1, WordCount wc2, List<string> possAnswers parameter definitions?) { // function 1 var isBetter name? = wc2.count < wc1.count value or expression?; // let 2 var isEqualAndPossAnswer name? = (wc2.count == wc1.count) && possAnswers.contains(wc2.word)value or expression?; // let 3 return if(isBetter || isEqualAndPossAnswer, wc2, wc1)value or expression?;4 } // function
+Function betterOf name?(wc1 As WordCount, wc2 As WordCount, possAnswers As List(Of String)parameter definitions?) As WordCount Type? 1 Dim isBetter name? = wc2.count < wc1.count value or expression? ' let 2 Dim isEqualAndPossAnswer name? = (wc2.count = wc1.count) And possAnswers.contains(wc2.word)value or expression? ' let 3 Return if(isBetter Or isEqualAndPossAnswer, wc2, wc1)value or expression?4 End Function
public class Global {
+static WordCount Type? betterOf name?(WordCount wc1, WordCount wc2, List<String> possAnswers parameter definitions?) { // function 1 var isBetter name? = wc2.count < wc1.count value or expression?; // let 2 var isEqualAndPossAnswer name? = (wc2.count == wc1.count) && possAnswers.contains(wc2.word)value or expression?; // let 3 return if(isBetter || isEqualAndPossAnswer, wc2, wc1)value or expression?;4 } // function
}
+function nextCellValue name?(grid as List<of List<of Int>>, x as Int, y as Int parameter definitions?) returns Int Type? 1 let live name? be willLive(grid[x][y], liveNeighbours(grid, x, y))value or expression?2 return if(live, black, white)value or expression?3 end function
+def nextCellValue name?(grid: list[list[int]], x: int, y: int parameter definitions?) -> int Type?: # function 1 live name? = willLive(grid[x][y], liveNeighbours(grid, x, y))value or expression? # let 2 return if(live, black, white)value or expression?3
+static int Type? nextCellValue name?(List<List<int>> grid, int x, int y parameter definitions?) { // function 1 var live name? = willLive(grid[x][y], liveNeighbours(grid, x, y))value or expression?; // let 2 return if(live, black, white)value or expression?;3 } // function
+Function nextCellValue name?(grid As List(Of List(Of Integer)), x As Integer, y As Integer parameter definitions?) As Integer Type? 1 Dim live name? = willLive(grid[x][y], liveNeighbours(grid, x, y))value or expression? ' let 2 Return if(live, black, white)value or expression?3 End Function
public class Global {
+static int Type? nextCellValue name?(List<List<int>> grid, int x, int y parameter definitions?) { // function 1 var live name? = willLive(grid[x][y], liveNeighbours(grid, x, y))value or expression?; // let 2 return if(live, black, white)value or expression?;3 } // function
}

The if function requires three arguments to be provided, in the following order:

1. The condition, which may compare two values, or it may call another function that returns a Boolean value
2. The value to be returned by the if function when the condition evaluates to true
3. The value to be returned by the if function when the condition evaluates to false

Thus the if function performs a role somewhat similar to an if instruction, but differs from it in these important respects:

- The if function is not an instruction: it forms part, or all, of an expression and may be used within any expression that forms part of an instruction.
- It returns a value, which must be used.
- It may make use of other expressions to define the arguments, but may not contain other instructions.

Although if functions can be nested, nesting to more than one level can become very hard to read. When required, it is often better to delegate to a new function to perform part of the logic.

## Iteration may be achieved using recursion

There are two ways to implement iteration within a function:

Either by using 'recursion', i.e. a recursive function (described here), or by the approach described in later.

A recursive function is one that at some point evaluates itself, and is best understood by example. In the Recursive Functions demo, the factorial function is a good place to start:

+function factorial name?(n as Int parameter definitions?) returns Int Type? 1 return if(n < 2, 1, n*factorial(n - 1))value or expression?2 end function
+def factorial name?(n: int parameter definitions?) -> int Type?: # function 1 return if(n < 2, 1, n*factorial(n - 1))value or expression?2
+static int Type? factorial name?(int n parameter definitions?) { // function 1 return if(n < 2, 1, n*factorial(n - 1))value or expression?;2 } // function
+Function factorial name?(n As Integer parameter definitions?) As Integer Type? 1 Return if(n < 2, 1, n*factorial(n - 1))value or expression?2 End Function
public class Global {
+static int Type? factorial name?(int n parameter definitions?) { // function 1 return if(n < 2, 1, n*factorial(n - 1))value or expression?;2 } // function
}

It shows these important aspects of designing a recursive function:

- When the function is called within the function body it is typically with a smaller version of the original problem: in this case `factorial(n)factorial(n)factorial(n)factorial(n)factorial(n)` calculates `factorial(n - 1)factorial(n - 1)factorial(n - 1)factorial(n - 1)factorial(n - 1)` and multiplies it by `nnnnn`.
- The recursion must 'bottom out' eventually, and this must be explicitly checked for. In this case it bottoms out when `nnnnn` is less than `22222`, because 0! and 1! are both 1. The most common error when writing a recursive function is forgetting to define and check for the bottoming-out condition. If you fail to do this, for example by writing `return n*factorial(n - 1) Code does not parse as Elan.return n*factorial(n - 1) Code does not parse as Elan.return n*factorial(n - 1) Code does not parse as Elan.return n*factorial(n - 1) Code does not parse as Elan.return n*factorial(n - 1) Code does not parse as Elan.` — or you get the condition wrong — the iteration will continue indefinitely until you eventually get a 'Stack overflow error', which crashes the program. Try it so that you learn to recognise and diagnose the potential problem.

## Lists and other data structures are never mutated

In procedural programming a List may be mutated either by reassigning an indexed value, for example:

reassign mySubjects[3]variableName? to "Geography"value or expression?0
mySubjects[3]variableName? = "Geography"value or expression? # reassign variable 0
mySubjects[3]variableName? = "Geography"value or expression?; // reassign variable 0
mySubjects[3]variableName? = "Geography"value or expression? ' reassign variable 0
mySubjects[3]variableName? = "Geography"value or expression?; // reassign variable 0
or by calling one of the available procedure methods on on it such as:
call mySubjects.append procedureName?("Music"arguments?)0
mySubjects.append procedureName?("Music"arguments?) # call procedure 0
mySubjects.append procedureName?("Music"arguments?); // call procedure 0
mySubjects.append procedureName?("Music"arguments?) ' call procedure 0
mySubjects.append procedureName?("Music"arguments?); // call procedure 0
but in FP this is not permitted. Data structures are never to be mutated. Instead, you may call a function that returns a copy of a data structure with specified differences from the original. For example, you may write:
let myNewSubjects be mySubjects.withSet(3, "Geography") Code does not parse as Elan.
let myNewSubjects be mySubjects.withSet(3, "Geography") Code does not parse as Elan.
let myNewSubjects be mySubjects.withSet(3, "Geography") Code does not parse as Elan.
let myNewSubjects be mySubjects.withSet(3, "Geography") Code does not parse as Elan.
let myNewSubjects be mySubjects.withSet(3, "Geography") Code does not parse as Elan.
or
let myNewSubjects be mySubjects.withAppend("Music") Code does not parse as Elan.
let myNewSubjects be mySubjects.withAppend("Music") Code does not parse as Elan.
let myNewSubjects be mySubjects.withAppend("Music") Code does not parse as Elan.
let myNewSubjects be mySubjects.withAppend("Music") Code does not parse as Elan.
let myNewSubjects be mySubjects.withAppend("Music") Code does not parse as Elan.

At first sight this may seem awkward, strange and certainly inefficient. But though you might never have thought about it in these terms, this is what you have always done when manipulating a `StringstrstringStringString`. You can never actually mutate a string, such as converting it to upper case or trimming off the leading spaces. You have to write, for example:

let myNewString be myString.upperCase() Code does not parse as Elan.
let myNewString be myString.upperCase() Code does not parse as Elan.
let myNewString be myString.upperCase() Code does not parse as Elan.
let myNewString be myString.upperCase() Code does not parse as Elan.
let myNewString be myString.upperCase() Code does not parse as Elan.

When you want to apply operations to all items in a List you need to use iteration, which means using either recursion  or Higher-order Functions  and within that technique make use of the various with.. methods. The sum function in the Recursive Functions demo calculates the sum of all items in any List of floating point numbers (the tests included in the demo show example results):

+function sum name?(li as List<of Float>parameter definitions?) returns Float Type? 1 return if(li.length() is 0, 0.0, li.head() + sum(li.tail()))value or expression?2 end function
+def sum name?(li: list[float]parameter definitions?) -> float Type?: # function 1 return if(li.length() == 0, 0.0, li.head() + sum(li.tail()))value or expression?2
+static double Type? sum name?(List<double> li parameter definitions?) { // function 1 return if(li.length() == 0, 0.0, li.head() + sum(li.tail()))value or expression?;2 } // function
+Function sum name?(li As List(Of Double)parameter definitions?) As Double Type? 1 Return if(li.length() = 0, 0.0, li.head() + sum(li.tail()))value or expression?2 End Function
public class Global {
+static double Type? sum name?(List<double> li parameter definitions?) { // function 1 return if(li.length() == 0, 0.0, li.head() + sum(li.tail()))value or expression?;2 } // function
}

Note the use of these two dot function calls on the List `lilililili`(see Dot syntax  in Language Reference):

- head returns only the first item in the List.
- tail returns all the items of the List except the first.

In FP, algorithms to process lists are often written in terms of the 'head' and 'tail' of the list. You could just write e.g. `li[0]li[0]li[0]li[0]li[0]` and `li.substring(1, li.length())li.substring(1, li.length())li.substring(1, li.length())li.substring(1, li.length())li.substring(1, li.length())` instead, with the same result. But using the head and tail methods makes your code easier to read and may make your intention clearer.

The next example combines the previous two ideas:

- updating a List by using a with.. method to create a copy of the original List with specified differences.
- using recursion to iterate over the items in the List.

in a function to reverse the order or items in a List:
+function reverse name?(li as List<of Float>parameter definitions?) returns List<of Float>Type? 1 return if(li.length() < 2, li, reverse(li.tail()).withAppend(li.head()))value or expression?2 end function
+def reverse name?(li: list[float]parameter definitions?) -> list[float]Type?: # function 1 return if(li.length() < 2, li, reverse(li.tail()).withAppend(li.head()))value or expression?2
+static List<double>Type? reverse name?(List<double> li parameter definitions?) { // function 1 return if(li.length() < 2, li, reverse(li.tail()).withAppend(li.head()))value or expression?;2 } // function
+Function reverse name?(li As List(Of Double)parameter definitions?) As List(Of Double)Type? 1 Return if(li.length() < 2, li, reverse(li.tail()).withAppend(li.head()))value or expression?2 End Function
public class Global {
+static List<double>Type? reverse name?(List<double> li parameter definitions?) { // function 1 return if(li.length() < 2, li, reverse(li.tail()).withAppend(li.head()))value or expression?;2 } // function
}

A more advanced example is the Merge Sort demo, where:

- the principal function (sort) defines the algorithm in just one line, delegating to other, simpler functions. This is a very good example of 'functional decomposition', that is defining a function in terms of other functions each of which does part of the task.
- as well as testing the principal function, there are unit tests for each of the component functions. This builds confidence and makes debugging simpler. (Recursive functions can be hard to debug otherwise.)
- At first glance, none of the functions appears to be recursive because none of them calls itself directly. However, as you study the code you will see that sort calls sortedFrontHalf and sortedBackHalf both of which call back into sort again — crucially with approximately half of the original List. The same pattern exists between merge and mergeNonEmpty.

## A function may be passed into another function

The alternative to writing your own recursive function is to use Higher-order Functions (see HoFs  in Library Reference). A HoF is a function that takes in another function as a parameter. (Strictly speaking, a HoF may also be a function that returns another function, but Elan does not currently support that pattern.) Under the covers, HoFs are written using recursion, but you don't see this.

There are many possible HoFs, but three of them — filter, map and reduce — are so widely used to process lists in FP, and in many different ways, that they are sometimes referred to as the 'Holy Trinity of Functional Programming'. They can be used individually or in combination. The purpose and operation of each is explained below.

All of the languages supported by Elan have their own versions of filter, map and reduce that are similar in intent but have differing syntax, and sometimes different names (e.g. 'fold' in place of 'reduce').The Elan library has its own version of these functions which work the same way in each language.

Start by loading and running the demo program Map, Filter, Reduce, and look at the test:

+test test_Map_Filter_Reduce test_name? 1 let nums name? be [2.22, 5.37, 8.97, 7.53, 8.2, 9.43, 7.74, 7.03, 9.62, 2.5]value or expression?2 assert nums.filter(lessThan5)actual (computed) value? is [2.22, 2.5]expected value? not run 3 assert nums.map(cube)actual (computed) value? is [10.94, 154.85, 721.73, 426.96, 551.37, 838.56, 463.68, 347.43, 890.28, 15.63]expected value? not run 4 assert nums.reduce(1.0, product).floor()actual (computed) value? is 81480107 expected value? not run 5 assert nums.filter(lessThan5).map(inverse)actual (computed) value? is [0.45, 0.4]expected value? not run 6 assert nums.filter(lessThan5).map(inverse).map(toString).reduce("results: ", concat)actual (computed) value? is "results: 0.45|0.4|"expected value? not run 7 end test
+def test_Map_Filter_Reduce test_name?(self) -> None: 1 nums name? = [2.22, 5.37, 8.97, 7.53, 8.2, 9.43, 7.74, 7.03, 9.62, 2.5]value or expression? # let 2 self.assertEqual(nums.filter(lessThan5)actual (computed) value?, [2.22, 2.5]expected value?) not run 3 self.assertEqual(nums.map(cube)actual (computed) value?, [10.94, 154.85, 721.73, 426.96, 551.37, 838.56, 463.68, 347.43, 890.28, 15.63]expected value?) not run 4 self.assertEqual(nums.reduce(1.0, product).floor()actual (computed) value?, 81480107 expected value?) not run 5 self.assertEqual(nums.filter(lessThan5).map(inverse)actual (computed) value?, [0.45, 0.4]expected value?) not run 6 self.assertEqual(nums.filter(lessThan5).map(inverse).map(toString).reduce("results: ", concat)actual (computed) value?, "results: 0.45|0.4|"expected value?) not run 7
+[TestMethod] static void test_Map_Filter_Reduce test_name?() { 1 var nums name? = [2.22, 5.37, 8.97, 7.53, 8.2, 9.43, 7.74, 7.03, 9.62, 2.5]value or expression?; // let 2 Assert.AreEqual([2.22, 2.5]expected value?, nums.filter(lessThan5)actual (computed) value?); not run 3 Assert.AreEqual([10.94, 154.85, 721.73, 426.96, 551.37, 838.56, 463.68, 347.43, 890.28, 15.63]expected value?, nums.map(cube)actual (computed) value?); not run 4 Assert.AreEqual(81480107 expected value?, nums.reduce(1.0, product).floor()actual (computed) value?); not run 5 Assert.AreEqual([0.45, 0.4]expected value?, nums.filter(lessThan5).map(inverse)actual (computed) value?); not run 6 Assert.AreEqual("results: 0.45|0.4|"expected value?, nums.filter(lessThan5).map(inverse).map(toString).reduce("results: ", concat)actual (computed) value?); not run 7 } // test
+<TestMethod> Sub test_Map_Filter_Reduce test_name?() 1 Dim nums name? = {2.22, 5.37, 8.97, 7.53, 8.2, 9.43, 7.74, 7.03, 9.62, 2.5}value or expression? ' let 2 Assert.AreEqual({2.22, 2.5}expected value?, nums.filter(lessThan5)actual (computed) value?) not run 3 Assert.AreEqual({10.94, 154.85, 721.73, 426.96, 551.37, 838.56, 463.68, 347.43, 890.28, 15.63}expected value?, nums.map(cube)actual (computed) value?) not run 4 Assert.AreEqual(81480107 expected value?, nums.reduce(1.0, product).floor()actual (computed) value?) not run 5 Assert.AreEqual({0.45, 0.4}expected value?, nums.filter(lessThan5).map(inverse)actual (computed) value?) not run 6 Assert.AreEqual("results: 0.45|0.4|"expected value?, nums.filter(lessThan5).map(inverse).map(toString).reduce("results: ", concat)actual (computed) value?) not run 7 End Sub
public class Global {
+@Test static void test_Map_Filter_Reduce test_name?() { 1 var nums name? = [2.22, 5.37, 8.97, 7.53, 8.2, 9.43, 7.74, 7.03, 9.62, 2.5]value or expression?; // let 2 assertEquals([2.22, 2.5]expected value?, nums.filter(lessThan5)actual (computed) value?); not run 3 assertEquals([10.94, 154.85, 721.73, 426.96, 551.37, 838.56, 463.68, 347.43, 890.28, 15.63]expected value?, nums.map(cube)actual (computed) value?); not run 4 assertEquals(81480107 expected value?, nums.reduce(1.0, product).floor()actual (computed) value?); not run 5 assertEquals([0.45, 0.4]expected value?, nums.filter(lessThan5).map(inverse)actual (computed) value?); not run 6 assertEquals("results: 0.45|0.4|"expected value?, nums.filter(lessThan5).map(inverse).map(toString).reduce("results: ", concat)actual (computed) value?); not run 7 } // test
}

Each of the three HoFs is applied to a List by a 'dot method call'. In this example each is applied to the same List (of floating point numbers), though the subject List may be of any Type. Because they are all dot methods, they can easily be chained in dot sequences, as shown.

Each HoF is passed the name of a function that is defined elsewhere in the program. The function name is given as an argument, without brackets or arguments, e.g. lessThan5. For filter and map, this is the only argument; for reduce there is another argument. Taking each HoF in turn:

filter

- returns a List that is made up of selected items from the original List. The function passed into filter is applied to each of the List's items in turn, and determines whether or not each should 'pass' through the filter into the resulting List. In the first example the function passes only those values from the original List that are less than 5.
- the definition of the function lessThan5 (lower down in the code) includes a parameter of type `FloatfloatdoubleDoubledouble` (the same type as of the item in the List) but returns a `BooleanboolboolBooleanbool` specifying whether or not a specific item should pass the filter. Making sure that Types match up as expected can be the trickiest part of learning to use HoFs.

map

- returns a List that will have the same number of items as in the original List. They might be of the same type as the in the original List (though typically different values) or, depending on the return type of the function passed in, the items in the resulting List might be of a type different from those in the original List. But each item in the resulting List corresponds ('maps') to an item of the original List at the same position
- as with filter, the function passed into map must have a single parameter of the same type as the items in the List, though its return value may be of any Type.

reduce

- returns a single value, that is derived by combining all of the item values in the original List according to the function passed in. That derived value can be of the same Type as the items of the List (for example when used to combine a List of numbers by addition or multiplication), but can be of a different type including a data structure.
- Unlike filter and map, reduce requires two arguments:
  1. the initial value (sometimes called the 'seed') that will be progressively refined and eventually returned. This initial value must therefore have the type of the desired final value.
  2. the function passed into reduce must define two parameters:
     1. the accumulating value, therefore of the same type as the initial 'seed' value.
     2. the item to which the function is applied, therefore of the same type as the items in the List.
- The return type of the function must have the same type as the 'seed' value.
- Each item of the List is passed in turn into the function (as second argument), the first argument being the latest value that has developed from the seed.

filter and map methods may be chained, and in any order, provided that the item type of each resulting List is of the type expected by the next one.

Because reduce transforms a List into a single value, it is typically used in isolation or as the last of a chain. It can, of course, be followed in the chain by a simpler function (such as round).

### Lambdas

In the examples above the function being passed into the HoF (using its name) is defined as a 'standalone' (global) function elsewhere in the program. This pattern has two advantages:>/p>

- The function may be used elsewhere in the program, either to pass into a another HoF, or in the same way as any other function.
- The function can be tested in isolation.

However, there are many circumstances where the function you need to pass into a HoF, is unlikely to be used in any different context, and where the function is so simple that it hardly warrants its own test — especially if the whole expression that uses the HoF is being tested.

A lambda is a function that is defined 'inline' as an argument in a function call. For example, the expression from the example above:

nums.filter(lessThan5)
nums.filter(lessThan5)
nums.filter(lessThan5)
nums.filter(lessThan5)
nums.filter(lessThan5)
could be written as:
nums.filter(lambda x as Int => x < 5)
nums.filter(lambda x: int: x < 5)
nums.filter(int x => x < 5)
nums.filter(Function (x As Integer) x < 5)
nums.filter((int x) -> x < 5)

thereby eliminating the need to define the lessThan5 function for one use only.

There is a whole branch of mathematics devoted to 'lambda calculus', which in turn provided the theoretical underpinning for the concept of function programming (FP). And lambdas have capabilities that are both more subtle and more sophisticated than can be described here, including the idea of 'closure' (which you can look up if you are ready to go much deeper — and which is supported in Elan). However, you should note that, because of the need for compatibility across all the supported languages, Elan has a restricted implementation of HoFs and of 'function passing' in general, but it is sufficient to grasp the key principles of Functional Programming. To go further you would need to switch to a pure FP language such as Haskell. Currently Elan does not permit (in any of the supported languages):

- The definition of a lambda except inline as the argument to a HoF. You cannot, for example, assign a lambda (or a function) to a variable.
- The definition of your own HoFs — you are restricted to using the HoFs defined in the Elan library.

### Using HoFs to iterate over a 2D List

If you are using Elan's Block Graphics, or have another need to process a 2D List (such as working with matrices or tabular data), and you want to do this in pure functions, you have the challenge of how to iterate over two dimensions — something that is straightforward in procedural programming by means of 'nested loops'. It is certainly possible to iterate over two dimensions of a List using HoFs within a single expression, but until you are fluent in such programming, the recommended approach is to break up the task into an 'inner' function that processes just a single column (or row, if preferred) of the 2D structure and an 'outer' function that processes each of the columns (or rows).

This is exemplified in the following functions, taken from the Life - functional demo, which together perform a role equivalent to the nextGeneration procedure in the Life - procedural demo:

+function nextGeneration name?(grid as List<of List<of Int>>parameter definitions?) returns List<of List<of Int>>Type? 1 let cols name? be range(0, 40)value or expression?2 return cols.map(lambda x as Int => nextCol(grid, x))value or expression?3 end function +function nextCol name?(grid as List<of List<of Int>>, x as Int parameter definitions?) returns List<of Int>Type? 4 let col name? be grid[x]value or expression?5 let rows name? be range(0, 30)value or expression?6 return rows.map(lambda y as Int => nextCellValue(grid, x, y))value or expression?7 end function
+def nextGeneration name?(grid: list[list[int]]parameter definitions?) -> list[list[int]]Type?: # function 1 cols name? = range(0, 40)value or expression? # let 2 return cols.map(lambda x: int: nextCol(grid, x))value or expression?3 +def nextCol name?(grid: list[list[int]], x: int parameter definitions?) -> list[int]Type?: # function 4 col name? = grid[x]value or expression? # let 5 rows name? = range(0, 30)value or expression? # let 6 return rows.map(lambda y: int: nextCellValue(grid, x, y))value or expression?7
+static List<List<int>>Type? nextGeneration name?(List<List<int>> grid parameter definitions?) { // function 1 var cols name? = range(0, 40)value or expression?; // let 2 return cols.map(int x => nextCol(grid, x))value or expression?;3 } // function +static List<int>Type? nextCol name?(List<List<int>> grid, int x parameter definitions?) { // function 4 var col name? = grid[x]value or expression?; // let 5 var rows name? = range(0, 30)value or expression?; // let 6 return rows.map(int y => nextCellValue(grid, x, y))value or expression?;7 } // function
+Function nextGeneration name?(grid As List(Of List(Of Integer))parameter definitions?) As List(Of List(Of Integer))Type? 1 Dim cols name? = range(0, 40)value or expression? ' let 2 Return cols.map(Function (x As Integer) nextCol(grid, x))value or expression?3 End Function +Function nextCol name?(grid As List(Of List(Of Integer)), x As Integer parameter definitions?) As List(Of Integer)Type? 4 Dim col name? = grid[x]value or expression? ' let 5 Dim rows name? = range(0, 30)value or expression? ' let 6 Return rows.map(Function (y As Integer) nextCellValue(grid, x, y))value or expression?7 End Function
public class Global {
+static List<List<int>>Type? nextGeneration name?(List<List<int>> grid parameter definitions?) { // function 1 var cols name? = range(0, 40)value or expression?; // let 2 return cols.map((int x) -> nextCol(grid, x))value or expression?;3 } // function +static List<int>Type? nextCol name?(List<List<int>> grid, int x parameter definitions?) { // function 4 var col name? = grid[x]value or expression?; // let 5 var rows name? = range(0, 30)value or expression?; // let 6 return rows.map((int y) -> nextCellValue(grid, x, y))value or expression?;7 } // function
}

Note the use of range in both functions to create `colscolscolscolscols` and `rowsrowsrowsrowsrows` respectively, which are just Lists of numbers e.g. [0, 1, 2, .. , 39]. The map HoFs iterate over these column and row numbers using them to access the appropriate portions of the `gridgridgridgridgrid`, which is a 2D `List<of List<of Int>>list[list[int]]List<List<int>>List(Of List(Of Integer))List<List<int>>`.

## User-defined Classes should be immutable

It is possible, indeed highly desirable, to have user-defined Types (i.e. Classes) in FP. However, in true FP, an instance of a Class would never be mutated. So, when running under the functional profile, you may define Classes and add properties and function methods, but you may not define any procedure method. (In Object-oriented Programming you would use procedure methods to mutate an instance or do anything that cannot be done by a function.)

But this raises a question: how are we to make changes to an instance of a Class?. The answer is similar to that for updating a List, String, or other standard data structure within a function (described in earlier): you need define with.. methods that return a copy of the instance with specified changes. For example, in the Snake - functional demo, the Class `GameGameGameGameGame` has several with.. methods, one of which is shown here:

+function withHead name?(value as Square parameter definitions?) returns Game Type? 1 let copyOfThis name? be copy(this)value or expression?2 reassign copyOfThis.head variableName? to value value or expression?3 return copyOfThis value or expression?4 end function
+def withHead name?(value: Square parameter definitions?) -> Game Type?: # function 1 copyOfThis name? = copy(self)value or expression? # let 2 copyOfThis.head variableName? = value value or expression? # reassign variable 3 return copyOfThis value or expression?4
+static Game Type? withHead name?(Square value parameter definitions?) { // function 1 var copyOfThis name? = copy(this)value or expression?; // let 2 copyOfThis.head variableName? = value value or expression?; // reassign variable 3 return copyOfThis value or expression?;4 } // function
+Function withHead name?(value As Square parameter definitions?) As Game Type? 1 Dim copyOfThis name? = copy(Me)value or expression? ' let 2 copyOfThis.head variableName? = value value or expression? ' reassign variable 3 Return copyOfThis value or expression?4 End Function
public class Global {
+static Game Type? withHead name?(Square value parameter definitions?) { // function 1 var copyOfThis name? = copy(this)value or expression?; // let 2 copyOfThis.head variableName? = value value or expression?; // reassign variable 3 return copyOfThis value or expression?;4 } // function
}
Note that it:

- returns a `GameGameGameGameGame` (i.e. a Class instance)
- creates a copy (i.e. a new instance) of `thisthisthisthisthis` (instance) named `copyOfThiscopyOfThiscopyOfThiscopyOfThiscopyOfThis`
- reassigns the property `headheadheadheadhead` of `copyOfThiscopyOfThiscopyOfThiscopyOfThiscopyOfThis` to the new value
- returns the updated `copyOfThiscopyOfThiscopyOfThiscopyOfThiscopyOfThis` (instance)

Although a with.. method is a pure function, the standard form of a with.. method, like the one above, must be created using the with method instruction template, which is offered only within a Class, and only when using the functional profile.

The reason is that only within the with.. method are you allowed to reassign a property, and this may only be on the a value named `copyOfThiscopyOfThiscopyOfThiscopyOfThiscopyOfThis`. You cannot, for example, edit it to say e.g. `reassign this.xvariableName? to valuevalue or expression?0self.xvariableName? = valuevalue or expression? # reassign variable0this.xvariableName? = valuevalue or expression?; // reassign variable0Me.xvariableName? = valuevalue or expression? ' reassign variable0this.xvariableName? = valuevalue or expression?; // reassign variable0`, since that would make changes observable from outside the function.

Note, in the same demo, that the Class `SquareSquareSquareSquareSquare` does not define any with.. methods because there is no need within the program to update any instance of Square — instead, a new instance is created, specifying the `xxxxx` and `yyyyy` coordinates as needed. For this reason the method named withNewApple does not need to be able to reassign a property on a copy, but does need to do other work. It has been written using the standard function method instruction template.

## Generating Random numbers within a function requires a special pattern

Warning: This is an advanced technique and we recommend not attempting to use it until you are fairly comfortable with all the previous Principles.

In procedural programming you use the 'system methods' random (for a floating point number in the range 0 to 1) or randInt for an integer in a specified range. You may use these system methods within the main routine or a procedure, and you may pass these random values into a function, but you may not generate one or more random values within a function. When writing games and simulations that rely heavily on generating random numbers this can make it very difficult to achieve the primary objective of doing all data transformations within functions. Fortunately, there is a mechanism to generate random numbers within functions. Before looking at how to use it, it is important to understand the following:

- A small number of computers have dedicated hardware that generates true random numbers using advanced physics such as quantum effects or radioactive decay. Most computers, however, rely on 'pseudo random number' generation. This is where the next random number is derived from the previous one, but in such a way that for most practical purposes the results may be considered random.
- When you use the standard random or randInt system methods, the 'system' is keeping track of the previously generated numbers and using them to generate the next ones. This means that your code that uses them is dependent upon state of the system as a whole.
- A function has to be 'deterministic' in that its returned value must depend solely on the values provided as arguments; for a given set of argument values, a function must always return the same result. Its result cannot be dependent upon the current date, time or what the system has done previously. A function that was given all such information in its parameters would make it extremely complicated and unwieldy!

The 'functional Random' pattern, works within these constraints. If you want to generate one or more random numbers within a function, you must pass in the 'state' needed to derive that next random value, and you must pass the updated state to the next place where a new random is required, either inside or outside the function. This is done using an instance of the type `RandomRandomRandomRandomRandom` (note the capital R, which distinguishes this from the procedural methods) which may be thought of as an instance of a 'Random Number Generator'.

To see how `RandomRandomRandomRandomRandom` works, we will first explore it within a tiny program intended to show the result of rolling a dice 10 times:

+main 1 variable rng name? set to new Random()value or expression?2 +for i item? in range(1, 10)source? 3 print(rollDice(rng)arguments?)4 end for end main +function rollDice name?(rng as Random parameter definitions?) returns Int Type? 5 return rng.asInt(1, 6)value or expression?6 end function
+def main() -> None: 1 rng name? = Random()value or expression? # variable definition 2 +for i item? in range(1, 10)source?: 3 print(rollDice(rng)arguments?)4 +def rollDice name?(rng: Random parameter definitions?) -> int Type?: # function 5 return rng.asInt(1, 6)value or expression?6 main()
+static void main() { 1 var rng name? = new Random()value or expression?;2 +foreach (i item? in range(1, 10)source?) { 3 Console.WriteLine(rollDice(rng)arguments?); // print 4 } // foreach } // main +static int Type? rollDice name?(Random rng parameter definitions?) { // function 5 return rng.asInt(1, 6)value or expression?;6 } // function
+Sub main() 1 Dim rng name? = New Random()value or expression? ' variable definition 2 +For Each i item? In range(1, 10)source? 3 Console.WriteLine(rollDice(rng)arguments?) ' print 4 Next i End Sub +Function rollDice name?(rng As Random parameter definitions?) As Integer Type? 5 Return rng.asInt(1, 6)value or expression?6 End Function
public class Global {
+static void main() { 1 var rng name? = new Random()value or expression?;2 +foreach (i item? in range(1, 10)source?) { 3 System.out.println(rollDice(rng)arguments?); // print 4 } // foreach } // main +static int Type? rollDice name?(Random rng parameter definitions?) { // function 5 return rng.asInt(1, 6)value or expression?;6 } // function
}
If you run this program you will see that it generates the same value (namely 3) each time! We need to change it so that after each roll the variable `rngrngrngrngrng` is updated to the next value of the Random number generator. So changing just the main routine to the following will generate a more random looking sequence:
+main 1 variable rng name? set to new Random()value or expression?2 +for i item? in range(1, 10)source? 3 print(rollDice(rng)arguments?)4 reassign rng variableName? to rng.nextGen()value or expression?5 end for end main
+def main() -> None: 1 rng name? = Random()value or expression? # variable definition 2 +for i item? in range(1, 10)source?: 3 print(rollDice(rng)arguments?)4 rng variableName? = rng.nextGen()value or expression? # reassign variable 5 main()
+static void main() { 1 var rng name? = new Random()value or expression?;2 +foreach (i item? in range(1, 10)source?) { 3 Console.WriteLine(rollDice(rng)arguments?); // print 4 rng variableName? = rng.nextGen()value or expression?; // reassign variable 5 } // foreach } // main
+Sub main() 1 Dim rng name? = New Random()value or expression? ' variable definition 2 +For Each i item? In range(1, 10)source? 3 Console.WriteLine(rollDice(rng)arguments?) ' print 4 rng variableName? = rng.nextGen()value or expression? ' reassign variable 5 Next i End Sub
public class Global {
+static void main() { 1 var rng name? = new Random()value or expression?;2 +foreach (i item? in range(1, 10)source?) { 3 System.out.println(rollDice(rng)arguments?); // print 4 rng variableName? = rng.nextGen()value or expression?; // reassign variable 5 } // foreach } // main
}

Now when you run the same program it produces random looking values, but always in the same sequence. This effect can be very useful for testing code, but it makes for very predictable games!

To overcome this predictability, initialise the random generator from the system clock (given that it changes 1,000 times per second) which will make it almost impossible to predict the sequence:

+main 1 variable rng name? set to new Random()value or expression?2 call rng.initialiseFromClock procedureName?(arguments?)3 +for i item? in range(1, 10)source? 4 print(rollDice(rng)arguments?)5 reassign rng variableName? to rng.nextGen()value or expression?6 end for end main
+def main() -> None: 1 rng name? = Random()value or expression? # variable definition 2 rng.initialiseFromClock procedureName?(arguments?) # call procedure 3 +for i item? in range(1, 10)source?: 4 print(rollDice(rng)arguments?)5 rng variableName? = rng.nextGen()value or expression? # reassign variable 6 main()
+static void main() { 1 var rng name? = new Random()value or expression?;2 rng.initialiseFromClock procedureName?(arguments?); // call procedure 3 +foreach (i item? in range(1, 10)source?) { 4 Console.WriteLine(rollDice(rng)arguments?); // print 5 rng variableName? = rng.nextGen()value or expression?; // reassign variable 6 } // foreach } // main
+Sub main() 1 Dim rng name? = New Random()value or expression? ' variable definition 2 rng.initialiseFromClock procedureName?(arguments?) ' call procedure 3 +For Each i item? In range(1, 10)source? 4 Console.WriteLine(rollDice(rng)arguments?) ' print 5 rng variableName? = rng.nextGen()value or expression? ' reassign variable 6 Next i End Sub
public class Global {
+static void main() { 1 var rng name? = new Random()value or expression?;2 rng.initialiseFromClock procedureName?(arguments?); // call procedure 3 +foreach (i item? in range(1, 10)source?) { 4 System.out.println(rollDice(rng)arguments?); // print 5 rng variableName? = rng.nextGen()value or expression?; // reassign variable 6 } // foreach } // main
}

This now works well. But if we are going to have to go back out to the main routine between each use of `RandomRandomRandomRandomRandom`, we might as well have used the procedural methods in the first place. The following example shows something that could not be done that way: creating a List of random dice-throws entirely within a function:

+main 1 variable rng name? set to new Random()value or expression?2 call rng.initialiseFromClock procedureName?(arguments?)3 print(randomList(rng).item_0 arguments?)4 end main +function randomList name?(rng as Random parameter definitions?) returns (List<of Int>, Random)Type? 5 let li name? be new List<of Int>()value or expression?6 let items name? be range(0, 10)value or expression?7 return items.reduce((li, rng), appendDiceThrow)value or expression?8 end function +function appendDiceThrow name?(tup as (List<of Int>, Random), row as Int parameter definitions?) returns (List<of Int>, Random)Type? 9 let col name? be tup.item_0 value or expression?10 let rng name? be tup.item_1 value or expression?11 return (col.withAppend(rng.asInt(1, 6)), rng.nextGen())value or expression?12 end function
+def main() -> None: 1 rng name? = Random()value or expression? # variable definition 2 rng.initialiseFromClock procedureName?(arguments?) # call procedure 3 print(randomList(rng).item_0 arguments?)4 +def randomList name?(rng: Random parameter definitions?) -> tuple[list[int], Random]Type?: # function 5 li name? = list[int]()value or expression? # let 6 items name? = range(0, 10)value or expression? # let 7 return items.reduce((li, rng), appendDiceThrow)value or expression?8 +def appendDiceThrow name?(tup: tuple[list[int], Random], row: int parameter definitions?) -> tuple[list[int], Random]Type?: # function 9 col name? = tup.item_0 value or expression? # let 10 rng name? = tup.item_1 value or expression? # let 11 return (col.withAppend(rng.asInt(1, 6)), rng.nextGen())value or expression?12 main()
+static void main() { 1 var rng name? = new Random()value or expression?;2 rng.initialiseFromClock procedureName?(arguments?); // call procedure 3 Console.WriteLine(randomList(rng).item_0 arguments?); // print 4 } // main +static (List<int>, Random)Type? randomList name?(Random rng parameter definitions?) { // function 5 var li name? = new List<int>()value or expression?; // let 6 var items name? = range(0, 10)value or expression?; // let 7 return items.reduce((li, rng), appendDiceThrow)value or expression?;8 } // function +static (List<int>, Random)Type? appendDiceThrow name?((List<int>, Random) tup, int row parameter definitions?) { // function 9 var col name? = tup.item_0 value or expression?; // let 10 var rng name? = tup.item_1 value or expression?; // let 11 return (col.withAppend(rng.asInt(1, 6)), rng.nextGen())value or expression?;12 } // function
+Sub main() 1 Dim rng name? = New Random()value or expression? ' variable definition 2 rng.initialiseFromClock procedureName?(arguments?) ' call procedure 3 Console.WriteLine(randomList(rng).item_0 arguments?) ' print 4 End Sub +Function randomList name?(rng As Random parameter definitions?) As (List(Of Integer), Random)Type? 5 Dim li name? = New List(Of Integer)()value or expression? ' let 6 Dim items name? = range(0, 10)value or expression? ' let 7 Return items.reduce((li, rng), appendDiceThrow)value or expression?8 End Function +Function appendDiceThrow name?(tup As (List(Of Integer), Random), row As Integer parameter definitions?) As (List(Of Integer), Random)Type? 9 Dim col name? = tup.item_0 value or expression? ' let 10 Dim rng name? = tup.item_1 value or expression? ' let 11 Return (col.withAppend(rng.asInt(1, 6)), rng.nextGen())value or expression?12 End Function
public class Global {
+static void main() { 1 var rng name? = new Random()value or expression?;2 rng.initialiseFromClock procedureName?(arguments?); // call procedure 3 System.out.println(randomList(rng).item_0 arguments?); // print 4 } // main +static (List<int>, Random)Type? randomList name?(Random rng parameter definitions?) { // function 5 var li name? = new List<int>()value or expression?; // let 6 var items name? = range(0, 10)value or expression?; // let 7 return items.reduce((li, rng), appendDiceThrow)value or expression?;8 } // function +static (List<int>, Random)Type? appendDiceThrow name?((List<int>, Random) tup, int row parameter definitions?) { // function 9 var col name? = tup.item_0 value or expression?; // let 10 var rng name? = tup.item_1 value or expression?; // let 11 return (col.withAppend(rng.asInt(1, 6)), rng.nextGen())value or expression?;12 } // function
}

In Life - functional you can find this pattern employed to create a randomised initial grid of random black or white blocks.

# Global Instructions

## Same as for object-oriented programming

Coding with Elan using the functional profile offers the same global instructions as offered in the object-oriented profile.

Statement instructions

Within the main routine or any procedure coding with Elan using the functional profile offers the same statement instructions as offered in the object-oriented profile.

However, within a function coding with Elan using the functional profile allows only the `returnreturnreturnreturnreturn` statement

- which forms part of the function template, plus the option to precede this with one or more ...

## Let Statement

#### Examples of let statements

From the Life - functional demo:

+function north name?(cell as (Int, Int)parameter definitions?) returns (Int, Int)Type? 1 let x name? be cell.item_0 value or expression?2 let y name? be cell.item_1 value or expression?3 let y2 name? be if(y is 0, 29, y - 1)value or expression?4 return (x, y2)value or expression?5 end function
+def north name?(cell: tuple[int, int]parameter definitions?) -> tuple[int, int]Type?: # function 1 x name? = cell.item_0 value or expression? # let 2 y name? = cell.item_1 value or expression? # let 3 y2 name? = if(y == 0, 29, y - 1)value or expression? # let 4 return (x, y2)value or expression?5
+static (int, int)Type? north name?((int, int) cell parameter definitions?) { // function 1 var x name? = cell.item_0 value or expression?; // let 2 var y name? = cell.item_1 value or expression?; // let 3 var y2 name? = if(y == 0, 29, y - 1)value or expression?; // let 4 return (x, y2)value or expression?;5 } // function
+Function north name?(cell As (Integer, Integer)parameter definitions?) As (Integer, Integer)Type? 1 Dim x name? = cell.item_0 value or expression? ' let 2 Dim y name? = cell.item_1 value or expression? ' let 3 Dim y2 name? = if(y = 0, 29, y - 1)value or expression? ' let 4 Return (x, y2)value or expression?5 End Function
public class Global {
+static (int, int)Type? north name?((int, int) cell parameter definitions?) { // function 1 var x name? = cell.item_0 value or expression?; // let 2 var y name? = cell.item_1 value or expression?; // let 3 var y2 name? = if(y == 0, 29, y - 1)value or expression?; // let 4 return (x, y2)value or expression?;5 } // function
}

The first two let statements are used to extract the two values from the 2-tuple `cellcellcellcellcell` into named values `xxxxx` and `yyyyy`. The third let statement, calculates the y coordinate for the cell immediately to the North, using a conditional expression to 'wrap' around to the bottom of the 40x30 grid if necessary.

From the Merge Sort demo:

+function sortedFrontHalf name?(li as List<of String>parameter definitions?) returns List<of String>Type? 1 let mid name? be divAsInt(li.length(), 2)value or expression?2 let frontHalf name? be li.subList(0, mid)value or expression?3 return sort(frontHalf)value or expression?4 end function
+def sortedFrontHalf name?(li: list[str]parameter definitions?) -> list[str]Type?: # function 1 mid name? = divAsInt(li.length(), 2)value or expression? # let 2 frontHalf name? = li.subList(0, mid)value or expression? # let 3 return sort(frontHalf)value or expression?4
+static List<string>Type? sortedFrontHalf name?(List<string> li parameter definitions?) { // function 1 var mid name? = divAsInt(li.length(), 2)value or expression?; // let 2 var frontHalf name? = li.subList(0, mid)value or expression?; // let 3 return sort(frontHalf)value or expression?;4 } // function
+Function sortedFrontHalf name?(li As List(Of String)parameter definitions?) As List(Of String)Type? 1 Dim mid name? = divAsInt(li.length(), 2)value or expression? ' let 2 Dim frontHalf name? = li.subList(0, mid)value or expression? ' let 3 Return sort(frontHalf)value or expression?4 End Function
public class Global {
+static List<String>Type? sortedFrontHalf name?(List<String> li parameter definitions?) { // function 1 var mid name? = divAsInt(li.length(), 2)value or expression?; // let 2 var frontHalf name? = li.subList(0, mid)value or expression?; // let 3 return sort(frontHalf)value or expression?;4 } // function
}

This function could have been written without using any let statements, as:

+function sortedFrontHalf name?(li as List<of String>parameter definitions?) returns List<of String>Type? 1 return sort(li.subList(0, divAsInt(li.length(), 2)))value or expression?2 end function
+def sortedFrontHalf name?(li: list[str]parameter definitions?) -> list[str]Type?: # function 1 return sort(li.subList(0, divAsInt(li.length(), 2)))value or expression?2
+static List<string>Type? sortedFrontHalf name?(List<string> li parameter definitions?) { // function 1 return sort(li.subList(0, divAsInt(li.length(), 2)))value or expression?;2 } // function
+Function sortedFrontHalf name?(li As List(Of String)parameter definitions?) As List(Of String)Type? 1 Return sort(li.subList(0, divAsInt(li.length(), 2)))value or expression?2 End Function
public class Global {
+static List<String>Type? sortedFrontHalf name?(List<String> li parameter definitions?) { // function 1 return sort(li.subList(0, divAsInt(li.length(), 2)))value or expression?;2 } // function
}
but the use of let statements makes the intention much easier to read.

#### What you need to know about let statements

- A let statement is like a variable definition, except that the named value created may not then be reassigned to another value.
- A let statement is therefore somewhat like a constant, except that:
  - It is defined within a function, not globally
  - The value assigned to the name may be defined by an expression that incorporates function parameters and/or the named values from any (previous) let statements in the function.
  - The value may be a data structure such as a list
- The motivations for using let statements is to:
  - To eliminate duplication, where the same sub-expression would appear more than once within the final expression to be evaluated and returned by the function.
  - To improve readabilty. In theory it is possible to implement any function using just a `returnreturnreturnreturnreturn` statement followed by a single expression, but the expressions can quickly become very hard to read, so it is better out sub-expressions into let statement - or, if the sub-expressions might be useful in in other contexts, as separate functions.
  - Elan does have some limits on the complexity of expressions, and breaking out sub-expressions into lets is a good way to avoid encountering those limits.

# Member instructions

When using the functional profile, in the context of a class you will be offered the same member instructions as when using the object-oriented profile, with two exceptions:

- There is an additional member: the with method
- The procedure method is not available for use - because procedure methods cause side effects. All input/output or other system interaction within a functional program must be handled directly within the main routine, or a global procedure.

## With method

#### Examples of with methods

From the Snake - functional demo, where the

`GameGameGameGameGame` class defines 8 with methods including:
+function withHead name?(value as Square parameter definitions?) returns Game Type? 1 let copyOfThis name? be copy(this)value or expression?2 reassign copyOfThis.head variableName? to value value or expression?3 return copyOfThis value or expression?4 end function
+def withHead name?(value: Square parameter definitions?) -> Game Type?: # function 1 copyOfThis name? = copy(self)value or expression? # let 2 copyOfThis.head variableName? = value value or expression? # reassign variable 3 return copyOfThis value or expression?4
+static Game Type? withHead name?(Square value parameter definitions?) { // function 1 var copyOfThis name? = copy(this)value or expression?; // let 2 copyOfThis.head variableName? = value value or expression?; // reassign variable 3 return copyOfThis value or expression?;4 } // function
+Function withHead name?(value As Square parameter definitions?) As Game Type? 1 Dim copyOfThis name? = copy(Me)value or expression? ' let 2 copyOfThis.head variableName? = value value or expression? ' reassign variable 3 Return copyOfThis value or expression?4 End Function
public class Global {
+static Game Type? withHead name?(Square value parameter definitions?) { // function 1 var copyOfThis name? = copy(this)value or expression?; // let 2 copyOfThis.head variableName? = value value or expression?; // reassign variable 3 return copyOfThis value or expression?;4 } // function
}

This method is called from 11 places elsewhere in the code, including within this global method:

+function moveSnake name?(g as Game parameter definitions?) returns Game Type? 1 let k name? be g.key value or expression?2 let x name? be g.head.x value or expression?3 let y name? be g.head.y value or expression?4 let newX name? be if(k.equals("a"), x - 1, if(k.equals("d"), x + 1, x))value or expression?5 let newY name? be if(k.equals("w"), y - 1, if(k.equals("s"), y + 1, y))value or expression?6 return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY))value or expression?7 end function
+def moveSnake name?(g: Game parameter definitions?) -> Game Type?: # function 1 k name? = g.key value or expression? # let 2 x name? = g.head.x value or expression? # let 3 y name? = g.head.y value or expression? # let 4 newX name? = if(k.equals("a"), x - 1, if(k.equals("d"), x + 1, x))value or expression? # let 5 newY name? = if(k.equals("w"), y - 1, if(k.equals("s"), y + 1, y))value or expression? # let 6 return g.withBody(g.body.withAppend(g.head)).withHead(Square(newX, newY))value or expression?7
+static Game Type? moveSnake name?(Game g parameter definitions?) { // function 1 var k name? = g.key value or expression?; // let 2 var x name? = g.head.x value or expression?; // let 3 var y name? = g.head.y value or expression?; // let 4 var newX name? = if(k.equals("a"), x - 1, if(k.equals("d"), x + 1, x))value or expression?; // let 5 var newY name? = if(k.equals("w"), y - 1, if(k.equals("s"), y + 1, y))value or expression?; // let 6 return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY))value or expression?;7 } // function
+Function moveSnake name?(g As Game parameter definitions?) As Game Type? 1 Dim k name? = g.key value or expression? ' let 2 Dim x name? = g.head.x value or expression? ' let 3 Dim y name? = g.head.y value or expression? ' let 4 Dim newX name? = if(k.equals("a"), x - 1, if(k.equals("d"), x + 1, x))value or expression? ' let 5 Dim newY name? = if(k.equals("w"), y - 1, if(k.equals("s"), y + 1, y))value or expression? ' let 6 Return g.withBody(g.body.withAppend(g.head)).withHead(New Square(newX, newY))value or expression?7 End Function
public class Global {
+static Game Type? moveSnake name?(Game g parameter definitions?) { // function 1 var k name? = g.key value or expression?; // let 2 var x name? = g.head.x value or expression?; // let 3 var y name? = g.head.y value or expression?; // let 4 var newX name? = if(k.equals("a"), x - 1, if(k.equals("d"), x + 1, x))value or expression?; // let 5 var newY name? = if(k.equals("w"), y - 1, if(k.equals("s"), y + 1, y))value or expression?; // let 6 return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY))value or expression?;7 } // function
}

Notice, in the same program, that the `SquareSquareSquareSquareSquare` class does not define any with methods

- because there is a never a need to update a square. A square represents a specific location on the 40x30 grid - if you need to change, say, the location of the apple, you use (or create new) the square for the location you want - you don't update the existing one.

#### What you need to know about methods

- A with method is a specific form of function method.
- Its purpose is to allow an instance of a class to be 'updated' without actually mutating the instance.
- Instead, the method returns a copy of the current instance, but with the specified differences.
- Several of the standard data structures in the Elan library have similar with methods, that are broadly equivalent to procedure methods, but for use within a function. For example `ListlistListListList` has the procedural method append and the function method withAppend.
- When you create a new with method within a class, the method includes three templated completed instructions. You should not attempt to change the first or last instructions, nor delete the middle one - if you do this by mistake, delete the whole method and start again.
- The middle instruction - a reassign variable - indicates that its form should be: `reassign copyOfThis.aPropertyNamevariableName? to theNewValuevalue or expression?0copyOfThis.aPropertyNamevariableName? = theNewValuevalue or expression? # reassign variable0copyOfThis.aPropertyNamevariableName? = theNewValuevalue or expression?; // reassign variable0copyOfThis.aPropertyNamevariableName? = theNewValuevalue or expression? ' reassign variable0copyOfThis.aPropertyNamevariableName? = theNewValuevalue or expression?; // reassign variable0`
- `copyOfThiscopyOfThiscopyOfThiscopyOfThiscopyOfThis` is a reserved name within Elan - this variable can only be created by the templated instruction shown above, and it is the only variable that may be re-assigned within a function, working in the functional profile.
- Always returning a copy of the data structure, instead of mutating the one you have may feel strange, but even in procedural programming, strings are never mutated: the dot-method upperCase does not change a string to upper case - it returns a new string with the contents of the original transformed to upper case.
- Because the method returns a new object, withMethods may be 'chained' (or 'dot-changed'), as in the earlier example: `return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY)) Code does not parse as Elan.return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY)) Code does not parse as Elan.return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY)) Code does not parse as Elan.return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY)) Code does not parse as Elan.return g.withBody(g.body.withAppend(g.head)).withHead(new Square(newX, newY)) Code does not parse as Elan.`

Elan Language Reference go to the top 