---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: clamp
excerpt: |
  DuckDB Community Extensions
  Provides mathematical clamp functions for numeric types in DuckDB, including general clamping, saturate, and others. Ensures values stay within a specified range and handles NULLs and NaNs correctly.

extension:
  name: clamp
  description: Provides mathematical clamp functions for numeric types in DuckDB, including general clamping, saturate, and others. Ensures values stay within a specified range and handles NULLs and NaNs correctly.
  version: 0.1.0
  language: C++
  build: cmake
  license: MIT
  maintainers:
    - oglego

repo:
  github: oglego/duckdb_clamp
  ref: 8e21b27a80a2ebfda2b786d06ca50a4123b3faa5

docs:
  hello_world: |
    -- General clamp between min and max
    SELECT clamp(5, 0, 10);      -- Returns 5
    SELECT clamp(-5, 0, 10);     -- Returns 0
    SELECT clamp(15, 0, 10);     -- Returns 10

    -- NULL handling
    SELECT clamp(NULL, 0, 10);   -- Returns NULL
    SELECT clamp(5, NULL, 10);   -- Returns NULL
    SELECT clamp(5, 0, NULL);    -- Returns NULL

    -- Convenience clip (alias for clamp)
    SELECT clip(15, 10, 20);  -- Returns 15
    SELECT clip(5, 10, 20);   -- Returns 10
    SELECT clip(25, 10, 20);  -- Returns 20

    -- Saturate (equivalent to clamp(x, 0.0, 1.0))
    SELECT saturate(0.5);        -- Returns 0.5
    SELECT saturate(-0.5);       -- Returns 0.0
    SELECT saturate(1.5);        -- Returns 1.0

    -- Convenience clamp01 (alias for saturate)
    SELECT clamp01(0.7);         -- Returns 0.7
    SELECT clamp01(-1.0);        -- Returns 0.0
    SELECT clamp01(2.0);         -- Returns 1.0

    -- Handling NaN and NULL
    SELECT clamp(CAST('NaN' AS DOUBLE), 0, 10); -- Returns NaN
    SELECT saturate(NULL);                      -- Returns NULL

    -- Wrap a value into a range [min, max) using modular arithmetic
    SELECT wrap(11, 0, 10);      -- Returns 1
    SELECT wrap(25, 10, 20);     -- Returns 15
    SELECT wrap(5, 10, 20);      -- Returns 15

    -- Pingpong a value between min and max
    SELECT pingpong(11, 0, 10);  -- Returns 9
    SELECT pingpong(12, 10, 20); -- Returns 12
    SELECT pingpong(28, 10, 20); -- Returns 12

    -- Fract (returns the fractional part of a number)
    SELECT fract(1.75);          -- Returns 0.75
    SELECT fract(-0.1);          -- Returns 0.9
    SELECT fract(10);            -- Returns 0.0

    -- Step function (returns 0 if value < edge, otherwise 1)
    SELECT step(0.5, 0.25);      -- Returns 0.0
    SELECT step(0.5, 0.5);       -- Returns 1.0
    SELECT step(5,6);            -- Returns 1

  extended_description: |
    The Clamp extension provides functions for numerical restriction:

    1. **clamp(value, min, max)**: Restricts a numeric value between `min` and `max`.
       - Supports NaN propagation (IEEE-754 standard)
       - Throws an exception if `min > max`
       - Returns NULL if any argument is NULL

    2. **clip(value, min, max)**: Alias for `clamp(value, min, max)`.

    3. **saturate(value)**: Convenience function to clamp values between 0.0 and 1.0.

    4. **clamp01(value)**: Alias for `saturate(value)`.

    5. **wrap(value, min, max)**: Wrap a value x into the range [min, max) using modular arithmetic.

    6. **pingpong(value, min, max)**: Return a value that "bounces" back and forth between the min and max.

    7. **fract(value)**: Return the fractional part of a number.

    8. **step(edge, value)**: Return 0 if `value < edge`, otherwise return 1.

    This extension ensures safe handling of edge cases including:
    - NaN values
    - NULLs
    - Floating-point numbers
    - Large integers

extension_star_count: 2
extension_star_count_pretty: 2
extension_download_count: 24047
extension_download_count_pretty: 24.0k
image: '/images/community_extensions/social_preview/preview_community_extension_clamp.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| Linux ARM64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| macOS AMD64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| macOS ARM64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| Windows AMD64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ✅ | ✅ | ✅ | ✅ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

| function_name | function_type |                                                                                             description                                                                                              | comment |       examples        |
|---------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------------------|
| clamp         | scalar        | Restricts value to the range [min_val, max_val]. Returns min_val if value is below it and max_val if value is above it. Returns NaN if any argument is NaN and raises an error if min_val > max_val. | NULL    | [clamp(15, 0, 10)]    |
| clamp01       | scalar        | Alias of saturate. Restricts value to the range [0, 1].                                                                                                                                              | NULL    | [clamp01(1.5)]        |
| clip          | scalar        | Alias of clamp. Restricts value to the range [min_val, max_val].                                                                                                                                     | NULL    | [clip(15, 0, 10)]     |
| fract         | scalar        | Returns the fractional part of value, computed as value - floor(value). For example the result for -1.25 is 0.75. Always returns 0 for integers.                                                     | NULL    | [fract(3.75)]         |
| pingpong      | scalar        | Bounces value back and forth between min_val and max_val, producing a triangle wave. Raises an error if min_val >= max_val.                                                                          | NULL    | [pingpong(12, 0, 10)] |
| saturate      | scalar        | Restricts value to the range [0, 1]. Returns 0 for values below 0 and 1 for values above 1.                                                                                                          | NULL    | [saturate(1.5)]       |
| step          | scalar        | Threshold function that returns 0 if value < edge, otherwise 1. Returns NaN if either argument is NaN.                                                                                               | NULL    | [step(0.5, 0.75)]     |
| wrap          | scalar        | Wraps value into the half-open range [min_val, max_val) using modular arithmetic, which is useful for cyclic values such as angles. Raises an error if min_val >= max_val.                           | NULL    | [wrap(370, 0, 360)]   |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.