From ad72919f82e1b5c18728aa471c2abc3f5608d525 Mon Sep 17 00:00:00 2001
From: Nenad <xinef.it@gmail.com>
Date: Sun, 29 Dec 2024 19:37:25 +0100
Subject: [PATCH] implement operator overloading concept

---
 .../operator-overloading/.meta/config.json    |  6 +--
 concepts/operator-overloading/about.md        | 49 +++++++++++++++++++
 concepts/operator-overloading/introduction.md |  4 ++
 concepts/operator-overloading/links.json      | 11 ++++-
 4 files changed, 65 insertions(+), 5 deletions(-)

diff --git a/concepts/operator-overloading/.meta/config.json b/concepts/operator-overloading/.meta/config.json
index 35b1d32b..d57d8b6b 100644
--- a/concepts/operator-overloading/.meta/config.json
+++ b/concepts/operator-overloading/.meta/config.json
@@ -1,7 +1,5 @@
 {
-    "blurb": "<todo>",
-    "authors": [
-        "<your_gh_username>"
-    ],
+    "blurb": "Operator overloading in Cairo enables you to redefine standard operators like `+` and `-` for custom types by implementing specific traits.",
+    "authors": ["0xNeshi"],
     "contributors": []
 }
diff --git a/concepts/operator-overloading/about.md b/concepts/operator-overloading/about.md
index 6917574a..8e21e5b7 100644
--- a/concepts/operator-overloading/about.md
+++ b/concepts/operator-overloading/about.md
@@ -1 +1,50 @@
 # Operator Overloading
+
+Operator overloading is a feature in some programming languages that allows the redefinition of standard operators, such as addition (`+`), subtraction (`-`), multiplication (`*`), and division (`/`), to work with user-defined types.
+
+This can make the syntax of the code more intuitive, by enabling operations on user-defined types to be expressed in the same way as operations on primitive types.
+
+In Cairo, operator overloading is achieved through the implementation of specific traits.
+
+Each operator has an associated trait, and overloading that operator involves providing an implementation of that trait for a custom type.
+However, it's essential to use operator overloading judiciously.
+
+Misuse can lead to confusion, making the code more difficult to maintain, for example when there is no semantic meaning to the operator being overloaded.
+
+Consider an example where two `Potions` need to be combined.
+
+`Potions` have two data fields, mana and health.
+
+Combining two `Potions` should add their respective fields.
+
+```rust
+struct Potion {
+    health: felt252,
+    mana: felt252,
+}
+
+impl PotionAdd of Add<Potion> {
+    fn add(lhs: Potion, rhs: Potion) -> Potion {
+        Potion { health: lhs.health + rhs.health, mana: lhs.mana + rhs.mana }
+    }
+}
+
+fn main() {
+    let health_potion: Potion = Potion { health: 100, mana: 0 };
+    let mana_potion: Potion = Potion { health: 0, mana: 100 };
+    let super_potion: Potion = health_potion + mana_potion;
+    // Both potions were combined with the `+` operator.
+    assert(super_potion.health == 100, '');
+    assert(super_potion.mana == 100, '');
+}
+```
+
+In the code above, we're implementing the `Add` trait for the `Potion` type.
+
+The add function takes two arguments: `lhs` and `rhs` (left and right-hand side).
+
+The function body returns a new `Potion` instance, its field values being a combination of `lhs` and `rhs`.
+
+As illustrated in the example, overloading an operator requires specification of the concrete type being overloaded.
+
+The overloaded generic trait is `Add<T>`, and we define a concrete implementation for the type `Potion` with `Add<Potion>`.
diff --git a/concepts/operator-overloading/introduction.md b/concepts/operator-overloading/introduction.md
index e10b99d0..a8a394da 100644
--- a/concepts/operator-overloading/introduction.md
+++ b/concepts/operator-overloading/introduction.md
@@ -1 +1,5 @@
 # Introduction
+
+Operator overloading in Cairo enables you to redefine standard operators like `+` and `-` for custom types by implementing specific traits.
+This allows user-defined types to interact intuitively with operators, similar to primitive types.
+When used thoughtfully, operator overloading enhances code readability and expressiveness while preserving clarity and intent.
diff --git a/concepts/operator-overloading/links.json b/concepts/operator-overloading/links.json
index fe51488c..87fd948d 100644
--- a/concepts/operator-overloading/links.json
+++ b/concepts/operator-overloading/links.json
@@ -1 +1,10 @@
-[]
+[
+    {
+      "url": "https://book.cairo-lang.org/ch12-03-operator-overloading.html",
+      "description": "Operator Overloading in The Cairo Book"
+    },
+    {
+      "url": "https://book.cairo-lang.org/appendix-02-operators-and-symbols.html",
+      "description": "Operators and Symbols in The Cairo Book"
+    }
+]