mcs/class/corlib/Documentation/en/System/Random.xml

   1 <Type Name="Random" FullName="System.Random" FullNameSP="System_Random" Maintainer="ecma">
   2   <TypeSignature Language="ILASM" Value=".class public serializable Random extends System.Object" />
   3   <TypeSignature Language="C#" Value="public class Random" />
   4   <MemberOfLibrary>BCL</MemberOfLibrary>
   5   <AssemblyInfo>
   6     <AssemblyName>mscorlib</AssemblyName>
   7     <AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ]</AssemblyPublicKey>
   8     <AssemblyVersion>1.0.5000.0</AssemblyVersion>
   9     <AssemblyVersion>2.0.0.0</AssemblyVersion>
  10   </AssemblyInfo>
  11   <ThreadingSafetyStatement>All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.</ThreadingSafetyStatement>
  12   <Base>
  13     <BaseTypeName>System.Object</BaseTypeName>
  14   </Base>
  15   <Interfaces />
  16   <Docs>
  17     <summary>
  18       <para> Generates
  19       psuedo-random numbers.</para>
  20     </summary>
  21     <remarks>
  22       <para> Instances of this class are initialized using a "seed",
  23       or starting value. The series of numbers
  24       generated by instances of the class are repeatable: given the
  25       same seed value,
  26       all instances of this class generate the same series of numbers.</para>
  27       <para>
  28         <block subset="none" type="note"> The numbers generated by this class are chosen with equal
  29       probability from a finite set of numbers. The numbers are generated by a
  30       definite mathematical algorithm and are therefore not truly random, but are
  31       sufficiently random for practical purposes. For this reason, the numbers are
  32       considered to be psuedo-random.
  33       </block>
  34       </para>
  35     </remarks>
  36   </Docs>
  37   <Members>
  38     <Member MemberName=".ctor">
  39       <MemberSignature Language="ILASM" Value="public rtspecialname specialname instance void .ctor()" />
  40       <MemberSignature Language="C#" Value="public Random ();" />
  41       <MemberType>Constructor</MemberType>
  42       <ReturnValue />
  43       <Parameters />
  44       <Docs>
  45         <summary>
  46           <para>Constructs a new instance of the
  47  <see langword="Random" /> class using <see cref="P:System.Environment.TickCount" qualify="true" />
  48  as the seed
  49  value.</para>
  50         </summary>
  51         <remarks>
  52           <para>This constructor is equivalent to <see cref="T:System.Random" />(<see cref="P:System.Environment.TickCount" /> ).</para>
  53           <para>
  54             <block subset="none" type="note">When generating
  55  random numbers on high performance systems, the system clock value might not
  56  produce the desired behavior. For details, see the <see cref="T:System.Random" />(<see cref="T:System.Int32" />
  57  )
  58  constructor.</block>
  59           </para>
  60         </remarks>
  61       </Docs>
  62       <Excluded>0</Excluded>
  63       <AssemblyInfo>
  64         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  65         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  66       </AssemblyInfo>
  67     </Member>
  68     <Member MemberName=".ctor">
  69       <MemberSignature Language="ILASM" Value="public rtspecialname specialname instance void .ctor(int32 Seed)" />
  70       <MemberSignature Language="C#" Value="public Random (int Seed);" />
  71       <MemberType>Constructor</MemberType>
  72       <ReturnValue />
  73       <Parameters>
  74         <Parameter Name="Seed" Type="System.Int32" />
  75       </Parameters>
  76       <Docs>
  77         <param name="Seed">A <see cref="T:System.Int32" /> used as the starting value for the pseudo-random number sequence.</param>
  78         <summary>
  79           <para>Constructs a new instance of the <see langword="Random" /> class using the specified
  80    seed value.</para>
  81         </summary>
  82         <remarks>
  83           <para>
  84             <block subset="none" type="note">To construct instances that produce different random number sequences, invoke
  85       this constructor using different seed values such as might be
  86       produced by the system clock. Note, however that on high performance systems, the system clock
  87       might not change between invocations of the constructor, in which case the seed value
  88       will be the same for different instances of <see langword="Random" /> . When this is the case, additional operations are required to have the seed values differ in each invocation.
  89    </block>
  90           </para>
  91         </remarks>
  92         <example>
  93           <para> The following example demonstrates using a
  94       bitwise complement operation to obtain different random numbers using a time-dependent
  95       seed value on high performance systems.</para>
  96           <code lang="C#">using System;
  97 class RandomTest {
  98     public static void Main() {
  99         Random rand1 = new Random();
 100         Random rand2 = new Random(Environment.TickCount);
 101         Console.WriteLine("The random number is {0}",rand1.Next());
 102         Console.WriteLine("The random number is {0}",rand2.Next());
 103
 104         Random rdm1 = new Random(unchecked(Environment.TickCount));
 105         Random rdm2 = new Random(~unchecked(Environment.TickCount));
 106         Console.WriteLine("The random number is {0}",rdm1.Next());
 107         Console.WriteLine("The random number is {0}",rdm2.Next());
 108     }
 109 }
 110    </code>
 111           <c>
 112             <para>The output is </para>
 113             <para>The random number is 1990211954</para>
 114             <para>The random number is 1990211954</para>
 115             <para>The random number is 1990211954</para>
 116             <para>The random number is 964628126</para>
 117           </c>
 118         </example>
 119       </Docs>
 120       <Excluded>0</Excluded>
 121       <AssemblyInfo>
 122         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 123         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 124       </AssemblyInfo>
 125     </Member>
 126     <Member MemberName="Next">
 127       <MemberSignature Language="ILASM" Value=".method public hidebysig virtual int32 Next()" />
 128       <MemberSignature Language="C#" Value="public virtual int Next ();" />
 129       <MemberType>Method</MemberType>
 130       <ReturnValue>
 131         <ReturnType>System.Int32</ReturnType>
 132       </ReturnValue>
 133       <Parameters />
 134       <Docs>
 135         <summary>
 136           <para>Returns a psuedo-random number between 0 and <see cref="F:System.Int32.MaxValue" />.</para>
 137         </summary>
 138         <returns>
 139           <para>A <see cref="T:System.Int32" /> greater than or equal to zero and less than
 140 <see cref="F:System.Int32.MaxValue" />.</para>
 141         </returns>
 142         <remarks>
 143           <para>
 144             <block subset="none" type="behaviors">As described above.</block>
 145           </para>
 146           <para>
 147             <block subset="none" type="overrides">Override this method to customize the algorithm used to generate the return value.</block>
 148           </para>
 149         </remarks>
 150         <example>
 151           <para>The following example demonstrates using the
 152    <see langword="Next" /> method. The output generated by this example
 153       will
 154       vary.</para>
 155           <code lang="C#">using System;
 156 class RandomTest {
 157     public static void Main() {
 158         Random rand1 = new Random();
 159         for (int i = 0; i&lt;10;i++)
 160         Console.WriteLine("The random number is {0}",rand1.Next());
 161
 162     }
 163 }
 164    </code>
 165           <para>The output is</para>
 166           <c>
 167             <para> The random number is
 168          1544196111</para>
 169             <para> The random number is
 170          181749919</para>
 171             <para> The random number is
 172          1045210087</para>
 173             <para> The random number is
 174          1073826097</para>
 175             <para> The random number is
 176          1533078806</para>
 177             <para> The random number is
 178          1083151645</para>
 179             <para> The random number is
 180          569083504</para>
 181             <para> The random number is
 182          1711370568</para>
 183             <para> The random number is
 184          578178313</para>
 185             <para> The random number is
 186          409444742</para>
 187           </c>
 188         </example>
 189       </Docs>
 190       <Excluded>0</Excluded>
 191       <AssemblyInfo>
 192         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 193         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 194       </AssemblyInfo>
 195     </Member>
 196     <Member MemberName="Next">
 197       <MemberSignature Language="ILASM" Value=".method public hidebysig virtual int32 Next(int32 maxValue)" />
 198       <MemberSignature Language="C#" Value="public virtual int Next (int maxValue);" />
 199       <MemberType>Method</MemberType>
 200       <ReturnValue>
 201         <ReturnType>System.Int32</ReturnType>
 202       </ReturnValue>
 203       <Parameters>
 204         <Parameter Name="maxValue" Type="System.Int32" />
 205       </Parameters>
 206       <Docs>
 207         <param name="maxValue">The upper bound of the random number to be generated. <paramref name="maxValue" /> is required to be greater than or equal to zero.</param>
 208         <summary>
 209           <para>Returns a psuedo-random positive number less than the specified
 210       maximum.</para>
 211         </summary>
 212         <returns>
 213           <para>A <see cref="T:System.Int32" /> set to a psuedo-random value greater than or equal to zero
 214    and less than <paramref name="maxValue" />. If <paramref name="maxValue" /> is zero, returns zero.</para>
 215         </returns>
 216         <remarks>
 217           <para>
 218             <block subset="none" type="behaviors">As described
 219       above.</block>
 220           </para>
 221           <para>
 222             <block subset="none" type="overrides">Override this method to customize
 223       the algorithm used to generate the return value.</block>
 224           </para>
 225           <para>
 226             <block subset="none" type="usage">Use this method to generate a psuedo-random number
 227       less than the specified maximum value.</block>
 228           </para>
 229         </remarks>
 230         <exception cref="T:System.ArgumentOutOfRangeException">
 231           <paramref name="maxValue" /> is less than zero.</exception>
 232       </Docs>
 233       <Excluded>0</Excluded>
 234       <AssemblyInfo>
 235         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 236         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 237       </AssemblyInfo>
 238     </Member>
 239     <Member MemberName="Next">
 240       <MemberSignature Language="ILASM" Value=".method public hidebysig virtual int32 Next(int32 minValue, int32 maxValue)" />
 241       <MemberSignature Language="C#" Value="public virtual int Next (int minValue, int maxValue);" />
 242       <MemberType>Method</MemberType>
 243       <ReturnValue>
 244         <ReturnType>System.Int32</ReturnType>
 245       </ReturnValue>
 246       <Parameters>
 247         <Parameter Name="minValue" Type="System.Int32" />
 248         <Parameter Name="maxValue" Type="System.Int32" />
 249       </Parameters>
 250       <Docs>
 251         <param name="minValue">The lower bound of the random number returned.</param>
 252         <param name="maxValue">The upper bound of the random number returned.</param>
 253         <summary>
 254           <para>Returns a psuedo-random number within a specified range.</para>
 255         </summary>
 256         <returns>
 257           <para>A psuedo-random number greater than or equal to <paramref name="minValue" /> and
 258    less than <paramref name="maxValue" />. If <paramref name="minValue" /> and
 259 <paramref name="maxValue " />are equal, this value
 260    is returned.</para>
 261         </returns>
 262         <remarks>
 263           <para>
 264             <block subset="none" type="behaviors">As described above.</block>
 265           </para>
 266           <para>
 267             <block subset="none" type="overrides">Override this
 268       method to customize the algorithm used to generate the return
 269       value.</block>
 270           </para>
 271           <para>
 272             <block subset="none" type="usage">Use this method to generate
 273       psuedo-random numbers in a specified range.</block>
 274           </para>
 275         </remarks>
 276         <exception cref="T:System.ArgumentOutOfRangeException">
 277           <paramref name="minValue" /> is greater than <paramref name="maxValue" />.</exception>
 278       </Docs>
 279       <Excluded>0</Excluded>
 280       <AssemblyInfo>
 281         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 282         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 283       </AssemblyInfo>
 284     </Member>
 285     <Member MemberName="NextBytes">
 286       <MemberSignature Language="ILASM" Value=".method public hidebysig virtual void NextBytes(class System.Byte[] buffer)" />
 287       <MemberSignature Language="C#" Value="public virtual void NextBytes (byte[] buffer);" />
 288       <MemberType>Method</MemberType>
 289       <ReturnValue>
 290         <ReturnType>System.Void</ReturnType>
 291       </ReturnValue>
 292       <Parameters>
 293         <Parameter Name="buffer" Type="System.Byte[]" />
 294       </Parameters>
 295       <Docs>
 296         <param name="buffer">An array of bytes to be populated with random numbers.</param>
 297         <summary>
 298           <para>Populates the elements of a specified array of bytes with random numbers.</para>
 299         </summary>
 300         <remarks>
 301           <para>
 302             <block subset="none" type="behaviors">Each element of the array of bytes is set to a random number greater than or
 303  equal to zero, and less than or equal to <see cref="F:System.Byte.MaxValue" />.</block>
 304           </para>
 305           <para>
 306             <block subset="none" type="overrides">Override this method to customize
 307  the algorithm used to generate the return value.</block>
 308           </para>
 309           <para>
 310             <block subset="none" type="usage">Use the
 311  <see langword=" NextByte" /> method to populate a <see cref="T:System.Byte" />
 312  array with random numbers.</block>
 313           </para>
 314         </remarks>
 315         <exception cref="T:System.ArgumentNullException">
 316           <paramref name="buffer" /> is a <see langword="null" /> reference.</exception>
 317       </Docs>
 318       <Excluded>0</Excluded>
 319       <AssemblyInfo>
 320         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 321         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 322       </AssemblyInfo>
 323     </Member>
 324     <Member MemberName="NextDouble">
 325       <MemberSignature Language="ILASM" Value=".method public hidebysig virtual float64 NextDouble()" />
 326       <MemberSignature Language="C#" Value="public virtual double NextDouble ();" />
 327       <MemberType>Method</MemberType>
 328       <ReturnValue>
 329         <ReturnType>System.Double</ReturnType>
 330       </ReturnValue>
 331       <Parameters />
 332       <Docs>
 333         <summary>
 334           <para>Returns a random number between 0.0 and 1.0.</para>
 335         </summary>
 336         <returns>
 337           <para>A <see cref="T:System.Double" /> greater than or equal to 0.0, and less than 1.0.</para>
 338         </returns>
 339         <remarks>
 340           <para>
 341             <block subset="none" type="behaviors">As described
 342       above.</block>
 343           </para>
 344           <para>
 345             <block subset="none" type="usage">Use this method to generate a
 346       psuedo-random number greater than or equal to zero, and less than
 347       one.</block>
 348           </para>
 349         </remarks>
 350       </Docs>
 351       <Excluded>1</Excluded>
 352       <ExcludedLibrary>ExtendedNumerics</ExcludedLibrary>
 353       <AssemblyInfo>
 354         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 355         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 356       </AssemblyInfo>
 357     </Member>
 358     <Member MemberName="Sample">
 359       <MemberSignature Language="C#" Value="protected virtual double Sample ();" />
 360       <MemberType>Method</MemberType>
 361       <ReturnValue>
 362         <ReturnType>System.Double</ReturnType>
 363       </ReturnValue>
 364       <Parameters />
 365       <Docs>
 366         <summary>To be added.</summary>
 367         <returns>To be added.</returns>
 368         <remarks>To be added.</remarks>
 369       </Docs>
 370       <AssemblyInfo>
 371         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 372         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 373       </AssemblyInfo>
 374     </Member>
 375   </Members>
 376   <TypeExcluded>0</TypeExcluded>
 377   <Attributes>
 378     <Attribute>
 379       <AttributeName>System.Runtime.InteropServices.ComVisible(true)</AttributeName>
 380     </Attribute>
 381   </Attributes>
 382 </Type>