The cl-pcg Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-pcg Reference Manual

This is the cl-pcg Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:28:37 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-pcg is a permuted congruential generator implementation in pure Common Lisp.

Permuted congruential generators are seedable, small, fast, fairly-hard-to-predict random number generators. They can be useful for things like games. They can also be advanced and rewound efficiently.

PCGs are not cryptographically secure. If you need that, look elsewhere.

Testing with Dieharder

There's a Roswell script you can use to make a little executable that will spew random bytes to stdout, suitable for piping into dieharder:

make build/pcg
./build/pcg | dieharder -a -g 200

build/pcg will dump out infinite random bytes until stdout breaks, so maybe don't run it in a bare terminal unless you want to just totally hose it.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-pcg

Author

Steve Losh <steve@stevelosh.com>

Home Page

https://sjl.bitbucket.io/cl-pcg/

License

MIT

Description

A bare-bones Permuted Congruential Generator implementation in pure Common Lisp.

Version

1.0.0

Dependency

sb-rotate-byte

Source

cl-pcg.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 cl-pcg/vendor

Parent

cl-pcg (system)

Location

vendor/

Components

Previous: , Up: Modules   [Contents][Index]

3.2 cl-pcg/src

Dependency

package.lisp (file)

Parent

cl-pcg (system)

Location

src/

Component

pcg.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-pcg.asd

Location

cl-pcg.asd

Systems

