add "random" tool introduced for EVS in 3GPP S4-121078.

doc/manual/unsup.tex

@@ -68,6 +68,11 @@ \section{Source code}
             scaling factors (linear or dB), and adding a DC
             level. For Unix/MSDOS.
 
+\item[random.c:]
+            randomization tool for selecting items from a list or
+            drawing numbers from a range. Reuses the EID linear
+            congruential generator from eid.c. For Unix/MSDOS.
+
 \item[sb.c:]
         swap bytes for word-oriented files. For
         VMS/Unix/MSDOS.
@@ -119,3 +124,178 @@ \section{Test files}
 
         \end{verbatim}}
 \end{Descr}
+
+
+%----------------------------------------------------------------------
+\section{The {\tt random} tool}
+\label{sec:random}
+%----------------------------------------------------------------------
+
+%----------------------------------------------------------------------
+\subsection{Introduction}
+%----------------------------------------------------------------------
+
+The {\tt random} tool provides deterministic pseudo-random selection
+capabilities for use in speech and audio codec evaluation scripts. It
+was originally developed for the EVS (Enhanced Voice Services) codec
+processing scripts as specified in 3GPP S4-121078.
+
+The tool supports two modes of operation:
+\begin{itemize}
+\item {\bf Subset selection:} randomly select one or more items from a
+  provided list, sampling without replacement.
+\item {\bf Range mode:} draw random integers from a specified numeric
+  range.
+\end{itemize}
+
+Deterministic behavior is achieved through a seed-based linear
+congruential sequence (LCS) generator, ensuring reproducible results
+across platforms when the same seed is used.
+
+%----------------------------------------------------------------------
+\subsection{Description of the algorithm}
+%----------------------------------------------------------------------
+
+The pseudo-random number generator is inherited from the EID tool
+({\tt eid.c}) in the STL. It implements a linear congruential
+generator as described by Knuth~\cite{Knuth}:
+
+\[
+  \mathrm{seed}_{n+1} = (69069 \times \mathrm{seed}_n + 1) \bmod 2^{32}
+\]
+
+The generator returns a uniformly distributed value in $[0, 1)$ by
+scaling:
+\[
+  r = 2^{-32} \times \mathrm{seed}
+\]
+
+The {\tt unsigned int} type (32 bits on all modern platforms) is used
+to ensure identical behavior on Windows, Linux, and macOS.
+
+\subsubsection{Subset mode}
+
+In subset mode, the tool selects {\em n} items from a list of {\em N}
+items without replacement. For each selection:
+\begin{enumerate}
+\item A random index $k = \lfloor N \cdot r \rfloor$ is computed.
+\item The item at position $k$ is output.
+\item The item is removed from the list (remaining items shift down).
+\item $N$ is decremented for the next draw.
+\end{enumerate}
+
+\subsubsection{Range mode}
+
+In range mode, the tool draws {\em n} random integers from the
+inclusive range $[\mathrm{start}, \mathrm{stop}]$. Each value is computed
+as:
+\[
+  v = \mathrm{start} + \lfloor (\mathrm{stop} - \mathrm{start} + 1) \cdot r \rfloor
+\]
+
+Note that in range mode, values are drawn independently (with
+replacement).
+
+\subsubsection{Dummy pre-runs}
+
+An optional number of dummy pre-runs can be specified. These advance
+the RNG state before selection begins, effectively providing a
+secondary diversification mechanism beyond the seed value.
+
+%----------------------------------------------------------------------
+\subsection{Implementation}
+%----------------------------------------------------------------------
+
+The tool is implemented as a single source file {\tt random.c} in the
+{\tt src/unsup/} directory.
+
+\subsubsection{Usage}
+
+{\tt
+\begin{verbatim}
+random [OPTIONS] [ITEM_LIST]
+\end{verbatim}
+}
+
+\subsubsection{Options}
+
+\begin{Descr}{40mm}
+\item[\tt -s SEED]
+        Seed for the random number generator. Any value between 0 and
+        $2^{32}-1$. Default: 3141592653.
+
+\item[\tt -d PRERUNS]
+        Number of dummy pre-runs to advance the RNG state before
+        selection begins. Default: 0.
+
+\item[\tt -r START STOP]
+        Range mode: draw random integers from the inclusive range
+        $[\mathrm{START}, \mathrm{STOP}]$. When this option is specified,
+        no item list is expected.
+
+\item[\tt -n NUM\_ITEMS]
+        Number of items to select (subset mode) or numbers to draw
+        (range mode). Default: 1.
+
+\item[\tt -v]
+        Verbose output: shows the internal state of the item list
+        after each selection (subset mode only).
+
+\item[\tt -h]
+        Print usage information and exit.
+\end{Descr}
+
+\subsubsection{Examples}
+
+\paragraph{Select one item from a list:}
+{\tt
+\begin{verbatim}
+$ random -s 42 alpha bravo charlie delta echo
+alpha
+\end{verbatim}
+}
+
+\paragraph{Select 3 items from a list with 3 dummy pre-runs:}
+{\tt
+\begin{verbatim}
+$ random -s 42 -d 3 -n 3 alpha bravo charlie delta echo
+bravo delta charlie
+\end{verbatim}
+}
+
+\paragraph{Draw 5 random integers from a range:}
+{\tt
+\begin{verbatim}
+$ random -s 12345 -r 10 20 -n 5
+12 19 12 14 14
+\end{verbatim}
+}
+
+\subsubsection{Limitations}
+
+\begin{itemize}
+\item Maximum of 1000 items in subset mode.
+\item The seed is parsed with {\tt atoi()}, limiting practical input to
+  signed integer range on some platforms. For full 32-bit range,
+  numeric overflow wraps as expected for unsigned arithmetic.
+\end{itemize}
+
+%----------------------------------------------------------------------
+\subsection{Tests and portability}
+%----------------------------------------------------------------------
+
+Three CTest test cases validate the tool:
+
+\begin{enumerate}
+\item {\bf random1:} Range mode with seed 12345, range $[10, 20]$, 5
+  draws. Expected output: ``12 19 12 14 14''.
+\item {\bf random2:} Subset mode with seed 42, selecting 1 item from 5.
+  Expected output starts with ``alpha''.
+\item {\bf random3:} Subset mode with seed 42, 3 dummy pre-runs,
+  selecting 3 items from 5. Expected output: ``bravo delta charlie''.
+\end{enumerate}
+
+Tests use {\tt PASS\_REGULAR\_EXPRESSION} to verify stdout matches
+expected values, ensuring cross-platform reproducibility of the RNG
+sequence.
+

