Skip to content

Commit 86898b3

Browse files
kylekatarnlskylekatarnls
committed
Document clamp function
1 parent 10e6a2b commit 86898b3

2 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎reference/array/versions.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
<function name='array_walk_recursive' from='PHP 5, PHP 7, PHP 8'/>
6565
<function name='arsort' from='PHP 4, PHP 5, PHP 7, PHP 8'/>
6666
<function name='asort' from='PHP 4, PHP 5, PHP 7, PHP 8'/>
67+
<function name='clamp' from='PHP 8 &gt;= 8.6.0'/>
6768
<function name='compact' from='PHP 4, PHP 5, PHP 7, PHP 8'/>
6869
<function name='count' from='PHP 4, PHP 5, PHP 7, PHP 8'/>
6970
<function name='current' from='PHP 4, PHP 5, PHP 7, PHP 8'/>

‎reference/math/functions/clamp.xml‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<refentry xml:id="function.clamp" xmlns="http://docbook.org/ns/docbook">
4+
<refnamediv>
5+
<refname>clamp</refname>
6+
<refpurpose>Return the given value if in range, else return the nearest bound</refpurpose>
7+
</refnamediv>
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis>
11+
<type>mixed</type><methodname>clamp</methodname>
12+
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
13+
<methodparam><type>mixed</type><parameter>min</parameter></methodparam>
14+
<methodparam><type>mixed</type><parameter>max</parameter></methodparam>
15+
</methodsynopsis>
16+
<simpara>
17+
Return the given value if in range of <parameter>min</parameter> and <parameter>max</parameter>.
18+
Else if it's lower than <parameter>min</parameter>, return <parameter>min</parameter>.
19+
Else return <parameter>max</parameter>.
20+
</simpara>
21+
<note>
22+
<para>
23+
Values of different types will be compared using the <link linkend="language.operators.comparison">
24+
standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be
25+
compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric
26+
<type>string</type> values will be compared alphanumerically. The actual value returned will be of the
27+
original type with no conversion applied.
28+
</para>
29+
</note>
30+
<caution>
31+
<simpara>
32+
Be careful when passing arguments of different types because
33+
<function>clamp</function> can produce unpredictable results.
34+
</simpara>
35+
</caution>
36+
</refsect1>
37+
<refsect1 role="parameters">
38+
&reftitle.parameters;
39+
<variablelist>
40+
<varlistentry>
41+
<term><parameter>value</parameter></term>
42+
<listitem>
43+
<simpara>
44+
Any <link linkend="language.operators.comparison">comparable</link>
45+
value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>.
46+
</simpara>
47+
</listitem>
48+
</varlistentry>
49+
<varlistentry>
50+
<term><parameter>min</parameter></term>
51+
<listitem>
52+
<simpara>
53+
A <link linkend="language.operators.comparison">comparable</link> minimum to limit
54+
the <parameter>value</parameter> to.
55+
</simpara>
56+
</listitem>
57+
</varlistentry>
58+
<varlistentry>
59+
<term><parameter>max</parameter></term>
60+
<listitem>
61+
<simpara>
62+
A <link linkend="language.operators.comparison">comparable</link> maximum to limit
63+
the <parameter>value</parameter> to.
64+
</simpara>
65+
</listitem>
66+
</varlistentry>
67+
</variablelist>
68+
</refsect1>
69+
<refsect1 role="returnvalues">
70+
&reftitle.returnvalues;
71+
<simpara>
72+
<function>clamp</function> returns the parameter <parameter>value</parameter> if
73+
considered "between" <parameter>min</parameter> and <parameter>max</parameter> according to standard
74+
comparisons.
75+
</simpara>
76+
<simpara>
77+
If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be
78+
<constant>NAN</constant>.
79+
</simpara>
80+
</refsect1>
81+
82+
<refsect1 role="errors">
83+
&reftitle.errors;
84+
<simpara>
85+
If <parameter>min</parameter> is greater than <parameter>max</parameter>,
86+
<function>clamp</function> throws a <exceptionname>ValueError</exceptionname>.
87+
</simpara>
88+
<simpara>
89+
If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>,
90+
<function>clamp</function> throws a <exceptionname>ValueError</exceptionname>.
91+
</simpara>
92+
</refsect1>
93+
94+
<refsect1 role="examples">
95+
&reftitle.examples;
96+
<para>
97+
<example>
98+
<title>Example uses of <function>clamp</function></title>
99+
<programlisting role="php">
100+
<![CDATA[
101+
<?php
102+
echo clamp(-5, min: 0, max: 100), PHP_EOL; // 0
103+
echo clamp(55, min: 0, max: 100), PHP_EOL; // 55
104+
echo clamp(103, min: 0, max: 100), PHP_EOL; // 100
105+
106+
echo clamp("J", min: "A", max: "F"), PHP_EOL; // "F"
107+
108+
clamp(
109+
new \DateTimeImmutable('2025-08-01'),
110+
min: new \DateTimeImmutable('2025-08-15'),
111+
max: new \DateTimeImmutable('2025-09-15'),
112+
)->format('Y-m-d'), PHP_EOL; // 2025-08-15
113+
?>
114+
]]>
115+
</programlisting>
116+
</example>
117+
</para>
118+
119+
</refsect1>
120+
<refsect1 role="seealso">
121+
&reftitle.seealso;
122+
<para>
123+
<simplelist>
124+
<member><function>min</function></member>
125+
<member><function>max</function></member>
126+
</simplelist>
127+
</para>
128+
</refsect1>
129+
</refentry>
130+
<!-- Keep this comment at the end of the file
131+
Local variables:
132+
mode: sgml
133+
sgml-omittag:t
134+
sgml-shorttag:t
135+
sgml-minimize-attributes:nil
136+
sgml-always-quote-attributes:t
137+
sgml-indent-step:1
138+
sgml-indent-data:t
139+
indent-tabs-mode:nil
140+
sgml-parent-document:nil
141+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
142+
sgml-exposed-tags:nil
143+
sgml-local-catalogs:nil
144+
sgml-local-ecat-files:nil
145+
End:
146+
vim600: syn=xml fen fdm=syntax fdl=2 si
147+
vim: et tw=78 syn=sgml
148+
vi: ts=1 sw=1
149+
-->

0 commit comments

Comments
 (0)