io7m-jfppg 1.0.1 Documentation
Package Information
Orientation
Overview
The jfppg package provides an OCaml program that generates Java code to serialize/deserialize double precision floats to and from custom fixed-point formats.
The program essentially takes a "signed" or "unsigned" declaration, and a pair of numbers denoting the number of bits to use for the integral and fractional parts of the fixed-point value. The program then generates a Java class declaration with functions for serializing and deserializing values of this type. The generated class contains various informative constants and contains complete Javadoc commenting. The generated class does not depend on the jfppg package and therefore may be easily distributed without adding extra dependencies to your program.
Installation
Installation Requirements
The package requires ocaml 3.10.2 or newer to compile. The package uses some trivial build scripts that will only run on POSIX-like systems. It is sufficient to use MSYS or Cygwin on Windows.
On POSIX platforms, the project can then be compiled using make:
$ make
On Windows platforms, the project can then be compiled using make win32:
$ make win32
Installation
Copy the fppg command to wherever your platform usually keeps executables.
Supported Systems
The software produces code that is known to pass 100% of the generated unit tests on the following platforms:
OSOS-VersionOS-ArchJDK-VendorJDK-VersionVMVM-Version
Linux3.2.2-1-ARCHx86_64Sun Microsystems Inc.1.6.0_22OpenJDK 64-Bit Server VM19.0-b09
Linux3.2.9-1-ARCHx86_64Sun Microsystems Inc.1.6.0_24OpenJDK 64-Bit Server VM20.0-b12
Windows XP5.1x86Oracle Corporation1.7.0_02Java Hotspot(TM) Client VM22.0-b10
Mac OS X10.6.8x86_64Apple Inc.1.6.0_29Java Hotspot(TM) 64-Bit Server VM20.4-b02-402
SunOS5.11x86Sun Microsystems Inc.1.6.0_21Java Hotspot(TM) Client VM17.0-b16
Platform Specific Issues
Win32
OCaml appears to have problems finding the correct libraries for linking (often raising linker errors such as "cannot find library ws2_32"). It is necessary to pass extra linker flags on the command line to deal with this (for MinGW):
ocamlopt -cclib '-L c:\mingw\lib' ...
Note that make win32 already takes care of this.
License
All files distributed with the jfppg package are placed under the following license:
Copyright © 2012 http://io7m.com

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        
Tutorial
Tutorial
The fppg command takes a class name, a signed or unsigned declaration, a size in bits for the integral part, and a size in bits for the fractional part:
$ fppg FixedI8F24Unsigned unsigned 8 24 > FixedI8F24Unsigned.java
        
The API presented by classes generated by fppg is trivial. Assuming that an unsigned fixed point type with 8 bits for the integral part and 24 bits for the fractional part:
final FixedI8F24Unsigned u = new FixedI8F24Unsigned(1.0);
        
The serialized value in u is accessible from the field u.value. This value can be decoded back to a double precision value using the toDouble function:
final double d = FixedI8F24Unsigned.toDouble(u.value);