grey.h File Reference

#include <stdint.h>
#include <inttypes.h>

Include dependency graph for grey.h:

Go to the source code of this file.

Macros
#define	GREY_VERSION   "1.0.0"
	Version of the grey.h API using semantic versioning.
#define	GREY_UINTBITS   64
#define	GREY_MAX   ((uint64_t) UINT64_MAX)
#define	GREY_FMT   PRIu64
#define	GREY_FMTx   PRIx64
#define	GREY_FMTX   PRIX64
#define	grey_add(grey, delta)   grey_to(grey_from((grey)) + (delta))
	Utility wrapper adding/subtracting a delta to a Grey-encoded value. More...
#define	grey_incr(grey)   grey_add((grey), 1)
	Utility wrapper incrementing a Grey-encoded value by 1. More...
#define	grey_decr(grey)   grey_add((grey), -1)
	Utility wrapper decrementing a Grey-encoded value by 1. More...

Typedefs
typedef uint64_t	grey_code_t
typedef grey_code_t	grey_int_t
	Binary value (regular integer), of the same size as Grey-coded values.

Functions
grey_code_t	grey_to (grey_int_t value)
	Converts a regular binary unsigned integer to Grey code. More...
grey_int_t	grey_from (grey_code_t grey)
	Converts a Grey-encoded value into a regular binary unsigned integer. More...
uint8_t	grey_binstr (char str[GREY_UINTBITS+1], grey_code_t grey)
	Fills a string with the Grey code in binary representation. More...

Detailed Description

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

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.

Copyright

Copyright © 2020, Matjaž Guštin dev@m.nosp@m.atja.nosp@m.z.it https://matjaz.it. All rights reserved. License: BSD 3-clause license.

Macro Definition Documentation

GREY_UINTBITS

GREY_UINTBITS   64

Defines the domain in bits of the Grey codes. In other words what is the max value a Grey code could hold.

• Set it to 64 to convert uint64_t values to and from Grey codes.
• Set it to 32 to convert uint32_t values to and from Grey codes.
• Set it to 16 to convert uint16_t values to and from Grey codes.
• Set it to 8 to convert uint8_t values to and from Grey codes.

grey_code_t and grey_int_t will automatically be defined as the proper integer types to hold the Grey-encoded values and their binary (regular integer) values.

Defaults to 64 thus using uint64_t integers only, unless specified otherwise at compile time.

GREY_MAX

GREY_MAX   ((uint64_t) UINT64_MAX)

Maximum allowed value that grey_code_t and grey_int_t support.

Can be increased with GREY_UINTBITS.

GREY_FMT

GREY_FMT   PRIu64

Format specifier for printf and similar functions of the decimal integer representation of grey_code_t and grey_int_t.

Usage example:

grey_code_t code = 15U;
printf("My Grey code is " GREY_FMT "!\n", code); // prints 15

GREY_FMTx

GREY_FMTx   PRIx64

Format specifier for printf and similar functions of the hexadecimal lowercase integer representation of grey_code_t and grey_int_t.

Usage example:

grey_code_t code = 15;
printf("My Grey code is " GREY_FMTx "!\n", code); // prints "f"

GREY_FMTX

GREY_FMTX   PRIX64

Format specifier for printf and similar functions of the hexadecimal uppercase integer representation of grey_code_t and grey_int_t.

Usage example:

grey_code_t code = 15;
printf("My Grey code is " GREY_FMTX "!\n", code); // prints "F"

grey_add

#define grey_add	(		grey,
			delta
	)		grey_to(grey_from((grey)) + (delta))

Utility wrapper adding/subtracting a delta to a Grey-encoded value.

Warning

No checks are performed for overflows/underflows/integer conversion errors etc.!

Parameters

grey	value to increase/decrease.
delta	value to add/remove from the grey code, signed.

Returns

increased/decreased Grey code.

grey_incr

#define grey_incr

(

grey

)

grey_add((grey), 1)

Utility wrapper incrementing a Grey-encoded value by 1.

Warning

No checks are performed for overflows!

Parameters

grey	value to increment.

Returns

incremented Grey code = grey+1.

grey_decr

#define grey_decr

(

grey

)

grey_add((grey), -1)

Utility wrapper decrementing a Grey-encoded value by 1.

Warning

No checks are performed for underflows!

Parameters

grey	value to decrement.

Returns

decremented Grey code = grey-1.

Typedef Documentation

grey_code_t

grey_code_t

Grey-encoded value, to distinguish them from binary values.

Can be altered with GREY_UINTBITS.

Function Documentation

grey_to()

grey_code_t grey_to

(

grey_int_t

value

)

Converts a regular binary unsigned integer to Grey code.

Parameters

value

the binary value (regular integer) to convert

Returns

value converted into Grey code

grey_from()

grey_int_t grey_from

(

grey_code_t

grey

)

Converts a Grey-encoded value into a regular binary unsigned integer.

Parameters

grey	value to convert

Returns

binary value (regular integer) of the Grey code

grey_binstr()

uint8_t grey_binstr	(	char	str[GREY_UINTBITS+1],
		grey_code_t	grey
	)

Fills a string with the Grey code in binary representation.

The representation is:

• ASCII
• big endian (as humans would read and write the number)
• contains no spaces
• is null-terminated
• is at most GREY_UINTBITS bytes in size (excluding the null-terminator).

Example: grey_binstr(str, 0x0E) fills str with "1110\0" and returns 4.

Note: this is just a utility function, is not meant to be super-efficient.

Parameters

[out]	str	buffer of GREY_UINTBITS+1 bytes (the "+1" is the space for the null-terminator).
[in]	grey	value to encode.

Returns

length of the binary string written into str excluding the null-terminator