Add documentation for saturating math functions (github#1282)

Co-authored-by: Lana Brindley <github@lanabrindley.com>
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

api/page-index/page-index.js

@@ -314,6 +314,33 @@ module.exports = [
               },
             ],
           },
+          {
+            title: 'Saturating math',
+            type: 'directory',
+            href: 'saturating_math',
+            children: [
+              {
+                title: 'saturating_add',
+                href: 'saturating_add',
+              },
+              {
+                title: 'saturating_add_pos',
+                href: 'saturating_add_pos',
+              },
+              {
+                title: 'saturating_mul',
+                href: 'saturating_mul',
+              },
+              {
+                title: 'saturating_sub',
+                href: 'saturating_sub',
+              },
+              {
+                title: 'saturating_sub_pos',
+                href: 'saturating_sub_pos',
+              },
+            ],
+          },
           {
             title: 'Statistical aggregates',
             type: 'directory',

api/saturating_add.md

@@ -0,0 +1,36 @@
+---
+api_name: saturating_add()
+excerpt: Adds two numbers, saturating at the numeric bounds instead of overflowing
+license: community
+toolkit: true
+api_experimental: true
+topic: hyperfunctions
+tags: [hyperfunctions, saturating math]
+api_category: hyperfunction
+hyperfunction_toolkit: true
+hyperfunction_family: 'saturating math'
+hyperfunction_subfamily: saturating math
+hyperfunction_type: one-step
+---
+
+# saturating_add()  <tag type="toolkit">Toolkit</tag><tag type="toolkit-experimental" content="Experimental" />
+The `saturating_add` function adds two numbers, saturating at -2147483648 and 2147483647 instead of overflowing.
+
+For more information about saturating math functions, see the
+[saturating math docs][saturating-math-docs].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`x`|`INT`| An integer to add to y|
+|`y`|`INT`| An integer to add to x |
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|`saturating_add`|`INT`| The result of `x+y`, saturating at the numeric bounds instead of overflowing. The numeric bounds are the upper and lower bounds of the 32-bit signed integers.|
+
+
+[saturating-math-docs]: /api/:currentVersion:/hyperfunctions/saturating_math/

api/saturating_add_pos.md

@@ -0,0 +1,36 @@
+---
+api_name: saturating_add_pos()
+excerpt: Adds two numbers, saturating at 0 for the minimum bound
+license: community
+toolkit: true
+topic: hyperfunctions
+tags: [hyperfunctions, saturating math]
+api_category: hyperfunction
+api_experimental: true
+hyperfunction_toolkit: true
+hyperfunction_family: 'saturating math'
+hyperfunction_subfamily: saturating math
+hyperfunction_type: one-step
+---
+
+# saturating_add_pos()  <tag type="toolkit">Toolkit</tag><tag type="toolkit-experimental" content="Experimental" />
+The `saturating_add_pos` function adds two numbers, saturating at 0 and 2147483647 instead of overflowing.
+
+For more information about saturating math functions, see the
+[saturating math docs][saturating-math-docs].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`x`|`INT`| An integer to add to y|
+|`y`|`INT`| An integer to add to x |
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|`saturating_add_pos`|`INT`| The result of x+y, saturating at 0 for the minimum bound |
+
+
+[saturating-math-docs]: /api/:currentVersion:/hyperfunctions/saturating_math/

api/saturating_math.md

@@ -0,0 +1,22 @@
+# Saturating math
+The saturating math hyperfunctions help you perform saturating math on integers.
+In saturating math, the final result is bounded. If the result of a normal mathematical
+operation exceeds either the minimum or maximum bound, the result of the
+corresponding saturating math operation is capped at the bound. For example,
+`2 + (-3) = -1`. But in a saturating math function with a lower bound of zero, the result
+is `0`.
+
+You can use saturating math to make sure your results don't overflow the allowed range
+of integers, or to force a result to be greater than or equal to zero.
+
+Some hyperfunctions are included in the default TimescaleDB product. For
+additional hyperfunctions, you need to install the
+[Timescale Toolkit][install-toolkit] PostgreSQL extension.
+
+<hyperfunctionTable
+    hyperfunctionFamily='saturating math'
+    includeExperimental
+    sortByType
+/>
+
+[install-toolkit]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/install-toolkit

api/saturating_mul.md

@@ -0,0 +1,36 @@
+---
+api_name: saturating_mul()
+excerpt: Multiples two numbers, saturating at the numeric bounds instead of overflowing
+license: community
+toolkit: true
+topic: hyperfunctions
+tags: [hyperfunctions, saturating math]
+api_category: hyperfunction
+api_experimental: true
+hyperfunction_toolkit: true
+hyperfunction_family: 'saturating math'
+hyperfunction_subfamily: saturating math
+hyperfunction_type: one-step
+---
+
+# saturating_mul()  <tag type="toolkit">Toolkit</tag><tag type="toolkit-experimental" content="Experimental" />
+The `saturating_mul` function multiples two numbers, saturating at -2147483648 and 2147483647 instead of overflowing.
+
+For more information about saturating math functions, see the
+[saturating math docs][saturating-math-docs].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`x`|`INT`| An integer to multiply with y |
+|`y`|`INT`| An integer to multiply with x |
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|saturating_mul |INT| The result of `x*y`, saturating at the numeric bounds instead of overflowing|
+
+
+[saturating-math-docs]: /api/:currentVersion:/hyperfunctions/saturating_math/

api/saturating_sub.md

@@ -0,0 +1,36 @@
+---
+api_name: saturating_sub()
+excerpt: Subtracts one number from another, saturating at the numeric bounds instead of overflowing
+license: community
+toolkit: true
+topic: hyperfunctions
+tags: [hyperfunctions, saturating math]
+api_category: hyperfunction
+api_experimental: true
+hyperfunction_toolkit: true
+hyperfunction_family: 'saturating math'
+hyperfunction_subfamily: saturating math
+hyperfunction_type: one-step
+---
+
+# saturating_sub()  <tag type="toolkit">Toolkit</tag><tag type="toolkit-experimental" content="Experimental" />
+The `saturating_sub` function subtracts the second number from the first, saturating at -2147483648 and 2147483647 instead of overflowing.
+
+For more information about saturating math functions, see the
+[saturating math docs][saturating-math-docs].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`x`|`INT`| An integer for y to subtract from |
+|`y`|`INT`| An integer to subtract from x |
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|`saturating_sub` |`INT`| The result of `x-y`, saturating at the numeric bounds instead of overflowing |
+
+
+[saturating-math-docs]: /api/:currentVersion:/hyperfunctions/saturating_math/

api/saturating_sub_pos.md

@@ -0,0 +1,36 @@
+---
+api_name: saturating_sub_pos()
+excerpt: Subtracts one number from another, saturating at 0 for the minimum bound
+license: community
+toolkit: true
+topic: hyperfunctions
+tags: [hyperfunctions, saturating math]
+api_category: hyperfunction
+api_experimental: true
+hyperfunction_toolkit: true
+hyperfunction_family: 'saturating math'
+hyperfunction_subfamily: saturating math
+hyperfunction_type: one-step
+---
+
+# saturating_sub_pos()  <tag type="toolkit">Toolkit</tag><tag type="experimental-toolkit" content="Experimental" />
+The `saturating_sub_pos` subtracts the second number from the first, saturating at 0 and 2147483647 instead of overflowing.
+
+For more information about saturating math functions, see the
+[saturating math docs][saturating-math-docs].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`x`|`INT`| An integer for y to subtract from |
+|`y`|`INT`| An integer to subtract from x |
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|`saturating_sub_pos` |`INT|` The result of `x-y`, saturating at 0 for the minimum bound |
+
+
+[saturating-math-docs]: /api/:currentVersion:/hyperfunctions/saturating_math/