README.md (4391B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # clamp 22 23 > Restrict a double-precision floating-point number to a specified range. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var clamp = require( '@stdlib/math/base/special/clamp' ); 41 ``` 42 43 #### clamp( v, min, max ) 44 45 Restricts a double-precision floating-point number to a specified range. 46 47 ```javascript 48 var v = clamp( 3.14, 0.0, 5.0 ); 49 // returns 3.14 50 51 v = clamp( -3.14, 0.0, 5.0 ); 52 // returns 0.0 53 54 v = clamp( 10.0, 0.0, 5.0 ); 55 // returns 5.0 56 57 v = clamp( -0.0, 0.0, 5.0 ); 58 // returns 0.0 59 60 v = clamp( 0.0, -3.14, -0.0 ); 61 // returns -0.0 62 ``` 63 64 If provided `NaN` for any argument, the function returns `NaN`. 65 66 ```javascript 67 var v = clamp( NaN, 0.0, 5.0 ); 68 // returns NaN 69 70 v = clamp( 0.0, NaN, 5.0 ); 71 // returns NaN 72 73 v = clamp( 3.14, 0.0, NaN ); 74 // returns NaN 75 ``` 76 77 </section> 78 79 <!-- /.usage --> 80 81 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 82 83 <section class="notes"> 84 85 </section> 86 87 <!-- /.notes --> 88 89 <!-- Package usage examples. --> 90 91 <section class="examples"> 92 93 ## Examples 94 95 <!-- eslint no-undef: "error" --> 96 97 ```javascript 98 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); 99 var clamp = require( '@stdlib/math/base/special/clamp' ); 100 101 var min; 102 var max; 103 var v; 104 var i; 105 106 for ( i = 0; i < 100; i++ ) { 107 min = discreteUniform( 0.0, 10.0 ); 108 max = discreteUniform( 5.0, 15.0 ); 109 v = discreteUniform( -20.0, 20.0 ); 110 console.log( 'clamp(%d,%d,%d) => %d', v, min, max, clamp( v, min, max ) ); 111 } 112 ``` 113 114 </section> 115 116 <!-- /.examples --> 117 118 <!-- C interface documentation. --> 119 120 * * * 121 122 <section class="c"> 123 124 ## C APIs 125 126 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 127 128 <section class="intro"> 129 130 </section> 131 132 <!-- /.intro --> 133 134 <!-- C usage documentation. --> 135 136 <section class="usage"> 137 138 ### Usage 139 140 ```c 141 #include "stdlib/math/base/special/clamp.h" 142 ``` 143 144 #### stdlib_base_clamp( v, min, max ) 145 146 Restricts a double-precision floating-point number to a specified range. 147 148 ```c 149 double y = stdlib_base_clamp( -3.14, 0.0, 5.0 ); 150 // returns 0.0 151 ``` 152 153 The function accepts the following arguments: 154 155 - **v**: `[in] double` input value. 156 - **min**: `[in] double` minimum value. 157 - **max**: `[in] double` maximum value. 158 159 ```c 160 double stdlib_base_clamp( const double v, const double min, const double max ); 161 ``` 162 163 </section> 164 165 <!-- /.usage --> 166 167 <!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 168 169 <section class="notes"> 170 171 </section> 172 173 <!-- /.notes --> 174 175 <!-- C API usage examples. --> 176 177 <section class="examples"> 178 179 ### Examples 180 181 ```c 182 #include "stdlib/math/base/special/clamp.h" 183 #include <stdio.h> 184 185 int main() { 186 double x[] = { 3.14, -3.14, 0.0, 0.0/0.0 }; 187 188 double y; 189 int i; 190 for ( i = 0; i < 4; i++ ) { 191 y = stdlib_base_clamp( x[ i ], -3.0, 3.0 ); 192 printf( "clamp(%lf, %lf, %lf) = %lf\n", x[ i ], -3.0, 3.0, y ); 193 } 194 } 195 ``` 196 197 </section> 198 199 <!-- /.examples --> 200 201 </section> 202 203 <!-- /.c --> 204 205 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 206 207 <section class="references"> 208 209 </section> 210 211 <!-- /.references --> 212 213 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 214 215 <section class="links"> 216 217 </section> 218 219 <!-- /.links -->