[ { "name": "Random.PCG.Interop", "comment": " Provides a function to create a PCG seed from a seed in the core library.\nThis is useful for library writers who need a splittable or most robust PRNG but\ndon't want to require client code to use the PCG implementation.\n\n```elm\nimport Random\nimport Random.PCG\nimport Random.PCG.Interop as Random.PCG\n```\n\n@docs fission\n", "unions": [], "aliases": [], "values": [ { "name": "fission", "comment": " Use the core library's random seed to produce a PCG random seed.\n\nIt seems that the package website doesn't show modules in type annotations, so here it is in full:\n\n fission : Random.Seed -> (Random.PCG.Seed, Random.Seed)\n\n", "type": "Seed -> ( Seed, Seed )" } ], "binops": [] }, { "name": "Random.PCG", "comment": " Generate psuedo-random numbers and values, by constructing\n[generators](#Generator) for them. There are a bunch of basic generators like\n[`bool`](#bool) and [`int`](#int) that you can build up into fancier generators\nwith functions like [`list`](#list) and [`map`](#map).\n\nYou run a `Generator` by calling the [`generate`](#generate) function, which\nalso takes a random [`Seed`](#Seed), and passes back a new seed. You should\nnever use the same seed twice because you will get the same result! If you need\nrandom values over time, you should store the most recent seed in your model. If\nyou have several independent models, you can [`split`](#split) seeds into more\nseeds.\n\nThis is an implementation of [PCG](http://www.pcg-random.org/) by M. E. O'Neil,\nand is not cryptographically secure.\n\n# Getting Started\n@docs initialSeed2, generate\n\n# Basic Generators\n@docs Generator, bool, int, float\n\n# Data Structure Generators\n@docs pair, list\n\n# Custom Generators\n@docs constant, map, map2, map3, map4, map5, andMap, andThen, filter\n\n# Working With Seeds\n@docs initialSeed, split, fastForward, Seed\n\n# Constants\n@docs maxInt, minInt\n", "unions": [ { "name": "Generator", "comment": " A `Generator` is like a recipe for generating certain random values. So a\n`Generator Int` describes how to generate integers and a `Generator String`\ndescribes how to generate strings.\n", "args": [ "a" ], "cases": [] }, { "name": "Seed", "comment": " A `Seed` is the source of randomness in the whole system. It hides the\ncurrent state of the random number generator.\n", "args": [], "cases": [] } ], "aliases": [], "values": [ { "name": "andMap", "comment": " Map over any number of generators.\n\n randomPerson =\n person `map` genFirstName\n `andMap` genLastName\n `andMap` genBirthday\n `andMap` genPhoneNumber\n", "type": "Generator (a -> b) -> Generator a -> Generator b" }, { "name": "andThen", "comment": " Chain random operations by providing a callback that accepts a\nrandomly-generated value. This all happens inside the generator, and the seed is\nmanaged for you.\n\nIn the following example, we will generate a random letter by putting together\nuppercase and lowercase letters.\n\n letter : Generator Char\n letter =\n bool `andThen` \\b ->\n if b then genUppercaseLetter else genLowercaseLetter\n\nIf you find yourself calling `constant` in every branch of the callback, you can\nprobably use `map` instead.\n", "type": "Generator a -> (a -> Generator b) -> Generator b" }, { "name": "bool", "comment": " Create a generator that produces boolean values. The following example\nsimulates a coin flip that may land heads or tails.\n\n type Flip = Heads | Tails\n\n coinFlip : Generator Flip\n coinFlip =\n map (\\b -> if b then Heads else Tails) bool\n", "type": "Generator Bool" }, { "name": "constant", "comment": " Create a generator that always produces the value provided. This is useful\nwhen creating complicated chained generators and you need to handle a simple\ncase. It's also useful for the base case of recursive generators.\n", "type": "a -> Generator a" }, { "name": "fastForward", "comment": " Fast forward a seed the given number of steps, which may be negative (the\nseed will be \"rewound\"). This allows a single seed to serve as a random-access\nlookup table of random numbers. (To be sure no one else uses the seed,\n[`split`](#split) off your own).\n\n diceRollTable : Int -> Int\n diceRollTable i =\n fastForward i mySeed |> generate (int 1 6) |> fst\n", "type": "Int -> Seed -> Seed" }, { "name": "filter", "comment": " Filter a generator so that all generated values satisfy the given predicate.\n\n evens : Generator Int\n evens =\n filter (\\i -> i % 2 == 0) (int minInt maxInt)\n\nIf the predicate is unsatisfiable, the generator will not terminate, your\napplication will crash with a stack overflow, and you will be sad. You should\nalso avoid predicates that are merely very difficult to satisfy.\n\n badCrashingGenerator =\n filter (\\_ -> False) anotherGenerator\n\n likelyCrashingGenerator =\n filter (\\i -> i % 2000 == 0) (int minInt maxInt)\n", "type": "(a -> Bool) -> Generator a -> Generator a" }, { "name": "float", "comment": " Generate floats in a given range. The following example is a generator\nthat produces decimals between 0 and 1.\n\n probability : Generator Float\n probability =\n float 0 1\n", "type": "Float -> Float -> Generator Float" }, { "name": "generate", "comment": " Generate a random value as specified by a given `Generator`, using a `Seed`\nand returning a new one.\n\nIn the following example, we are trying to generate numbers between 0 and 100\nwith the `int 0 100` generator. Each time we call `generate` we need to provide\na seed. This will produce a random number and a *new* seed to use if we want to\nrun other generators later.\n\n (x, seed1) = generate (int 0 100) seed0\n (y, seed2) = generate (int 0 100) seed1\n (z, seed3) = generate (int 0 100) seed2\n [x, y, z] -- [85, 0, 38]\n\nNotice that we use different seeds on each line. This is important! If you reuse\nthe same seed, you get the same results.\n\n (x, _) = generate (int 0 100) seed0\n (y, _) = generate (int 0 100) seed0\n (z, _) = generate (int 0 100) seed0\n [x,y,z] -- [85, 85, 85]\n\nOf course, threading seeds through many calls to `generate` is tedious and\nerror-prone. That's why this library includes many functions to build more\ncomplicated generators, allowing you to call `generate` only a small number of\ntimes.\n", "type": "Generator a -> Seed -> ( a, Seed )" }, { "name": "initialSeed", "comment": " Like `initialSeed2`, but takes only one integer. Mostly for compatibility\nwith core.\n", "type": "Int -> Seed" }, { "name": "initialSeed2", "comment": " Take two integers to fully initialize the 64-bit state of the random\nnumber generator. Only the least significant 32 bits of each integer matter, and\nthose bits should be as random as possible.\n\nYou can generate and copy random integers to create a reproducible psuedo-random\ngenerator.\n\n $ node\n > Math.floor(Math.random()*0xFFFFFFFF)\n 227852860\n > Math.floor(Math.random()*0xFFFFFFFF)\n 1498709020\n\n -- Elm\n seed0 : Seed\n seed0 = initialSeed2 227852860 1498709020\n\nAlternatively, you can generate the random integers on page load and pass them\nthrough a port. The program will be different every time.\n\n -- Elm\n port randomSeed : (Int, Int)\n\n seed0 : Seed\n seed0 = (uncurry initialSeed2) randomSeed\n\n -- JS\n Elm.fullscreen(Elm.ModuleName,\n {randomSeed: [Math.floor(Math.random()*0xFFFFFFFF),\n Math.floor(Math.random()*0xFFFFFFFF)] })\n\nEither way, you should initialize a random seed only once. After that, whenever\nyou use a seed, you'll get another one back.\n", "type": "Int -> Int -> Seed" }, { "name": "int", "comment": " Generate 32-bit integers in a given range.\n\n int 0 10 -- an integer between zero and ten\n int -5 5 -- an integer between -5 and 5\n\n int minInt maxInt -- an integer in the widest range feasible\n\nThis function *can* produce values outside of the range [[`minInt`](#minInt),\n[`maxInt`](#maxInt)] but sufficient randomness is not guaranteed.\n", "type": "Int -> Int -> Generator Int" }, { "name": "list", "comment": " Create a list of random values of a given length.\n\n floatList : Generator (List Float)\n floatList =\n list 10 (float 0 1)\n\n intList : Generator (List Int)\n intList =\n list 5 (int 0 100)\n\n intPairs : Generator (List (Int, Int))\n intPairs =\n list 10 <| pair (int 0 100) (int 0 100)\n", "type": "Int -> Generator a -> Generator (List a)" }, { "name": "map", "comment": " Transform the values produced by a generator. The following examples show\nhow to generate booleans and letters based on a basic integer generator.\n\n bool : Generator Bool\n bool =\n map ((==) 1) (int 0 1)\n\n lowercaseLetter : Generator Char\n lowercaseLetter =\n map (\\n -> Char.fromCode (n + 97)) (int 0 25)\n\n uppercaseLetter : Generator Char\n uppercaseLetter =\n map (\\n -> Char.fromCode (n + 65)) (int 0 25)\n\n", "type": "(a -> b) -> Generator a -> Generator b" }, { "name": "map2", "comment": " Combine two generators.\n\nThis function is used to define things like [`pair`](#pair) where you want to\nput two generators together.\n\n pair : Generator a -> Generator b -> Generator (a,b)\n pair genA genB =\n map2 (,) genA genB\n\n", "type": "(a -> b -> c) -> Generator a -> Generator b -> Generator c" }, { "name": "map3", "comment": " Combine three generators. This could be used to produce random colors.\n\n import Color\n\n rgb : Generator Color.Color\n rgb =\n map3 Color.rgb (int 0 255) (int 0 255) (int 0 255)\n\n hsl : Generator Color.Color\n hsl =\n map3 Color.hsl (map degrees (float 0 359.9999)) (float 0 1) (float 0 1)\n", "type": "(a -> b -> c -> d) -> Generator a -> Generator b -> Generator c -> Generator d" }, { "name": "map4", "comment": " Combine four generators.\n\n import Color\n\n rgba : Generator Color.Color\n rgba =\n map4 Color.rgba (int 0 255) (int 0 255) (int 0 255) (float 0 1)\n", "type": "(a -> b -> c -> d -> e) -> Generator a -> Generator b -> Generator c -> Generator d -> Generator e" }, { "name": "map5", "comment": " Combine five generators.\n", "type": "(a -> b -> c -> d -> e -> f) -> Generator a -> Generator b -> Generator c -> Generator d -> Generator e -> Generator f" }, { "name": "maxInt", "comment": " The maximum value for randomly generated 32-bit ints. ", "type": "Int" }, { "name": "minInt", "comment": " The minimum value for randomly generated 32-bit ints. ", "type": "Int" }, { "name": "pair", "comment": " Create a pair of random values. A common use of this might be to generate\na point in a certain 2D space. Imagine we have a collage that is 400 pixels\nwide and 200 pixels tall.\n\n randomPoint : Generator (Int,Int)\n randomPoint =\n pair (int -200 200) (int -100 100)\n\n", "type": "Generator a -> Generator b -> Generator ( a, b )" }, { "name": "split", "comment": " Split a seed into two new seeds. Each seed will generate different random\nnumbers. This is useful when you have you need an unknown amount of randomness\n*later* but have to pass back a seed *now*.\n\nLet's say you have have many independent components which will each want to\ngenerate many random numbers. After splitting a seed, you can pass one of the\nnew seeds to a component, and keep the other to repeat the process.\n\n makeComponents : Seed -> List (Seed -> Component) -> (List Component, Seed)\n makeComponents seed constructors =\n case constructors of\n [] ->\n ([], seed)\n\n c::cs ->\n let\n (seed1, seed2) = split seed\n (tail, seed3) = makeComponents seed2 cs\n in\n (c seed1 :: tail, seed3)\n\nIf you need a known number of seeds, you can obtain them like so:\n\n generateNSeeds : Int -> Seed -> List Seed\n generateNSeeds n seed =\n let\n helper seeds =\n if List.length seeds >= n then\n List.take n seeds\n else\n List.concatMap\n (\\seed -> let (a,b) = split seed in [a,b])\n seeds\n |> helper\n in\n helper [seed]\n\nSplitting is a reproducible operation; just like generating numbers, it\nwill be the same every time. Similarly, once you split a seed, you must not\nreuse it.\n\nSplit seeds are extremely likely to be distinct for all practical purposes.\nHowever, it is not proven that there are no pathological cases.\n", "type": "Seed -> ( Seed, Seed )" } ], "binops": [] } ]