Grey codes a.k.a. Reflected binary codes in C, made simple

Grey codes or Reflected binary codes are encodings of unsigned integers such that two adjacent values have only 1 bit of difference. Originally designed for electromechanical switches so that the state would transition cleanly from one value to the other without other values being represented in between. More details on Wikipedia.

This is a tiny tiny C99 library that converts unsigned integers of any size from and to Grey codes.

By default, the library will operate on uint64_t integers for conversions from/to Grey codes. If you prefer using smaller integer (but also limit the domain of the Grey codes and their values), redefine the macro GREY_UINTBITS to 32, 16 or 8 instead of 64.

Usage example

// Convert to Grey code
grey_code_t my_code = grey_to(10); // my_code is now 0b1111 = 0x0F = 15
 
// Convert from Grey code
grey_int_t my_value = grey_from(my_code);  // my_value is now 10 again
 
// Handy macro for incrementing Grey codes
grey_code_t my_code = grey_to(103);  // my_code is now 84, representing 103
my_code = grey_incr(my_value);  // my_code is now 92, representing 104
my_value = grey_from(my_code);  // my_value is now 103
 
// Or for decrementing
my_code = grey_decr(85);
 
// Or for custom addition/subtraction (may be unsafe!)
my_code = grey_add(85, 5);
 
// Printing format
my_code = grey_to(42);
printf("Int %u "
       "= Grey decimal %" GREY_FMT
       " = Grey lowercase hex 0x%" GREY_FMTx
       " = Grey uppercase hex 0x%" GREY_FMTX "\n",
       42, my_code, my_code, my_code);
 
// Converting to binary string
char binstr[GREY_UINTBITS + 1];
uint8_t len = grey_binstr(binstr, 7);  // str now contains "111\0", len is 3

You can also check the tst/test.c file for more examples.

Include it in your project

Static source inclusion

Copy the inc/grey.h and src/grey.c files into your existing C project, add them to the source folders and compile. Done.

If you prefer using smaller integers, redefine GREY_UINTBITS.

Compiling into all possible targets

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DGREY_UINTBITS=64
cmake --build .

This will build all targets:

• a libgrey.dylib/libgrey.dll shared library
• a libgreystatic.a static library
• a test runner executable test_grey
• the Doxygen documentation (if Doxygen is installed)

To compile with the optimisation for size, use the -DCMAKE_BUILD_TYPE=MinSizeRel flag instead.

If you prefer using smaller integers, set -DGREY_UINTBITS=32 (or 16 or 8).