Safer integers in C++.

Overview

Integers

integers is a package for C++ that implements integer types with explicit, well-defined behavior (of your choice!) on overflow, underflow, division by 0, casting, and shifting too far.

integers is developed and maintained by members of the Fuchsia Security Team, but it is not an official Google product.

Defined behaviors are trapping (trapping and associated stand-alone helper functions), wrapping (wrapping and helpers), or clamping/saturating (clamping and helpers). You choose your preferred policy/behavior by using the stand-alone template helper functions and/or the template classes.

There is also a ranged template class for situations where you need a type that constrains integers to a specific range of values.

The main goals of this library are correctness and usability. Ideally, you can simply drop in the right type for your situation, and the rest of your code works as expected — the template classes should be fully compatible with the built-in primitive types. (If you find any gaps in functionality, that’s a bug! Please file an issue or send a pull request.)

Another goal is that this library should be easy to import and use, without any transitive dependencies or other complications. integers is a headers-only library. (See Installation.)

integers is tested to work with C++17 and C++20.

Usage

An example use case for integers is file format parsers and deserializers and so on, which are constantly calculating and re-calculating offsets and indices into files. It is all too easy to have mistakes in that kind of code, with the classic C integer semantics.

You can see a simple example of 4 ways to use the trapping helper functions and the trapping template class in demo.cc. It shows a simple example of code that is vulnerable to integer overflow, and ways to fix it.

For full documentation, see the Markdown comments in the header files.

Installation

To install, simply copy the header files into a place that your compiler can see them. You can do this manually, or you can edit the Makefile to set your desired INSTALL_DIR, and then run make install.

Efficiency

Dan Luu reports some general time efficiency numbers.

This implementation is intentionally naive, so that it is easy to understand and maintain. It might not be as efficient as absolutely possible. However, it should be in the ballpark of Microsoft’s SafeInt, Chromium’s numerics, and what you could do by hand.

Separate from run-time speed, adding integer overflow checks (as trapping , trapping_mul, et c. do) increases object code size proportional to how many checking call sites you have. integers aims to reduce the magnitude of the code size increase in NDEBUG builds. (Note the implementation in trap.h.)

Acknowledgements

Special thanks to Jan Wilken Dörrie and Dana Jansens for the help in implementation and general C++ advice.

See Also

These functions and classes were inspired in part by Rust’s std::num::Wrapping, std::intrinsics::wrapping_add, and std::intrinsics::add_with_overflow. This library generalizes the idea and brings it all into a single package for C++.

There are many efforts to provide better integer semantics for C++. You might like to check them out:

TODO

TODO: Consider providing some operations that don’t exist (such as rotate) for standard C and C++ integers.

integers will have a complete test suite. That’s a TODO in progress, along with the rest of the implementation work. Currently only trapping and its helper functions are implemented and tested.

For comments, constructive criticism, patches, help, et c., please feel free to file a GitHub issue or send a pull request! See Contributing and the Code Of Conduct.

You might also like...
Comments
  • Fix minor typo in README

    Fix minor typo in README

    Remove extra space in "etc" in Readme. Didn't open an issue because the typo was very minor.

    It's a good idea to open an issue first for discussion.

    • [x] Tests pass
    • [x] Appropriate changes to README are included in PR
    opened by kinshukdua 1
Owner
Google
Google ❤️ Open Source
Google
Two programs to find the LCM of two positive integers.

LCM-finders LCM-finders? LCM-finders is the repo for my LCM finder projects. I made this program in two similar languages. ?? Note: Two languages mean

Chandula Janith 1 Apr 15, 2022
A slightly safer io access library

SaferIO About SaferIO is an easy to use slightly more safe IO access library. Features Access IO ports, MSRs, physical memory, and PCI configuration s

null 9 Nov 26, 2022
A simple C library for compressing lists of integers using binary packing

The SIMDComp library A simple C library for compressing lists of integers using binary packing and SIMD instructions. The assumption is either that yo

Daniel Lemire 409 Dec 22, 2022
Random access array of tightly packed unsigned integers

PackedArray: random access array of tightly packed unsigned integers TLDR PackedArray comes to the rescue when you're in a desperate need for an uint9

Gregory Pakosz 140 Dec 8, 2022
A C++20 implementation of safe (wrap around) integers following MISRA C++ rules

PSsimplesafeint A C++20 implementation of safe (wrap around) integers following MISRA C++ rules. I might also work on a C++17 implementation, but this

Peter Sommerlad 37 Aug 15, 2022
C++ class for creating and computing arbitrary-length integers

BigNumber BigNumber is a C++ class that allows for the creation and computation of arbitrary-length integers. The maximum possible length of a BigNumb

Limeoats 143 Dec 14, 2022
Two programs to find the LCM of two positive integers.

LCM-finders LCM-finders? LCM-finders is the repo for my LCM finder projects. I made this program in two similar languages. ?? Note: Two languages mean

Chandula Janith 1 Apr 15, 2022
Given two arrays X and Y of positive integers, find the number of pairs such that x^y > y^x (raised to power of) where x is an element from X and y is an element from Y.

Number-of-pairs Given two arrays X and Y of positive integers, find the number of pairs such that x^y > y^x (raised to power of) where x is an element

Rajesh Kumar Sah 1 Nov 20, 2021