FS-1135 implementation - random functions for collections (#17277)

* Random functions: old version rebased

* Random functions: Rename functions according to the RFC

* Random functions: More naming refactoring and documentation

* Random functions: More documentation coments

* Random functions: Added randomShuffleInPlace functions and docs

* Random functions: refactoring

* Added null checks

* Added *by functions

* Random functions: Array random functions tests

* Added tests for lists and seqs

* Random functions: addded *By tests to arrays and sequences

* Random functions: addded *By tests to lists

* Random functions: try fix CI

* Random functions: review fixes

* Try fix CI

* Changed thread local implementation to thread static for performance per review

* PR review fix

* PR fix

* PR review fix

* Reverted HashSet constructor improvement since not netstandard2.0 compatible

* Fix formatting

* Fixed nan case for randomizer function

* PR review fixes

* PR review changes

* Fixed input length check logic for sample

---------

Co-authored-by: Petr <psfinaki@users.noreply.github.com>

docs/release-notes/.FSharp.Core/8.0.400.md

@@ -2,6 +2,8 @@
 
 ### Added
 
+* `Random functions for collections` ([RFC #1135](https://github.com/fsharp/fslang-design/blob/main/RFCs/FS-1135-random-functions-for-collections.md), [PR #17277](https://github.com/dotnet/fsharp/pull/17277))
+
 ### Changed
 
 * Cache delegate in query extensions. ([PR #17130](https://github.com/dotnet/fsharp/pull/17130))

src/FSharp.Core/FSharp.Core.fsproj

@@ -91,6 +91,12 @@
  <Compile Include="prim-types.fs">
  <Link>Primitives/prim-types.fs</Link>
  </Compile>
+ <Compile Include="Random.fsi">
+ <Link>Random/Random.fsi</Link>
+ </Compile>
+ <Compile Include="Random.fs">
+ <Link>Random/Random.fs</Link>
+ </Compile>
  <Compile Include="local.fsi">
  <Link>Collections/local.fsi</Link>
  </Compile>

src/FSharp.Core/Random.fs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation. All Rights Reserved. See License.txt in the project root for license information.
+
+namespace Microsoft.FSharp.Core
+
+open System
+open System.Runtime.CompilerServices
+open System.Threading
+
+[<AbstractClass; Sealed>]
+type internal ThreadSafeRandom() =
+
+ [<DefaultValue>]
+ [<ThreadStatic>]
+ static val mutable private random: Random
+
+ [<MethodImpl(MethodImplOptions.NoInlining)>]
+ static member private Create() =
+ ThreadSafeRandom.random <- Random()
+ ThreadSafeRandom.random
+
+ // Don't pass the returned Random object between threads
+ static member Shared =
+ match ThreadSafeRandom.random with
+ | null -> ThreadSafeRandom.Create()
+ | random -> random

src/FSharp.Core/Random.fsi

@@ -0,0 +1,7 @@
+namespace Microsoft.FSharp.Core
+
+open System
+
+[<AbstractClass; Sealed>]
+type internal ThreadSafeRandom =
+ static member Shared: Random

src/FSharp.Core/array.fs

@@ -1936,6 +1936,211 @@ module Array =
 
  result
 
+ [<CompiledName("RandomShuffleWith")>]
+ let randomShuffleWith (random: Random) (source: 'T array) : 'T array =
+ checkNonNull "random" random
+ checkNonNull "source" source
+
+ let result = copy source
+
+ Microsoft.FSharp.Primitives.Basics.Random.shuffleArrayInPlaceWith random result
+
+ result
+
+ [<CompiledName("RandomShuffleBy")>]
+ let randomShuffleBy (randomizer: unit -> float) (source: 'T array) : 'T array =
+ checkNonNull "source" source
+
+ let result = copy source
+
+ Microsoft.FSharp.Primitives.Basics.Random.shuffleArrayInPlaceBy randomizer result
+
+ result
+
+ [<CompiledName("RandomShuffle")>]
+ let randomShuffle (source: 'T array) : 'T array =
+ randomShuffleWith ThreadSafeRandom.Shared source
+
+ [<CompiledName("RandomShuffleInPlaceWith")>]
+ let randomShuffleInPlaceWith (random: Random) (source: 'T array) =
+ checkNonNull "random" random
+ checkNonNull "source" source
+
+ Microsoft.FSharp.Primitives.Basics.Random.shuffleArrayInPlaceWith random source
+
+ [<CompiledName("RandomShuffleInPlaceBy")>]
+ let randomShuffleInPlaceBy (randomizer: unit -> float) (source: 'T array) =
+ checkNonNull "source" source
+
+ Microsoft.FSharp.Primitives.Basics.Random.shuffleArrayInPlaceBy randomizer source
+
+ [<CompiledName("RandomShuffleInPlace")>]
+ let randomShuffleInPlace (source: 'T array) =
+ randomShuffleInPlaceWith ThreadSafeRandom.Shared source
+
+ [<CompiledName("RandomChoiceWith")>]
+ let randomChoiceWith (random: Random) (source: 'T array) : 'T =
+ checkNonNull "random" random
+ checkNonNull "source" source
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ let i = random.Next(0, inputLength)
+ source[i]
+
+ [<CompiledName("RandomChoiceBy")>]
+ let randomChoiceBy (randomizer: unit -> float) (source: 'T array) : 'T =
+ checkNonNull "source" source
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ let i = Microsoft.FSharp.Primitives.Basics.Random.next randomizer 0 inputLength
+ source[i]
+
+ [<CompiledName("RandomChoice")>]
+ let randomChoice (source: 'T array) : 'T =
+ randomChoiceWith ThreadSafeRandom.Shared source
+
+ [<CompiledName("RandomChoicesWith")>]
+ let randomChoicesWith (random: Random) (count: int) (source: 'T array) : 'T array =
+ checkNonNull "random" random
+ checkNonNull "source" source
+
+ if count < 0 then
+ invalidArgInputMustBeNonNegative "count" count
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ let result = Microsoft.FSharp.Primitives.Basics.Array.zeroCreateUnchecked count
+
+ for i = 0 to count - 1 do
+ let j = random.Next(0, inputLength)
+ result[i] <- source[j]
+
+ result
+
+ [<CompiledName("RandomChoicesBy")>]
+ let randomChoicesBy (randomizer: unit -> float) (count: int) (source: 'T array) : 'T array =
+ checkNonNull "source" source
+
+ if count < 0 then
+ invalidArgInputMustBeNonNegative "count" count
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ let result = Microsoft.FSharp.Primitives.Basics.Array.zeroCreateUnchecked count
+
+ for i = 0 to count - 1 do
+ let j = Microsoft.FSharp.Primitives.Basics.Random.next randomizer 0 inputLength
+ result[i] <- source[j]
+
+ result
+
+ [<CompiledName("RandomChoices")>]
+ let randomChoices (count: int) (source: 'T array) : 'T array =
+ randomChoicesWith ThreadSafeRandom.Shared count source
+
+ [<CompiledName("RandomSampleWith")>]
+ let randomSampleWith (random: Random) (count: int) (source: 'T array) : 'T array =
+ checkNonNull "random" random
+ checkNonNull "source" source
+
+ if count < 0 then
+ invalidArgInputMustBeNonNegative "count" count
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ if count > inputLength then
+ invalidArg "count" (SR.GetString(SR.notEnoughElements))
+
+ let result = Microsoft.FSharp.Primitives.Basics.Array.zeroCreateUnchecked count
+
+ let setSize =
+ Microsoft.FSharp.Primitives.Basics.Random.getMaxSetSizeForSampling count
+
+ if inputLength <= setSize then
+ let pool = copy source
+
+ for i = 0 to count - 1 do
+ let j = random.Next(0, inputLength - i)
+ result[i] <- pool[j]
+ pool[j] <- pool[inputLength - i - 1]
+ else
+ let selected = HashSet()
+
+ for i = 0 to count - 1 do
+ let mutable j = random.Next(0, inputLength)
+
+ while not (selected.Add j) do
+ j <- random.Next(0, inputLength)
+
+ result[i] <- source[j]
+
+ result
+
+ [<CompiledName("RandomSampleBy")>]
+ let randomSampleBy (randomizer: unit -> float) (count: int) (source: 'T array) : 'T array =
+ checkNonNull "source" source
+
+ if count < 0 then
+ invalidArgInputMustBeNonNegative "count" count
+
+ let inputLength = source.Length
+
+ if inputLength = 0 then
+ invalidArg "source" LanguagePrimitives.ErrorStrings.InputArrayEmptyString
+
+ if count > inputLength then
+ invalidArg "count" (SR.GetString(SR.notEnoughElements))
+
+ let result = Microsoft.FSharp.Primitives.Basics.Array.zeroCreateUnchecked count
+
+ // algorithm taken from https://github.com/python/cpython/blob/69b3e8ea569faabccd74036e3d0e5ec7c0c62a20/Lib/random.py#L363-L456
+ let setSize =
+ Microsoft.FSharp.Primitives.Basics.Random.getMaxSetSizeForSampling count
+
+ if inputLength <= setSize then
+ let pool = copy source
+
+ for i = 0 to count - 1 do
+ let j =
+ Microsoft.FSharp.Primitives.Basics.Random.next randomizer 0 (inputLength - i)
+
+ result[i] <- pool[j]
+ pool[j] <- pool[inputLength - i - 1]
+ else
+ let selected = HashSet()
+
+ for i = 0 to count - 1 do
+ let mutable j =
+ Microsoft.FSharp.Primitives.Basics.Random.next randomizer 0 inputLength
+
+ while not (selected.Add j) do
+ j <- Microsoft.FSharp.Primitives.Basics.Random.next randomizer 0 inputLength
+
+ result[i] <- source[j]
+
+ result
+
+ [<CompiledName("RandomSample")>]
+ let randomSample (count: int) (source: 'T array) : 'T array =
+ randomSampleWith ThreadSafeRandom.Shared count source
+
  module Parallel =
  open System.Threading
  open System.Threading.Tasks