Skip to content

Commit ddab889

Browse files
kylekatarnlskylekatarnls
committed
Document clamp function
1 parent 1bcc40f commit ddab889

File tree

3 files changed

+186
-0
lines changed

3 files changed

+186
-0
lines changed

‎appendices/migration85/new-functions.xml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<sect1 xml:id="migration85.new-functions">
3+
<title>New Functions</title>
4+
5+
<sect2 xml:id="migration85.new-functions.core">
6+
<title>Core</title>
7+
8+
<simplelist>
9+
<!-- RFC: https://wiki.php.net/rfc/clamp -->
10+
<member><function>clamp</function></member>
11+
</simplelist>
12+
</sect2>
13+
14+
</sect1>
15+
<!-- Keep this comment at the end of the file
16+
Local variables:
17+
mode: sgml
18+
sgml-omittag:t
19+
sgml-shorttag:t
20+
sgml-minimize-attributes:nil
21+
sgml-always-quote-attributes:t
22+
sgml-indent-step:1
23+
sgml-indent-data:t
24+
indent-tabs-mode:nil
25+
sgml-parent-document:nil
26+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
27+
sgml-exposed-tags:nil
28+
sgml-local-catalogs:nil
29+
sgml-local-ecat-files:nil
30+
End:
31+
vim600: syn=xml fen fdm=syntax fdl=2 si
32+
vim: et tw=78 syn=sgml
33+
vi: ts=1 sw=1
34+
-->

‎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.5.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: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
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+
<para>
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+
</para>
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+
<para>
40+
<variablelist>
41+
<varlistentry>
42+
<term><parameter>value</parameter></term>
43+
<listitem>
44+
<para>
45+
Any <link linkend="language.operators.comparison">comparable</link>
46+
value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>.
47+
</para>
48+
</listitem>
49+
</varlistentry>
50+
<varlistentry>
51+
<term><parameter>min</parameter></term>
52+
<listitem>
53+
<para>
54+
A <link linkend="language.operators.comparison">comparable</link> minimum to limit
55+
the <parameter>value</parameter> to.
56+
</para>
57+
</listitem>
58+
</varlistentry>
59+
<varlistentry>
60+
<term><parameter>max</parameter></term>
61+
<listitem>
62+
<para>
63+
A <link linkend="language.operators.comparison">comparable</link> maximum to limit
64+
the <parameter>value</parameter> to.
65+
</para>
66+
</listitem>
67+
</varlistentry>
68+
</variablelist>
69+
</para>
70+
</refsect1>
71+
<refsect1 role="returnvalues">
72+
&reftitle.returnvalues;
73+
<para>
74+
<function>clamp</function> returns the parameter <parameter>value</parameter> if
75+
considered "between" <parameter>min</parameter> and <parameter>max</parameter> according to standard
76+
comparisons.
77+
</para>
78+
<para>
79+
If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be
80+
<constant>NAN</constant>.
81+
</para>
82+
</refsect1>
83+
84+
<refsect1 role="errors">
85+
&reftitle.errors;
86+
<para>
87+
If <parameter>min</parameter> is greater than <parameter>max</parameter>,
88+
<function>clamp</function> throws a <classname>ValueError</classname>.
89+
</para>
90+
<para>
91+
If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>,
92+
<function>clamp</function> throws a <classname>ValueError</classname>.
93+
</para>
94+
</refsect1>
95+
96+
<refsect1 role="examples">
97+
&reftitle.examples;
98+
<para>
99+
<example>
100+
<title>Example uses of <function>clamp</function></title>
101+
<programlisting role="php">
102+
<![CDATA[
103+
<?php
104+
echo clamp(-5, min: 0, max: 100), PHP_EOL; // 0
105+
echo clamp(55, min: 0, max: 100), PHP_EOL; // 55
106+
echo clamp(103, min: 0, max: 100), PHP_EOL; // 100
107+
108+
echo clamp("J", min: "A", max: "F"), PHP_EOL; // "F"
109+
110+
clamp(
111+
new \DateTimeImmutable('2025-08-01'),
112+
min: new \DateTimeImmutable('2025-08-15'),
113+
max: new \DateTimeImmutable('2025-09-15'),
114+
)->format('Y-m-d'), PHP_EOL; // 2025-08-15
115+
?>
116+
]]>
117+
</programlisting>
118+
</example>
119+
</para>
120+
121+
</refsect1>
122+
<refsect1 role="seealso">
123+
&reftitle.seealso;
124+
<para>
125+
<simplelist>
126+
<member><function>min</function></member>
127+
<member><function>max</function></member>
128+
</simplelist>
129+
</para>
130+
</refsect1>
131+
</refentry>
132+
<!-- Keep this comment at the end of the file
133+
Local variables:
134+
mode: sgml
135+
sgml-omittag:t
136+
sgml-shorttag:t
137+
sgml-minimize-attributes:nil
138+
sgml-always-quote-attributes:t
139+
sgml-indent-step:1
140+
sgml-indent-data:t
141+
indent-tabs-mode:nil
142+
sgml-parent-document:nil
143+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
144+
sgml-exposed-tags:nil
145+
sgml-local-catalogs:nil
146+
sgml-local-ecat-files:nil
147+
End:
148+
vim600: syn=xml fen fdm=syntax fdl=2 si
149+
vim: et tw=78 syn=sgml
150+
vi: ts=1 sw=1
151+
-->

0 commit comments

Comments
 (0)