{
  "category": "Math and trigonometry functions",
  "display_name": "RANDBETWEEN",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.RANDBETWEEN",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 2 workbook cells. A volatile function: the recorded formulas hold it fixed, for example RAND()*0, so these cells show that the call works and not a clock or random value.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 2 recorded answers",
    "workbook_corpus": {
      "cells": 2,
      "matched": 2
    }
  },
  "implementations": [
    {
      "commit": "9e1884369a678158dd82d3d74188daf986995e87",
      "flavour": "excel-compatibility-candidate",
      "language": "Rust",
      "name": "CalcFunc",
      "own_code": [
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/random.rs#L36-L46"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/random::draw"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/random.rs#L36-L46",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 2 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.RANDBETWEEN.json",
  "name": "RANDBETWEEN",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n### Relationships\n\n- **[RAND](FUNC.RAND.md)** — the continuous source. `RANDBETWEEN` is built from it, and inverts\n  its endpoint convention.\n- **`INDEX(range, RANDBETWEEN(1, ROWS(range)))`** — sampling with replacement, the idiom this\n  function mostly exists to serve.\n- **`CRITBINOM`/`BINOM.INV`** — the other route to a discrete draw, via an inverse CDF. Different\n  distribution, same dependence on the quality of the underlying uniform.\n\n\n",
    "how-to-implement": "\n### Numerical notes\n\n\n**Uniformity is approximate, and the error is exactly `N/2⁵³`.** The construction\n`lo + ⌊u·N⌋`, with `u` uniform on a lattice of `2⁵³` values and `N = hi − lo + 1`, distributes\n`2⁵³` lattice points among `N` buckets. If `N` is not a power of two the buckets cannot receive\nequal counts, and the largest and smallest bucket probabilities differ by a relative amount of\nabout `N/2⁵³`. For `RANDBETWEEN(1,6)` that is around `10⁻¹⁵` — undetectable in any experiment that\nwill ever be run. For `N` above `2⁴⁰` it becomes measurable, and for `N` near `2⁵³` the\ndistribution is visibly lumpy.\n\nThe unbiased alternatives are well known: rejection sampling (redraw when `u` falls in the\nincomplete final block) and Lemire's multiply-shift method, which achieves the same at the cost of\none multiplication and a rarely taken branch. Both are strictly better mathematics. Neither may be\nsubstituted into an implementation that is targeting compatibility, because each changes which\ndraw a given stream position produces — so this is a case where `natural-best` and\n`excel-bitexact` must genuinely differ; see\n[About implementation options](../model/07-implementation-options.md).\n\n**A wide range does not give a wide sample.** Because the source lattice has `2⁵³` points, a\n`RANDBETWEEN` over a range wider than the generator's resolution cannot reach every integer in the\nrange — it reaches at most as many distinct values as the generator has. If the underlying stream\nis 32-bit, that ceiling is around four billion regardless of the bounds requested. Anyone using\n`RANDBETWEEN(1, 10^15)` as an identifier generator should know this.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, always integral.\n\n- **`bottom = top`** returns that value with probability 1 — a degenerate but legal draw.\n- **Non-integral bounds** narrow inward, as above; if `⌈bottom⌉ > ⌊top⌋` — for example\n  `RANDBETWEEN(1.2, 1.8)`, where no integer lies in the interval — the same refusal applies. This\n  is a case a reader is unlikely to anticipate: an interval that plainly contains numbers contains\n  no *integers*, and the function errors.\n- **Volatility.** `VolatileFull`, `PseudoRandom`, `HostSerialized`, `RandomProvider` — the whole\n  discussion on [RAND](FUNC.RAND.md) applies unchanged. The value is not stable; a\n  `RANDBETWEEN` cell cannot be used as a key.\n- **Very wide ranges.** When `top − bottom + 1` approaches or exceeds 2⁵³, the arithmetic that\n  produces the draw stops being exact; see the numerical notes.\n\n\n",
    "sources": "- Microsoft, \"WorksheetFunction.RandBetween method (Excel)\" —\n  <https://learn.microsoft.com/en-us/office/vba/api/excel.worksheetfunction.randbetween> (the\n  smallest/largest-integer wording and the recalculation statement; the page states no error\n  conditions and nothing about non-integral bounds).\n- Lemire, \"Fast random integer generation in an interval\", ACM TOMACS 4(1), 2019; L'Ecuyer &\n  Simard, \"TestU01\", ACM TOMS 33(4), 2007.\n- Handbook, [RAND](FUNC.RAND.md), [RANDARRAY](FUNC.RANDARRAY.md),\n  [Coercion and lifting](../model/02-coercion-and-lifting.md),\n  [About implementation options](../model/07-implementation-options.md).\n- Handbook projections `data/functions/FUNC.RANDBETWEEN.json` (`PseudoRandom`, `VolatileFull`,\n  `HostSerialized`, `RandomProvider`, `Custom` coercion) and\n  `data/presence/FUNC.RANDBETWEEN.json` (own module, no shared surfaces, no defect streams).\n\n",
    "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.",
    "what-it-does": "\n`RANDBETWEEN(bottom, top)` returns a pseudo-random **integer** between `bottom` and `top`,\n**inclusive at both ends**, redrawn on every recalculation.\n\n    P(X = k) = 1 / (top − bottom + 1)    for each integer k with bottom ≤ k ≤ top\n\nMicrosoft's VBA reference states the endpoints as inclusive without using the word: `bottom` is\n\"the smallest integer **RandBetween** will return\" and `top` is \"the largest integer\n**RandBetween** will return\". The same page states that \"a new random integer number is returned\nevery time the worksheet is calculated\".\n\n**The inclusive upper bound is the fact to carry away.** [RAND](FUNC.RAND.md) returns a value in\n`[0, 1)` — upper bound excluded. `RANDBETWEEN` includes both bounds. So `RANDBETWEEN(1, N)` picks\none of `N` items, while `INT(RAND()*N)+1` picks one of `N` items by a different route with a\ndifferent failure mode, and `RANDBETWEEN(0, N)` has `N+1` outcomes, not `N`. Off-by-one errors in\nspreadsheet sampling almost always trace back to mixing the two conventions.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `bottom` | The smallest integer that may be returned. Required. | — |\n| `top` | The largest integer that may be returned. Required. | — |\n\nBoth are numeric slots under ordinary to-number coercion — see\n[Coercion and lifting](../model/02-coercion-and-lifting.md). Microsoft's page types both as\n`Variant`, consistent with text and logicals converting.\n\n"
  },
  "signature": {
    "display": "RANDBETWEEN(bottom, top)",
    "parameters": [
      {
        "description": null,
        "name": "bottom",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "top",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 2,
        "min": 2
      },
      "category": "Math and trigonometry functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "Custom",
        "determinism_class": "PseudoRandom",
        "error_collapse_profile": "None",
        "fec_dependency_profile": "RandomProvider",
        "host_interaction_class": "ApplicationState",
        "kernel_signature_class": "Custom",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RandomProvider",
        "thread_safety_class": "HostSerialized",
        "volatility_class": "VolatileFull"
      },
      "descriptions": {
        "long": null,
        "short": "A random whole number between two limits, new at each recalculation",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns a random number between the numbers you specify",
        "microsoft_url": "https://support.microsoft.com/en-us/office/randbetween-function-4cc7f0d1-87dc-4eb7-987f-a469ab381685"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "bg-BG",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "cs-CZ",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "da-DK",
          "name": "SLUMPMELLEM"
        },
        {
          "locale": "de-DE",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "el-GR",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "en-AU",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "en-GB",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "en-US",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "es-ES",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "et-EE",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "fi-FI",
          "name": "SATUNNAISLUKU.VÄLILTÄ"
        },
        {
          "locale": "fr-FR",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "he-IL",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "hr-HR",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "hu-HU",
          "name": "VÉLETLEN.KÖZÖTT"
        },
        {
          "locale": "id-ID",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "it-IT",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "ja-JP",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "ko-KR",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "lt-LT",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "lv-LV",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "nb-NO",
          "name": "TILFELDIGMELLOM"
        },
        {
          "locale": "nl-NL",
          "name": "ASELECTTUSSEN"
        },
        {
          "locale": "pl-PL",
          "name": "LOS.ZAKR"
        },
        {
          "locale": "pt-BR",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "pt-PT",
          "name": "ALEATÓRIOENTRE"
        },
        {
          "locale": "ro-RO",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "ru-RU",
          "name": "СЛУЧМЕЖДУ"
        },
        {
          "locale": "sk-SK",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "sl-SI",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "sv-SE",
          "name": "SLUMP.MELLAN"
        },
        {
          "locale": "th-TH",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "tr-TR",
          "name": "RASTGELEARADA işlevi"
        },
        {
          "locale": "uk-UA",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "vi-VN",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "zh-CN",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "zh-HK",
          "name": "RANDBETWEEN"
        },
        {
          "locale": "zh-TW",
          "name": "RANDBETWEEN"
        }
      ],
      "signature": {
        "display": "RANDBETWEEN(bottom, top)",
        "parameters": [
          {
            "description": null,
            "name": "bottom",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "top",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "RANDBETWEEN",
      "version_marker": null,
      "xlcall": {
        "code": "464",
        "symbol": "xlfRandbetween"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/randbetween-function-4cc7f0d1-87dc-4eb7-987f-a469ab381685"
  },
  "try_it": {
    "formula": "=RANDBETWEEN(1,6)",
    "note": "OneCalc does not supply a random-number source in this preview.",
    "preview_status": "refused"
  },
  "url": "https://handbook.dnacalc.com/functions/RANDBETWEEN.html",
  "variants": [],
  "versions": []
}