CoCoA » CoCoALib

At the moment the names all have the prefix Random; this could be abbreviated into Rnd or Rand -- Anna thinks Rand is a better choice. It is to be understood that all generators are pseudorandom (but that is far too long to be a prefix!).

The suffix is Stream. This may be a poor choice because in a C++ context "stream" is customarily associated with I/O (and the related syntax using << and >>). It is certainly possible to regard random number generation as reading from a random stream, but the current syntax is not compatible with the standard C++ streams.

CoCoALib's random streams have been designed to have C++ input iterator syntax. Can we find a name which suggests this?

The fully generic random generator uses the suffix Source; this is the same length as Stream and would avoid any possible confusion with C++'s notion of streams.

Here is another idea. At the moment the names of the three random generators include the name of the type of random value created: RandomBoolStream, RandomLongStream and RandomZZStream. It should be easy to use templates and template specialization to allow names like these: RandomStream<bool>, RandomStream<long> and RandomStream<BigInt>

Advantage: This might make it easier to write templated code which needs to use random streams.

Disadvantage: we must write an (uninstantiable?) master template RandomStream<...>, and then write specializations. Also a user might naively think that the master template can be instantiated with any type.

Added 2012-12-04 JAA now thinks the template idea is not such a good one.

We need to improve documentation to make the differences between RandomSource and the Random*Stream functions clearer.

Here is another proposal for the new names:
RandGen
RandGenBool
RandGenLong
RandGenBigInt

Here my aim was to keep the names as short as possible.

Added 2012-12-05
Another proposal for names: (Seq is short for sequence)

RandomSeqLong
RandomSeqBool
RandomSeqBigInt

these might be sources of inspiration
http://www.gnu.org/software/gsl/manual/html_node/Random-Number-Generation.html
http://docs.scipy.org/doc/numpy/reference/routines.random.html
http://caml.inria.fr/pub/docs/manual-ocaml/libref/Random.html

A few ideas (brainstorming)

RandomBool(RndSrc)
RandomBool()  // calling GlobalRandomSource()

RandomLong(RndSrc) // remove??
RandomLong(RndSrc, lwb, upb)
RandomLong(lwb, upb)  // calling GlobalRandomSource()

Anna: I have implemented RandomLong(lwb, upb) and it works fine. I think it is the nicest interface.

Good idea!!

Anna: remove RandomLong(RndSrc)

OK, at least until someone says they really need it.

Added 2012-12-04: JAA confirms that the fn has been removed.

Following Alessandra Caleo's criticisms (see issue #75), we have modified the documentation and examples to make them clearer.

JAA has undone Anna's wording in the doc which discouraged used of RandomLongStream (and also for bools and BigInts).

We held a further verbal discussion about names. Anna pointed out that it is less important to make class names short than function names. JAA accepts this.

The remaining issue is whether to keep the names RandomXXXStream or switch to RandomSourceXXX as Anna suggested in point 4 above.

Note: I have not yet effected the renaming of files as this depends on our final choice for the class names.

Note 2: since the header files are all quite short, we could put all the random functions into a single header file -- is this a good idea? This would fit nicely if their names all begin with the same prefix, e.g. RandomSource

Discussion via Skype:
instead of sample use NextValue to access a new element from a RandomStream..