Skip to content

Document clamp function #2237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
+157 −0
Draft

Document clamp function #2237

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 157 additions & 0 deletions reference/math/functions/clamp.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 761d72245071f89a626903c9bcdc6aaff1252d54 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.clamp" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>clamp</refname>
<refpurpose>Retourne la valeur d'entrée si elle est comprise entre 2 bornes, sinon retourne la borne la plus proche</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>
<para>
Retourne la valeur d'entrée si elle est comprise entre <parameter>min</parameter> et <parameter>max</parameter>.
Si elle est inférieur à <parameter>min</parameter>, retourne <parameter>min</parameter>.
Sinon retourne <parameter>max</parameter>.
</para>
<note>
<para>
Les valeurs de différents types seront comparées en utilisant
les <link linkend="language.operators.comparison">règles de
comparaison standard</link>. Actuellement, une chaîne non numérique
sera comparée à un &integer;, comme s'il s'agissait de la valeur
<literal>0</literal>, mais plusieurs &string; non-numérique seront comparées de façon
alphanumérique. La valeur actuelle retournée sera du même type que
l'original et aucune conversion de type ne sera appliquée.
</para>
</note>
<caution>
<simpara>
Soyez prudent lorsque vous passez des arguments avec des types différents,
car <function>clamp</function> peut produire des résultats imprévisibles.
</simpara>
</caution>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
Toute valeur <link linkend="language.operators.comparison">comparable</link> à resserrer entre
<parameter>min</parameter> et <parameter>max</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>min</parameter></term>
<listitem>
<para>
Une valeur minimum <link linkend="language.operators.comparison">comparable</link>
à laquelle contraindre <parameter>value</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>max</parameter></term>
<listitem>
<para>
Une valeur maximum <link linkend="language.operators.comparison">comparable</link>
à laquelle contraindre <parameter>value</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
La fonction <function>clamp</function> retourne le paramètre <parameter>value</parameter>
s'il est considéré comme "entre" <parameter>min</parameter> et <parameter>max</parameter>
suivant la comparaison standard.
Si plusieurs valeurs de types différents sont évaluées comme étant égales
(i.e. <literal>0</literal> et <literal>'abc'</literal>), la première fournie
à la fonction sera retournée.
</para>
<para>
Si <parameter>value</parameter> est <constant>NAN</constant>, alors la valeur de retour
est également <constant>NAN</constant>.
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
Si <parameter>min</parameter> est supérieur à <parameter>max</parameter>,
la fonction <function>clamp</function> lance une <classname>ValueError</classname>.
</para>
<para>
Si <parameter>min</parameter> ou <parameter>max</parameter> est <constant>NAN</constant>,
la fonction <function>clamp</function> lance une <classname>ValueError</classname>.
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Exemple avec <function>clamp</function></title>
<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>
</example>
</para>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>min</function></member>
<member><function>max</function></member>
</simplelist>
</para>
</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
-->