cl-pcg (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-pcg/vendor/quickutils-package.lisp

Parent

vendor (module)

Location

vendor/quickutils-package.lisp

Packages

pcg.quickutils

Internal Definitions

*utilities* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cl-pcg/vendor/quickutils.lisp

Dependency

quickutils-package.lisp (file)

Parent

vendor (module)

Location

vendor/quickutils.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cl-pcg/package.lisp

Dependency

vendor (module)

Parent

cl-pcg (system)

Location

package.lisp

Packages

pcg


Previous: , Up: Lisp files   [Contents][Index]

4.1.5 cl-pcg/src/pcg.lisp

Parent

src (module)

Location

src/pcg.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 pcg.quickutils

Package that contains Quickutil utility functions.

Source

quickutils-package.lisp (file)

Use List

common-lisp

Used By List

pcg

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.2 pcg

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: with-gensyms NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

pcg.quickutils

Source

quickutils.lisp (file)

Macro: with-unique-names NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

pcg.quickutils

Source

quickutils.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: make-pcg &key SEED STREAM-ID

Create and return a new PCG.

If ‘seed‘ is ‘nil‘, a fresh random seed will be generated with the implementation’s ‘cl:random‘ function, as if by:

(random ... (make-random-state t))

Package

pcg

Source

pcg.lisp (file)

Function: make-pcg% SEED STREAM-ID

Create and return a new ‘pcg‘ for the given ‘seed‘ and ‘stream-id‘.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-advance PCG STEPS

Advance the state of ‘pcg‘ by ‘steps‘ steps.

This function returns ‘nil‘ and is only useful for its side effects.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-advance% PCG STEPS

Advance the state of ‘pcg‘ by ‘steps‘ steps.

This function returns ‘nil‘ and is only useful for its side effects.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random PCG BOUND &optional MAX INCLUSIVE?

Generate and return a random number in the specified interval.

If ‘max‘ is omitted the interval will be ‘[0, bound)‘.

If ‘max‘ is given the interval will be ‘[bound, max)‘.

If ‘inclusive?‘ is given the interval will be ‘[bound, max]‘.

If either of ‘bound‘ or ‘max‘ are floats, the result will be a float. Otherwise the result will be an integer.

As a side effect, the state of ‘pcg‘ will be advanced.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random% PCG

Return a random ‘(unsigned-byte 32)‘.

As a side effect, the state of ‘pcg‘ will be advanced.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random-bounded% PCG BOUND

Return a random integer between ‘0‘ (inclusive) and ‘bound‘ (exclusive).

As a side effect, the state of ‘pcg‘ will be advanced.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random-float% PCG

Return a random ‘single-float‘ between ‘0.0‘ and ‘1.0‘.

As a side effect, the state of ‘pcg‘ will be advanced.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-rewind PCG STEPS

Rewind the state of ‘pcg‘ by ‘steps‘ steps.

This function returns ‘nil‘ and is only useful for its side effects.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-rewind% PCG STEPS

Rewind the state of ‘pcg‘ by ‘steps‘ steps.

This function returns ‘nil‘ and is only useful for its side effects.

This is a low-level function that assumes you are passing in the correct types.

Package

pcg

Source

pcg.lisp (file)

Function: symb &rest ARGS

Receives any number of objects, concatenates all into one string with ‘#’mkstr‘ and converts them to symbol.

Extracted from _On Lisp_, chapter 4.

See also: ‘symbolicate‘

Package

pcg.quickutils

Source

quickutils.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Structures

Structure: pcg ()
Package

pcg

Source

pcg.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: state
Type

pcg::u64

Initform

0

Readers

pcg-state (function)

Writers

(setf pcg-state) (function)

Slot: increment
Type

pcg::u64

Initform

0

Readers

pcg-increment (function)

Writers

(setf pcg-increment) (function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Constants

Constant: +limit+
Package

pcg

Source

pcg.lisp (file)

Constant: +modulus+
Package

pcg

Source

pcg.lisp (file)

Constant: +multiplier+
Package

pcg

Source

pcg.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Special variables

Special Variable: *global-generator*
Package

pcg

Source

pcg.lisp (file)

Special Variable: *utilities*
Package

pcg.quickutils

Source

quickutils-package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Macros

Macro: check-types &rest PLACE-TYPE-PAIRS
Package

pcg

Source

pcg.lisp (file)

Macro: defun-inline NAME &body BODY

Like ‘defun‘, but declaims ‘name‘ to be ‘inline‘.

Package

pcg

Source

pcg.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Functions

Function: % N
Package

pcg

Source

pcg.lisp (file)

Function: *+ A B INCREMENT
Package

pcg

Source

pcg.lisp (file)

Function: actually-make-pcg &key (STATE STATE) (INCREMENT INCREMENT)
Package

pcg

Source

pcg.lisp (file)

Function: advance-state PCG
Package

pcg

Source

pcg.lisp (file)

Function: compute-increment STREAM-ID
Package

pcg

Source

pcg.lisp (file)

Function: copy-pcg INSTANCE
Package

pcg

Source

pcg.lisp (file)

Function: mkstr &rest ARGS

Receives any number of objects (string, symbol, keyword, char, number), extracts all printed representations, and concatenates them all into one string.

Extracted from _On Lisp_, chapter 4.

Package

pcg.quickutils

Source

quickutils.lisp (file)

Function: pcg-increment INSTANCE
Function: (setf pcg-increment) VALUE INSTANCE
Package

pcg

Source

pcg.lisp (file)

Function: pcg-p OBJECT
Package

pcg

Source

pcg.lisp (file)

Function: pcg-random-float PCG MIN MAX

Return a random ‘single-float‘.

As a side effect, the state of ‘pcg‘ will be advanced.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random-integer PCG MIN MAX

Return a random integer.

As a side effect, the state of ‘pcg‘ will be advanced.

Package

pcg

Source

pcg.lisp (file)

Function: pcg-random-range% PCG MIN MAX
Package

pcg

Source

pcg.lisp (file)

Function: pcg-state INSTANCE
Function: (setf pcg-state) VALUE INSTANCE
Package

pcg

Source

pcg.lisp (file)

Function: permute-rotate DATA SELECTOR
Package

pcg

Source

pcg.lisp (file)

Function: permute-xor-shift DATA
Package

pcg

Source

pcg.lisp (file)

Function: resolve-pcg PCG-DESIGNATOR
Package

pcg

Source

pcg.lisp (file)

Function: resolve-seed SEED
Package

pcg

Source

pcg.lisp (file)

Function: rotate-byte COUNT BYTESPEC INTEGER

Rotates a field of bits within INTEGER; specifically, returns an integer that contains the bits of INTEGER rotated COUNT times leftwards within the byte specified by BYTESPEC, and elsewhere contains the bits of INTEGER. See http://www.cliki.net/ROTATE-BYTE

Package

pcg

Source

pcg.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Types

Type: pcg-designator ()
Package

pcg

Source

pcg.lisp (file)

Type: string-designator ()

A string designator type. A string designator is either a string, a symbol, or a character.

Package

pcg.quickutils

Source

quickutils.lisp (file)

Type: u32 ()
Package

pcg

Source

pcg.lisp (file)

Type: u64 ()
Package

pcg

Source

pcg.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-pcg.asd: The cl-pcg<dot>asd file
cl-pcg/package.lisp: The cl-pcg/package<dot>lisp file
cl-pcg/src: The cl-pcg/src module
cl-pcg/src/pcg.lisp: The cl-pcg/src/pcg<dot>lisp file
cl-pcg/vendor: The cl-pcg/vendor module
cl-pcg/vendor/quickutils-package.lisp: The cl-pcg/vendor/quickutils-package<dot>lisp file
cl-pcg/vendor/quickutils.lisp: The cl-pcg/vendor/quickutils<dot>lisp file

F
File, Lisp, cl-pcg.asd: The cl-pcg<dot>asd file
File, Lisp, cl-pcg/package.lisp: The cl-pcg/package<dot>lisp file
File, Lisp, cl-pcg/src/pcg.lisp: The cl-pcg/src/pcg<dot>lisp file
File, Lisp, cl-pcg/vendor/quickutils-package.lisp: The cl-pcg/vendor/quickutils-package<dot>lisp file
File, Lisp, cl-pcg/vendor/quickutils.lisp: The cl-pcg/vendor/quickutils<dot>lisp file

L
Lisp File, cl-pcg.asd: The cl-pcg<dot>asd file
Lisp File, cl-pcg/package.lisp: The cl-pcg/package<dot>lisp file
Lisp File, cl-pcg/src/pcg.lisp: The cl-pcg/src/pcg<dot>lisp file
Lisp File, cl-pcg/vendor/quickutils-package.lisp: The cl-pcg/vendor/quickutils-package<dot>lisp file
Lisp File, cl-pcg/vendor/quickutils.lisp: The cl-pcg/vendor/quickutils<dot>lisp file

M
Module, cl-pcg/src: The cl-pcg/src module
Module, cl-pcg/vendor: The cl-pcg/vendor module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (   *  
A   C   D   F   M   P   R   S   W  
Index Entry  Section

%
%: Internal functions

(
(setf pcg-increment): Internal functions
(setf pcg-state): Internal functions

*
*+: Internal functions

A
actually-make-pcg: Internal functions
advance-state: Internal functions

C
check-types: Internal macros
compute-increment: Internal functions
copy-pcg: Internal functions

D
defun-inline: Internal macros

F
Function, %: Internal functions
Function, (setf pcg-increment): Internal functions
Function, (setf pcg-state): Internal functions
Function, *+: Internal functions
Function, actually-make-pcg: Internal functions
Function, advance-state: Internal functions
Function, compute-increment: Internal functions
Function, copy-pcg: Internal functions
Function, make-pcg: Exported functions
Function, make-pcg%: Exported functions
Function, mkstr: Internal functions
Function, pcg-advance: Exported functions
Function, pcg-advance%: Exported functions
Function, pcg-increment: Internal functions
Function, pcg-p: Internal functions
Function, pcg-random: Exported functions
Function, pcg-random%: Exported functions
Function, pcg-random-bounded%: Exported functions
Function, pcg-random-float: Internal functions
Function, pcg-random-float%: Exported functions
Function, pcg-random-integer: Internal functions
Function, pcg-random-range%: Internal functions
Function, pcg-rewind: Exported functions
Function, pcg-rewind%: Exported functions
Function, pcg-state: Internal functions
Function, permute-rotate: Internal functions
Function, permute-xor-shift: Internal functions
Function, resolve-pcg: Internal functions
Function, resolve-seed: Internal functions
Function, rotate-byte: Internal functions
Function, symb: Exported functions

M
Macro, check-types: Internal macros
Macro, defun-inline: Internal macros
Macro, with-gensyms: Exported macros
Macro, with-unique-names: Exported macros
make-pcg: Exported functions
make-pcg%: Exported functions
mkstr: Internal functions

P
pcg-advance: Exported functions
pcg-advance%: Exported functions
pcg-increment: Internal functions
pcg-p: Internal functions
pcg-random: Exported functions
pcg-random%: Exported functions
pcg-random-bounded%: Exported functions
pcg-random-float: Internal functions
pcg-random-float%: Exported functions
pcg-random-integer: Internal functions
pcg-random-range%: Internal functions
pcg-rewind: Exported functions
pcg-rewind%: Exported functions
pcg-state: Internal functions
permute-rotate: Internal functions
permute-xor-shift: Internal functions

R
resolve-pcg: Internal functions
resolve-seed: Internal functions
rotate-byte: Internal functions

S
symb: Exported functions

W
with-gensyms: Exported macros
with-unique-names: Exported macros

Jump to:   %   (   *  
A   C   D   F   M   P   R   S   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   I   S  
Index Entry  Section

*
*global-generator*: Internal special variables
*utilities*: Internal special variables

+
+limit+: Internal constants
+modulus+: Internal constants
+multiplier+: Internal constants

C
Constant, +limit+: Internal constants
Constant, +modulus+: Internal constants
Constant, +multiplier+: Internal constants

I
increment: Exported structures

S
Slot, increment: Exported structures
Slot, state: Exported structures
Special Variable, *global-generator*: Internal special variables
Special Variable, *utilities*: Internal special variables
state: Exported structures

Jump to:   *   +  
C   I   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   T   U  
Index Entry  Section

C
cl-pcg: The cl-pcg system

P
Package, pcg: The pcg package
Package, pcg.quickutils: The pcg<dot>quickutils package
pcg: The pcg package
pcg: Exported structures
pcg-designator: Internal types
pcg.quickutils: The pcg<dot>quickutils package

S
string-designator: Internal types
Structure, pcg: Exported structures
System, cl-pcg: The cl-pcg system

T
Type, pcg-designator: Internal types
Type, string-designator: Internal types
Type, u32: Internal types
Type, u64: Internal types

U
u32: Internal types
u64: Internal types

Jump to:   C   P   S   T   U