src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/eval/builtin_fn_num.d.elv (about) 1 #//skip-test 2 # Output a pseudo-random number in the interval [0, 1). Example: 3 # 4 # ```elvish-transcript 5 # ~> rand 6 # ▶ 0.17843564133528436 7 # ``` 8 fn rand { } 9 10 # Constructs a [typed number](language.html#number). 11 # 12 # If the argument is a string, this command outputs the typed number the 13 # argument represents, or raises an exception if the argument is not a valid 14 # representation of a number. If the argument is already a typed number, this 15 # command outputs it as is. 16 # 17 # This command is usually not needed for working with numbers; see the 18 # discussion of [numeric commands](#numeric-commands). 19 # 20 # Examples: 21 # 22 # ```elvish-transcript 23 # ~> num 10 24 # ▶ (num 10) 25 # ~> num 0x10 26 # ▶ (num 16) 27 # ~> num 1/12 28 # ▶ (num 1/12) 29 # ~> num 3.14 30 # ▶ (num 3.14) 31 # ~> num (num 10) 32 # ▶ (num 10) 33 # ``` 34 # 35 # See also [`exact-num`]() and [`inexact-num`](). 36 fn num {|string-or-number| } 37 38 # Coerces the argument to an exact number. If the argument is infinity or NaN, 39 # an exception is thrown. 40 # 41 # If the argument is a string, it is converted to a typed number first. If the 42 # argument is already an exact number, it is returned as is. 43 # 44 # Examples: 45 # 46 # ```elvish-transcript 47 # ~> exact-num (num 0.125) 48 # ▶ (num 1/8) 49 # ~> exact-num 0.125 50 # ▶ (num 1/8) 51 # ~> exact-num (num 1) 52 # ▶ (num 1) 53 # ``` 54 # 55 # Beware that seemingly simple fractions that can't be represented precisely in 56 # binary can result in the denominator being a very large power of 2: 57 # 58 # ```elvish-transcript 59 # ~> exact-num 0.1 60 # ▶ (num 3602879701896397/36028797018963968) 61 # ``` 62 # 63 # See also [`num`]() and [`inexact-num`](). 64 fn exact-num {|string-or-number| } 65 66 # Coerces the argument to an inexact number. 67 # 68 # If the argument is a string, it is converted to a typed number first. If the 69 # argument is already an inexact number, it is returned as is. 70 # 71 # Examples: 72 # 73 # ```elvish-transcript 74 # ~> inexact-num (num 1) 75 # ▶ (num 1.0) 76 # ~> inexact-num (num 0.5) 77 # ▶ (num 0.5) 78 # ~> inexact-num (num 1/2) 79 # ▶ (num 0.5) 80 # ~> inexact-num 1/2 81 # ▶ (num 0.5) 82 # ``` 83 # 84 # Since the underlying representation for inexact numbers has limited range, 85 # numbers with very large magnitudes may be converted to an infinite value: 86 # 87 # ```elvish-transcript 88 # ~> inexact-num 1000000000000000000 89 # ▶ (num 1e+18) 90 # ~> inexact-num 10000000000000000000 91 # ▶ (num +Inf) 92 # ~> inexact-num -10000000000000000000 93 # ▶ (num -Inf) 94 # ``` 95 # 96 # Likewise, numbers with very small magnitudes may be converted to 0: 97 # 98 # ```elvish-transcript 99 # ~> use math 100 # ~> math:pow 10 -323 101 # ▶ (num 1/100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000) 102 # ~> inexact-num (math:pow 10 -323) 103 # ▶ (num 1e-323) 104 # ~> math:pow 10 -324 105 # ▶ (num 1/1000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000) 106 # ~> inexact-num (math:pow 10 -324) 107 # ▶ (num 0.0) 108 # ``` 109 # 110 # See also [`num`]() and [`exact-num`](). 111 fn inexact-num {|string-or-number| } 112 113 #doc:html-id num-lt 114 # Outputs whether `$number`s in the given order are numerically strictly 115 # increasing. Outputs `$true` when given fewer than two numbers. 116 # 117 # Examples: 118 # 119 # ```elvish-transcript 120 # ~> < 1 2 121 # ▶ $true 122 # ~> < 2 1 123 # ▶ $false 124 # ~> < 1 2 3 125 # ▶ $true 126 # ``` 127 # 128 fn '<' {|@number| } 129 130 #doc:html-id num-le 131 # Outputs whether `$number`s in the given order are numerically non-decreaing. 132 # Outputs `$true` when given fewer than two numbers. 133 # 134 # Examples: 135 # 136 # ```elvish-transcript 137 # ~> <= 1 1 138 # ▶ $true 139 # ~> <= 2 1 140 # ▶ $false 141 # ~> <= 1 1 2 142 # ▶ $true 143 # ``` 144 fn '<=' {|@number| } 145 146 #doc:html-id num-eq 147 # Outputs whether `$number`s are all numerically equal. Outputs `$true` when 148 # given fewer than two numbers. 149 # 150 # Examples: 151 # 152 # ```elvish-transcript 153 # ~> == 1 1 154 # ▶ $true 155 # ~> == 1 (num 1) 156 # ▶ $true 157 # ~> == 1 (num 1) 1 158 # ▶ $true 159 # ~> == 1 (num 1) 1.0 160 # ▶ $true 161 # ~> == 1 2 162 # ▶ $false 163 # ``` 164 fn '==' {|@number| } 165 166 #doc:html-id num-ne 167 # Determines whether `$a` and `$b` are numerically inequal. Equivalent to `not 168 # (== $a $b)`. 169 # 170 # Examples: 171 # 172 # ```elvish-transcript 173 # ~> != 1 2 174 # ▶ $true 175 # ~> != 1 1 176 # ▶ $false 177 # ``` 178 fn '!=' {|a b| } 179 180 #doc:html-id num-gt 181 # Determines whether `$number`s in the given order are numerically strictly 182 # decreasing. Outputs `$true` when given fewer than two numbers. 183 # 184 # Examples: 185 # 186 # ```elvish-transcript 187 # ~> > 2 1 188 # ▶ $true 189 # ~> > 1 2 190 # ▶ $false 191 # ~> > 3 2 1 192 # ▶ $true 193 # ``` 194 fn '>' {|@number| } 195 196 #doc:html-id num-ge 197 # Outputs whether `$number`s in the given order are numerically non-increasing. 198 # Outputs `$true` when given fewer than two numbers. 199 # 200 # Examples: 201 # 202 # ```elvish-transcript 203 # ~> >= 1 1 204 # ▶ $true 205 # ~> >= 1 2 206 # ▶ $false 207 # ~> >= 2 1 1 208 # ▶ $true 209 # ``` 210 fn '>=' {|@number| } 211 212 #doc:html-id add 213 # Outputs the sum of all arguments, or 0 when there are no arguments. 214 # 215 # This command is [exactness-preserving](#exactness-preserving). 216 # 217 # Examples: 218 # 219 # ```elvish-transcript 220 # ~> + 5 2 7 221 # ▶ (num 14) 222 # ~> + 1/2 1/3 1/4 223 # ▶ (num 13/12) 224 # ~> + 1/2 0.5 225 # ▶ (num 1.0) 226 # ``` 227 fn + {|@num| } 228 229 #doc:html-id sub 230 # Outputs the result of subtracting from `$x-num` all the `$y-num`s, working 231 # from left to right. When no `$y-num` is given, outputs the negation of 232 # `$x-num` instead (in other words, `- $x-num` is equivalent to `- 0 $x-num`). 233 # 234 # This command is [exactness-preserving](#exactness-preserving). 235 # 236 # Examples: 237 # 238 # ```elvish-transcript 239 # ~> - 5 240 # ▶ (num -5) 241 # ~> - 5 2 242 # ▶ (num 3) 243 # ~> - 5 2 7 244 # ▶ (num -4) 245 # ~> - 1/2 1/3 246 # ▶ (num 1/6) 247 # ~> - 1/2 0.3 248 # ▶ (num 0.2) 249 # ~> - 10 250 # ▶ (num -10) 251 # ``` 252 fn - {|x-num @y-num| } 253 254 #doc:html-id mul 255 # Outputs the product of all arguments, or 1 when there are no arguments. 256 # 257 # This command is [exactness-preserving](#exactness-preserving). Additionally, 258 # when any argument is exact 0 and no other argument is a floating-point 259 # infinity, the result is exact 0. 260 # 261 # Examples: 262 # 263 # ```elvish-transcript 264 # ~> * 2 5 7 265 # ▶ (num 70) 266 # ~> * 1/2 0.5 267 # ▶ (num 0.25) 268 # ~> * 0 0.5 269 # ▶ (num 0) 270 # ``` 271 fn * {|@num| } 272 273 #doc:html-id div 274 # Outputs the result of dividing `$x-num` with all the `$y-num`s, working from 275 # left to right. When no `$y-num` is given, outputs the reciprocal of `$x-num` 276 # instead (in other words, `/ $y-num` is equivalent to `/ 1 $y-num`). 277 # 278 # Dividing by exact 0 raises an exception. Dividing by inexact 0 results with 279 # either infinity or NaN according to floating-point semantics. 280 # 281 # This command is [exactness-preserving](#exactness-preserving). Additionally, 282 # when `$x-num` is exact 0 and no `$y-num` is exact 0, the result is exact 0. 283 # 284 # Examples: 285 # 286 # ```elvish-transcript 287 # ~> / 2 288 # ▶ (num 1/2) 289 # ~> / 2.0 290 # ▶ (num 0.5) 291 # ~> / 10 5 292 # ▶ (num 2) 293 # ~> / 2 5 294 # ▶ (num 2/5) 295 # ~> / 2 5 7 296 # ▶ (num 2/35) 297 # ~> / 0 1.0 298 # ▶ (num 0) 299 # ~> / 2 0 300 # Exception: bad value: divisor must be number other than exact 0, but is exact 0 301 # [tty]:1:1-5: / 2 0 302 # ~> / 2 0.0 303 # ▶ (num +Inf) 304 # ``` 305 # 306 # When given no argument, this command is equivalent to `cd /`, due to the 307 # implicit cd feature. (The implicit cd feature is deprecated since 0.21.0). 308 fn / {|x-num @y-num| } 309 310 #doc:html-id rem 311 # Outputs the remainder after dividing `$x` by `$y`. The result has the same 312 # sign as `$x`. Both arguments must be exact integers. 313 # 314 # Examples: 315 # 316 # ```elvish-transcript 317 # ~> % 10 3 318 # ▶ (num 1) 319 # ~> % -10 3 320 # ▶ (num -1) 321 # ~> % 10 -3 322 # ▶ (num 1) 323 # ~> % 10000000000000000000 3 324 # ▶ (num 1) 325 # ~> % 10.0 3 326 # Exception: bad value: argument must be exact integer, but is (num 10.0) 327 # [tty]:1:1-8: % 10.0 3 328 # ``` 329 # 330 # This limit may be lifted in the future. 331 fn % {|x y| } 332 333 #//skip-test 334 # Output a pseudo-random integer N such that `$low <= N < $high`. If not given, 335 # `$low` defaults to 0. Examples: 336 # 337 # ```elvish-transcript 338 # ~> # Emulate dice 339 # randint 1 7 340 # ▶ 6 341 # ``` 342 fn randint {|low? high| } 343 344 #doc:show-unstable 345 # Sets the seed for the random number generator. 346 fn -randseed {|seed| } 347 348 # Outputs numbers, starting from `$start` and ending before `$end`, using 349 # `&step` as the increment. 350 # 351 # - If `$start` <= `$end`, `&step` defaults to 1, and `range` outputs values as 352 # long as they are smaller than `$end`. An exception is thrown if `&step` is 353 # given a negative value. 354 # 355 # - If `$start` > `$end`, `&step` defaults to -1, and `range` outputs values as 356 # long as they are greater than `$end`. An exception is thrown if `&step` is 357 # given a positive value. 358 # 359 # As a special case, if the outputs are floating point numbers, `range` also 360 # terminates if the values stop changing. 361 # 362 # This command is [exactness-preserving](#exactness-preserving). 363 # 364 # Examples: 365 # 366 # ```elvish-transcript 367 # ~> range 4 368 # ▶ (num 0) 369 # ▶ (num 1) 370 # ▶ (num 2) 371 # ▶ (num 3) 372 # ~> range 4 0 373 # ▶ (num 4) 374 # ▶ (num 3) 375 # ▶ (num 2) 376 # ▶ (num 1) 377 # ~> range -3 3 &step=2 378 # ▶ (num -3) 379 # ▶ (num -1) 380 # ▶ (num 1) 381 # ~> range 3 -3 &step=-2 382 # ▶ (num 3) 383 # ▶ (num 1) 384 # ▶ (num -1) 385 # ~> use math 386 # ~> range (- (math:pow 2 53) 1) +inf 387 # ▶ (num 9007199254740991.0) 388 # ▶ (num 9007199254740992.0) 389 # ``` 390 # 391 # When using floating-point numbers, beware that numerical errors can result in 392 # an incorrect number of outputs: 393 # 394 # ```elvish-transcript 395 # ~> range 0.9 &step=0.3 396 # ▶ (num 0.0) 397 # ▶ (num 0.3) 398 # ▶ (num 0.6) 399 # ▶ (num 0.8999999999999999) 400 # ``` 401 # 402 # Avoid this problem by using exact rationals: 403 # 404 # ```elvish-transcript 405 # ~> range 9/10 &step=3/10 406 # ▶ (num 0) 407 # ▶ (num 3/10) 408 # ▶ (num 3/5) 409 # ``` 410 # 411 # One usage of this command is to execute something a fixed number of times by 412 # combining with [each](#each): 413 # 414 # ```elvish-transcript 415 # ~> range 3 | each {|_| echo foo } 416 # foo 417 # foo 418 # foo 419 # ``` 420 # 421 # Etymology: 422 # [Python](https://docs.python.org/3/library/functions.html#func-range). 423 fn range {|&step start=0 end| }