123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437 |
- #elvdoc:fn rand
- #
- # ```elvish
- # rand
- # ```
- #
- # Output a pseudo-random number in the interval [0, 1). Example:
- #
- # ```elvish-transcript
- # ~> rand
- # ▶ 0.17843564133528436
- # ```
- #elvdoc:fn num
- #
- # ```elvish
- # num $string-or-number
- # ```
- #
- # Constructs a [typed number](./language.html#number).
- #
- # If the argument is a string, this command outputs the typed number the
- # argument represents, or raises an exception if the argument is not a valid
- # representation of a number. If the argument is already a typed number, this
- # command outputs it as is.
- #
- # This command is usually not needed for working with numbers; see the
- # discussion of [numeric commands](#numeric-commands).
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> num 10
- # ▶ (num 10)
- # ~> num 0x10
- # ▶ (num 16)
- # ~> num 1/12
- # ▶ (num 1/12)
- # ~> num 3.14
- # ▶ (num 3.14)
- # ~> num (num 10)
- # ▶ (num 10)
- # ```
- #
- # @cf exact-num inexact-num
- #elvdoc:fn exact-num
- #
- # ```elvish
- # exact-num $string-or-number
- # ```
- #
- # Coerces the argument to an exact number. If the argument is infinity or NaN,
- # an exception is thrown.
- #
- # If the argument is a string, it is converted to a typed number first. If the
- # argument is already an exact number, it is returned as is.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> exact-num (num 0.125)
- # ▶ (num 1/8)
- # ~> exact-num 0.125
- # ▶ (num 1/8)
- # ~> exact-num (num 1)
- # ▶ (num 1)
- # ```
- #
- # Beware that seemingly simple fractions that can't be represented precisely in
- # binary can result in the denominator being a very large power of 2:
- #
- # ```elvish-transcript
- # ~> exact-num 0.1
- # ▶ (num 3602879701896397/36028797018963968)
- # ```
- #
- # @cf num inexact-num
- #elvdoc:fn inexact-num
- #
- # ```elvish
- # inexact-num $string-or-number
- # ```
- #
- # Coerces the argument to an inexact number.
- #
- # If the argument is a string, it is converted to a typed number first. If the
- # argument is already an inexact number, it is returned as is.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> inexact-num (num 1)
- # ▶ (num 1.0)
- # ~> inexact-num (num 0.5)
- # ▶ (num 0.5)
- # ~> inexact-num (num 1/2)
- # ▶ (num 0.5)
- # ~> inexact-num 1/2
- # ▶ (num 0.5)
- # ```
- #
- # Since the underlying representation for inexact numbers has limited range,
- # numbers with very large magnitudes may be converted to an infinite value:
- #
- # ```elvish-transcript
- # ~> inexact-num 1000000000000000000
- # ▶ (num 1e+18)
- # ~> inexact-num 10000000000000000000
- # ▶ (num +Inf)
- # ~> inexact-num -10000000000000000000
- # ▶ (num -Inf)
- # ```
- #
- # Likewise, numbers with very small magnitudes may be converted to 0:
- #
- # ```elvish-transcript
- # ~> use math
- # ~> math:pow 10 -323
- # ▶ (num 1/100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000)
- # ~> inexact-num (math:pow 10 -323)
- # ▶ (num 1e-323)
- # ~> math:pow 10 -324
- # ▶ (num 1/1000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000)
- # ~> inexact-num (math:pow 10 -324)
- # ▶ (num 0.0)
- # ```
- #
- # @cf num exact-num
- #elvdoc:fn float64
- #
- # ```elvish
- # float64 $string-or-number
- # ```
- #
- # Constructs a floating-point number.
- #
- # This command is deprecated; use [`num`](#num) to construct a typed number, or
- # [`inexact-num`](#inexact-num) to construct an inexact number.
- #elvdoc:fn < <= == != > >= {#num-cmp}
- #
- # ```elvish
- # < $number... # less
- # <= $number... # less or equal
- # == $number... # equal
- # != $number... # not equal
- # > $number... # greater
- # >= $number... # greater or equal
- # ```
- #
- # Number comparisons. All of them accept an arbitrary number of arguments:
- #
- # 1. When given fewer than two arguments, all output `$true`.
- #
- # 2. When given two arguments, output whether the two arguments satisfy the named
- # relationship.
- #
- # 3. When given more than two arguments, output whether every adjacent pair of
- # numbers satisfy the named relationship.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> == 3 3.0
- # ▶ $true
- # ~> < 3 4
- # ▶ $true
- # ~> < 3 4 10
- # ▶ $true
- # ~> < 6 9 1
- # ▶ $false
- # ```
- #
- # As a consequence of rule 3, the `!=` command outputs `$true` as long as any
- # _adjacent_ pair of numbers are not equal, even if some numbers that are not
- # adjacent are equal:
- #
- # ```elvish-transcript
- # ~> != 5 5 4
- # ▶ $false
- # ~> != 5 6 5
- # ▶ $true
- # ```
- #elvdoc:fn + {#add}
- #
- # ```elvish
- # + $num...
- # ```
- #
- # Outputs the sum of all arguments, or 0 when there are no arguments.
- #
- # This command is [exactness-preserving](#exactness-preserving).
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> + 5 2 7
- # ▶ (num 14)
- # ~> + 1/2 1/3 1/4
- # ▶ (num 13/12)
- # ~> + 1/2 0.5
- # ▶ (num 1.0)
- # ```
- #elvdoc:fn - {#sub}
- #
- # ```elvish
- # - $x-num $y-num...
- # ```
- #
- # Outputs the result of subtracting from `$x-num` all the `$y-num`s, working
- # from left to right. When no `$y-num` is given, outputs the negation of
- # `$x-num` instead (in other words, `- $x-num` is equivalent to `- 0 $x-num`).
- #
- # This command is [exactness-preserving](#exactness-preserving).
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> - 5
- # ▶ (num -5)
- # ~> - 5 2
- # ▶ (num 3)
- # ~> - 5 2 7
- # ▶ (num -4)
- # ~> - 1/2 1/3
- # ▶ (num 1/6)
- # ~> - 1/2 0.3
- # ▶ (num 0.2)
- # ~> - 10
- # ▶ (num -10)
- # ```
- #elvdoc:fn * {#mul}
- #
- # ```elvish
- # * $num...
- # ```
- #
- # Outputs the product of all arguments, or 1 when there are no arguments.
- #
- # This command is [exactness-preserving](#exactness-preserving). Additionally,
- # when any argument is exact 0 and no other argument is a floating-point
- # infinity, the result is exact 0.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> * 2 5 7
- # ▶ (num 70)
- # ~> * 1/2 0.5
- # ▶ (num 0.25)
- # ~> * 0 0.5
- # ▶ (num 0)
- # ```
- #elvdoc:fn / {#div}
- #
- # ```elvish
- # / $x-num $y-num...
- # ```
- #
- # Outputs the result of dividing `$x-num` with all the `$y-num`s, working from
- # left to right. When no `$y-num` is given, outputs the reciprocal of `$x-num`
- # instead (in other words, `/ $y-num` is equivalent to `/ 1 $y-num`).
- #
- # Dividing by exact 0 raises an exception. Dividing by inexact 0 results with
- # either infinity or NaN according to floating-point semantics.
- #
- # This command is [exactness-preserving](#exactness-preserving). Additionally,
- # when `$x-num` is exact 0 and no `$y-num` is exact 0, the result is exact 0.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> / 2
- # ▶ (num 1/2)
- # ~> / 2.0
- # ▶ (num 0.5)
- # ~> / 10 5
- # ▶ (num 2)
- # ~> / 2 5
- # ▶ (num 2/5)
- # ~> / 2 5 7
- # ▶ (num 2/35)
- # ~> / 0 1.0
- # ▶ (num 0)
- # ~> / 2 0
- # Exception: bad value: divisor must be number other than exact 0, but is exact 0
- # [tty 6], line 1: / 2 0
- # ~> / 2 0.0
- # ▶ (num +Inf)
- # ```
- #
- # When given no argument, this command is equivalent to `cd /`, due to the
- # implicit cd feature. (The implicit cd feature will probably change to avoid
- # this oddity).
- #elvdoc:fn % {#rem}
- #
- # ```elvish
- # % $x $y
- # ```
- #
- # Outputs the remainder after dividing `$x` by `$y`. The result has the same
- # sign as `$x`.
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> % 10 3
- # ▶ (num 1)
- # ~> % -10 3
- # ▶ (num -1)
- # ~> % 10 -3
- # ▶ (num 1)
- # ```
- #
- # Note that `%` requires both arguments to be within the range of signed
- # integers the size of a [machine
- # word](https://en.wikipedia.org/wiki/Word_(computer_architecture)), and throws
- # an exception otherwise:
- #
- # ```elvish-transcript
- # ~> % (math:pow 2 63) 3
- # Exception: wrong type for arg #0: must be integer
- # ```
- #
- # This limit may be lifted in the future.
- #elvdoc:fn randint
- #
- # ```elvish
- # randint $low? $high
- # ```
- #
- # Output a pseudo-random integer N such that `$low <= N < $high`. If not given,
- # `$low` defaults to 0. Examples:
- #
- # ```elvish-transcript
- # ~> # Emulate dice
- # randint 1 7
- # ▶ 6
- # ```
- #elvdoc:fn -randseed
- #
- # ```elvish
- # -randseed $seed
- # ```
- #
- # Sets the seed for the random number generator.
- #elvdoc:fn range
- #
- # ```elvish
- # range &step $start=0 $end
- # ```
- #
- # Outputs numbers, starting from `$start` and ending before `$end`, using
- # `&step` as the increment.
- #
- # - If `$start` <= `$end`, `&step` defaults to 1, and `range` outputs values as
- # long as they are smaller than `$end`. An exception is thrown if `&step` is
- # given a negative value.
- #
- # - If `$start` > `$end`, `&step` defaults to -1, and `range` outputs values as
- # long as they are greater than `$end`. An exception is thrown if `&step` is
- # given a positive value.
- #
- # As a special case, if the outputs are floating point numbers, `range` also
- # terminates if the values stop changing.
- #
- # This command is [exactness-preserving](#exactness-preserving).
- #
- # Examples:
- #
- # ```elvish-transcript
- # ~> range 4
- # ▶ (num 0)
- # ▶ (num 1)
- # ▶ (num 2)
- # ▶ (num 3)
- # ~> range 4 0
- # ▶ (num 4)
- # ▶ (num 3)
- # ▶ (num 2)
- # ▶ (num 1)
- # ~> range -3 3 &step=2
- # ▶ (num -3)
- # ▶ (num -1)
- # ▶ (num 1)
- # ~> range 3 -3 &step=-2
- # ▶ (num 3)
- # ▶ (num 1)
- # ▶ (num -1)
- # ~> range (- (math:pow 2 53) 1) +inf
- # ▶ (num 9007199254740991.0)
- # ▶ (num 9007199254740992.0)
- # ```
- #
- # When using floating-point numbers, beware that numerical errors can result in
- # an incorrect number of outputs:
- #
- # ```elvish-transcript
- # ~> range 0.9 &step=0.3
- # ▶ (num 0.0)
- # ▶ (num 0.3)
- # ▶ (num 0.6)
- # ▶ (num 0.8999999999999999)
- # ```
- #
- # Avoid this problem by using exact rationals:
- #
- # ```elvish-transcript
- # ~> range 9/10 &step=3/10
- # ▶ (num 0)
- # ▶ (num 3/10)
- # ▶ (num 3/5)
- # ```
- #
- # One usage of this command is to execute something a fixed number of times by
- # combining with [each](#each):
- #
- # ```elvish-transcript
- # ~> range 3 | each {|_| echo foo }
- # foo
- # foo
- # foo
- # ```
- #
- # Etymology:
- # [Python](https://docs.python.org/3/library/functions.html#func-range).
|