[doc-en] master: Document clamp function for PHP 8.6 (#4814)

Author: Kyle (kylekatarnls) Committer: GitHub (web-flow) Pusher: jordikroon Date: 2026-09-30T21:44:42+02:00 Commit: https://github.com/php/doc-en/commit/bc21afc0cf0e58f48e5351fd9d5d86a0ddd71c8a Raw diff: https://github.com/php/doc-en/commit/bc21afc0cf0e58f48e5351fd9d5d86a0ddd71c8a.diff Document clamp function for PHP 8.6 (#4814) Changed paths: A reference/math/functions/clamp.xml M reference/array/versions.xml Diff: diff --git a/reference/array/versions.xml b/reference/array/versions.xml index d00594ce19fd..6a112b132338 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -64,6 +64,7 @@ <function name='array_walk_recursive' from='PHP 5, PHP 7, PHP 8'/> <function name='arsort' from='PHP 4, PHP 5, PHP 7, PHP 8'/> <function name='asort' from='PHP 4, PHP 5, PHP 7, PHP 8'/> + <function name='clamp' from='PHP 8 &gt;= 8.6.0'/> <function name='compact' from='PHP 4, PHP 5, PHP 7, PHP 8'/> <function name='count' from='PHP 4, PHP 5, PHP 7, PHP 8'/> <function name='current' from='PHP 4, PHP 5, PHP 7, PHP 8'/> diff --git a/reference/math/functions/clamp.xml b/reference/math/functions/clamp.xml new file mode 100644 index 000000000000..462d9ea76134 --- /dev/null +++ b/reference/math/functions/clamp.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> +<refentry xml:id="function.clamp" xmlns="http://docbook.org/ns/docbook"> + <refnamediv> + <refname>clamp</refname> + <refpurpose>Return the given value if in range, else return the nearest bound</refpurpose> + </refnamediv> + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <type>mixed</type><methodname>clamp</methodname> + <methodparam><type>mixed</type><parameter>value</parameter></methodparam> + <methodparam><type>mixed</type><parameter>min</parameter></methodparam> + <methodparam><type>mixed</type><parameter>max</parameter></methodparam> + </methodsynopsis> + <simpara> + Return the given value if in range of <parameter>min</parameter> and <parameter>max</parameter>. + Else if it's lower than <parameter>min</parameter>, return <parameter>min</parameter>. + Else return <parameter>max</parameter>. + </simpara> + <note> + <simpara> + Values of different types will be compared using the <link linkend="language.operators.comparison"> + standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be + compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric + <type>string</type> values will be compared alphanumerically. The actual value returned will be of the + original type with no conversion applied. + </simpara> + </note> + <caution> + <simpara> + Be careful when passing arguments of different types because + <function>clamp</function> can produce unpredictable results. + </simpara> + </caution> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>value</parameter></term> + <listitem> + <simpara> + Any <link linkend="language.operators.comparison">comparable</link> + value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>min</parameter></term> + <listitem> + <simpara> + A <link linkend="language.operators.comparison">comparable</link> minimum to limit + the <parameter>value</parameter> to. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>max</parameter></term> + <listitem> + <simpara> + A <link linkend="language.operators.comparison">comparable</link> maximum to limit + the <parameter>value</parameter> to. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + <function>clamp</function> returns the parameter <parameter>value</parameter> if + considered "between" <parameter>min</parameter> and <parameter>max</parameter> according to standard + comparisons. + </simpara> + <simpara> + If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be + <constant>NAN</constant>. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + If <parameter>min</parameter> is greater than <parameter>max</parameter>, + <function>clamp</function> throws a <exceptionname>ValueError</exceptionname>. + </simpara> + <simpara> + If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>, + <function>clamp</function> throws a <exceptionname>ValueError</exceptionname>. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php +echo clamp(-5, min: 0, max: 100), PHP_EOL; // 0 +echo clamp(55, min: 0, max: 100), PHP_EOL; // 55 +echo clamp(103, min: 0, max: 100), PHP_EOL; // 100 + +echo clamp("J", min: "A", max: "F"), PHP_EOL; // "F" + +clamp( + new \DateTimeImmutable('2025-08-01'), + min: new \DateTimeImmutable('2025-08-15'), + max: new \DateTimeImmutable('2025-09-15'), +)->format('Y-m-d'), PHP_EOL; // 2025-08-15 +?> +]]> + </programlisting> + </informalexample> + + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>min</function></member> + <member><function>max</function></member> + </simplelist> + </refsect1> +</refentry> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +-->