From 4cbefadbd7adee486e33a6b66014a2474e81f82e Mon Sep 17 00:00:00 2001
From: Tauseef Hilal Tantary <tantary.tauseef.atwork@gmail.com>
Date: Mon, 23 Oct 2023 19:21:09 +0530
Subject: [PATCH] [New Algorithm] - Triangular Numbers (#10663)

* Add New Algorithm: Triangular Numbers

* Calculate nth triangular number instead of generating a list

* Handle 0th position and update function name and docstring
---
 maths/special_numbers/triangular_numbers.py | 43 +++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 maths/special_numbers/triangular_numbers.py

diff --git a/maths/special_numbers/triangular_numbers.py b/maths/special_numbers/triangular_numbers.py
new file mode 100644
index 000000000..5be89e610
--- /dev/null
+++ b/maths/special_numbers/triangular_numbers.py
@@ -0,0 +1,43 @@
+"""
+A triangular number or triangle number counts objects arranged in an
+equilateral triangle. This module provides a function to generate n'th
+triangular number.
+
+For more information about triangular numbers, refer to:
+https://en.wikipedia.org/wiki/Triangular_number
+"""
+
+
+def triangular_number(position: int) -> int:
+    """
+    Generate the triangular number at the specified position.
+
+    Args:
+        position (int): The position of the triangular number to generate.
+
+    Returns:
+        int: The triangular number at the specified position.
+
+    Raises:
+        ValueError: If `position` is negative.
+
+    Examples:
+    >>> triangular_number(1)
+    1
+    >>> triangular_number(3)
+    6
+    >>> triangular_number(-1)
+    Traceback (most recent call last):
+        ...
+    ValueError: param `position` must be non-negative
+    """
+    if position < 0:
+        raise ValueError("param `position` must be non-negative")
+
+    return position * (position + 1) // 2
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()