src/unsup/CMakeLists.txt

@@ -39,6 +39,9 @@ add_executable(sh2chr sh2chr.c)
 
 add_executable(crc getcrc32.c)
 
+add_executable(random random.c)
+target_link_libraries(random ${M_LIBRARY})
+
 add_test(astrip1 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/astrip -q -smooth -wlen 145 -sample test_data/cftest1.dat test_data/astrip.smp)
 add_test(astrip1-verify ${CMAKE_COMMAND} -E compare_files test_data/astrip.smp test_data/astrip.ref)
 
@@ -71,3 +74,12 @@ add_test(fdelay5-verify ${CMAKE_COMMAND} -E compare_files test_data/delay-15.tst
 
 add_test(fdelay6 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/fdelay -hex 0xF test_data/litend.src test_data/delay-0f.tst)
 add_test(fdelay6-verify ${CMAKE_COMMAND} -E compare_files test_data/delay-0f.tst test_data/delay-15.ref)
+
+add_test(random1 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/random -s 12345 -r 10 20 -n 5)
+set_tests_properties(random1 PROPERTIES PASS_REGULAR_EXPRESSION "12 19 12 14 14")
+
+add_test(random2 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/random -s 42 alpha bravo charlie delta echo)
+set_tests_properties(random2 PROPERTIES PASS_REGULAR_EXPRESSION "^alpha ")
+
+add_test(random3 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/random -s 42 -d 3 -n 3 alpha bravo charlie delta echo)
+set_tests_properties(random3 PROPERTIES PASS_REGULAR_EXPRESSION "bravo delta charlie")

src/unsup/README.md

@@ -56,6 +56,10 @@ oper.c:     implement arithmetic operation on two files: add, subtract,
             multiply or divide two files applying scaling factors (linear
             or dB), and adding a DC level.
 
+random.c:   randomization tool for selecting items from a list or drawing
+            numbers from a range. Reuses the EID linear congruential
+            generator from eid.c.
+
 sb.c        swap bytes for word-oriented files. For VMS/Unix/MSDOS.
 
 sh2chr.c:   convert short-oriented (16-bit words) files to char-oriented