Using the library in your code

Installing

You have two choices for installing the library for use in your programs. Either download a pre-compiled binary for your system, or build the library yourself. The first is simpler, the latter more flexible. See the development documentation for how to build the library on your system. I make pre-compiled binaries available for Windows and Linux on Intel platforms.

Linux

Download this zip file and unpack it. This will give you the shared library file libojrand.so.0.0, the C header file ojrandlib.h, the Python module ojrandlib.py, and the Java archive ojrandlib.jar. Which of these you will need and where you will install them will depend on your development environment.

A common place to put the shared library is /usr/local/lib, after which you will have to run sudo ldconfig to rebuild the system’s shared library cache. You may instead want to place it somewhere in your private development tree, in which case you will have to update /etc/ld.so.conf to look for it. You may also want to create a link to it with a simpler name, like this:

sudo ln -s /usr/local/lib/libojrand.so.0.0 /usr/local/lib/libojrand.so

The C header file ojrandlib.h can be installed in /usr/local/include, or somewhere in your development tree if you add a -I option pointing to it in your C compiler invocations.

RandLib expects Python 3. If you are using Python 2.X, you can install the Python 3 package available in all major distributions and the two will get along fine. The Python module ojrandlib.py will have to be placed where your particular version of Python expects it (on my system, that’s /usr/local/lib/python3.2/site-packages), or else its location can be added to sys.path explicitly.

I recommend openjdk as a good Java for Linux. The java archive ojrandlib.jar must be placed in the “extensions” directory of your JDK (for example, /usr/lib/jvm/java-1.7.0-openjdk-i386/jre/lib/ext), which will vary by version, or else be added to the -cp option when invoking Java programs that use it (you may also want to use -Djava.library.path= to specify a non-standard location for the shared library).

Windows

Download this zip file and unpack it. This will give you the library file ojrand.dll, the C header file ojrandlib.h, the Python module ojrandlib.py, and the Java archive ojrandlib.jar. Which of these you will need and where you will install them will depend on your development environment.

Windows may not let you copy the DLL to the System32 directory where other DLLs are found, so you’ll have to have this file present in the directory with your executable to use with C and C++ programs. You probably will be allowed to install it in your Java JDK or your Python directory tree for access from those languages. The exact location where the library is expected will depend on your version of Java or Python.

If you are using MinGW as I recommend, the C header file ojrandlib.h can be installed in C:/MinGW/include, or somewhere in your development tree if you add a -I option pointing to it in your C compiler invocations. If you’re using a different development environment you’ll have to put the header file where it expects.

To use RandLib with Python, you will have to install Python 3. The Python module ojrandlib.py will have to be placed where your particular version of Python expects it (for example, C:/Python33/Lib), or else its location can be added to sys.path explicitly.

Likewise, you must have a Java JDK, and ojrandlib.jar must be placed in the “extensions” directory of your JDK (for example, C:/Program Files/Java/jdk1.7.0_21/jre/lib/ext), which will vary by version, or else be added to the -cp option when invoking Java programs that use it (you may also want to use -Djava.library.path= to specify a non-standard location for the shared library).

Using the library in your programs

C, C++

C and C++ programs need only include the single header file ojrandlib.h, and link against the library. Further details of the functions available are in the C API and C++ API documents. An example in C:

#include <stdlib.h>
#include <stdio.h>

#include "ojrandlib.h"

int main(int argc, char *argv[]) {
    ojr_generator *g = ojr_open(NULL);

    printf("  %d  %d  %d  %f\n",
        ojr_rand(g, 100), ojr_next16(g), ojr_next32(g),
        ojr_next_double(g));

    ojr_close(g);
    return 0;
}

And in C++:

#include <iostream>
using namespace std;

#include "ojrandlib.h"
using namespace oj;

int main(int argc, char *argv[]) {
    Generator g("mt19937");

    cout << "  " << g.rand(100) << "  " << g.next16()     <<
            "  " << g.next32()  << "  " << g.nextDouble() << "\n";

    return 0;
}

Python

As long as your Python implementation can find the library where you have installed it, programs need only import the module ojrandlib. Further details of the functions available are shown in the Python API document. A short example:

import ojrandlib as rl

g = rl.Generator("jkiss")

print("  {:d}".format(g.rand(100)), " {:d}".format(g.next16()), end="")
print(" {:d}".format(g.next32()), " {:f}".format(g.next_double()))

Java

Your Java programs will have to import the classes, and also load the library. More details of the classes and functions available are in the Java API document. Here’s a short example:

import com.onejoker.randlib.*;

public class Hello {
    static { System.loadLibrary("ojrand"); }

    public static void main(String[] args) {
        Generator g = new Generator("mt19937");

        for (int i = 0; i < 20; ++i) {
            System.out.printf("%12d ", g.next32());
            if (4 == (i % 5)) System.out.printf("\n");
        }
    }
}