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| }