From eddc198398bb8f032af087a5c0e953f5cc4cf65f Mon Sep 17 00:00:00 2001
From: SimonLab <simon.labondance@gmail.com>
Date: Tue, 21 Jan 2020 13:22:18 +0000
Subject: [PATCH] update Readme to document Future, async and await, #9

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/README.md b/README.md
index 3b677bc..6737a84 100644
--- a/README.md
+++ b/README.md
@@ -194,6 +194,83 @@ dynamic int a; // https://repl.it/repls/GreenDeadMatch
 a = 42;
 ```
 
+## Asynchronous events
+
+Dart provides the `Future` class to represent asynchronous events.
+For example the following `hello` function will return a `String`  in a near futur: 
+
+```dart
+Future<String> hello() { // The type parameter of Future is a String, represented by <String>
+    return Future.delayed(Duration(seconds: 2), () => "hello"); // Using the Future.delayed function to create a time gap of 2 seconds
+}
+```
+
+A function with a retun type of `Future<T>` (`T` here represent any types) can have two state returns `Uncomplete` and `Complete`.
+When completed the function will return the type `T`, in our case the `hello` function returns a `String`.
+If an error occurs then the function will return an `Error`.
+
+To be able to use the returned value of an asynchronus function we can use the `async` and `await` keywords.
+We need first to describe the function using an asynchronous function by adding the `async` keyword before the body of the function.
+Then we using the asynchronous function we prefix the call to the function with `await`. This will stop the process of the function
+and wait for the futur result. For example we can create a `main` function which will use our `hello` function:
+
+```dart
+void main() async {
+    String hi = await hello();
+    print(hi); // print "hello" after 2 seconds
+}
+
+Future<String> hello() { // The type parameter of Future is a String, represented by <String>
+    return Future.delayed(Duration(seconds: 2), () => "hello"); // Using the Future.delayed function to create a time gap of 2 seconds
+}
+```
+
+To test this code you can copy/paste it and run it on dartpad: https://dartpad.dev/
+
+If we do not add the `async/await` keywords, we can still call the asynchronous `hello` function,
+however the result won't be ready and the `Future` instance will be returned instead of the String:
+
+```dart
+void main() {
+    dynamic hi = hello();
+    print(hi); // print "Instance of _Future<String>"
+}
+
+Future<String> hello() { // The type parameter of Future is a String, represented by <String>
+    return Future.delayed(Duration(seconds: 2), () => "hello"); // Using the Future.delayed function to create a time gap of 2 seconds
+}
+```
+
+We can also use the `then` function which take a callback function to get the futur value:
+
+
+```dart
+void main() {
+    hello().then((futureValue) { // futureValue is the retuned value of the hello function
+        print(futureValue); // print after 2 seconds "hello"
+    });
+}
+
+Future<String> hello() { // The type parameter of Future is a String, represented by <String>
+    return Future.delayed(Duration(seconds: 2), () => "hello"); // Using the Future.delayed function to create a time gap of 2 seconds
+}
+```
+
+Compare to `await`, `then` will not stop the process of the function and continue the execution:
+
+```dart
+void main() {
+    hello().then((futureValue) { // futureValue is the retuned value of the hello function
+        print(futureValue); // print after 2 seconds "hello"
+    });
+    print('printed first'); // This print will be displayed before 'hello'
+}
+
+Future<String> hello() { // The type parameter of Future is a String, represented by <String>
+    return Future.delayed(Duration(seconds: 2), () => "hello"); // Using the Future.delayed function to create a time gap of 2 seconds
+}
+```
+
 ## Object-Oriented Programming in Dart
 
 Dart is an Object-Oriented language. Object Orientation is a software development paradigm that follows real-world modelling. Object Orientation considers a program as a collection of objects that communicate with each other via mechanism called methods.