Postmodern immutable and persistent data structures for C++

.. image:: :target: :alt: Travis Badge

.. image:: :target: :alt: CodeCov Badge

.. raw:: html

<a href=""><img style="position: absolute; top: 0; right: 0; border: 0;" src="" alt="Fork me on GitHub" data-canonical-src=""></a>

immer is a library of persistent_ and immutable_ data structures written in C++.

.. _persistent: .. _immutable:

  • Persistent means that when you modify the data structure, the old value is preserved.

  • Immutable means that all manipulation methods are const.

An object is never modified in place but a new value is returned instead. Since the old value is still there and it will never change, the new value can transparently keep references to common parts of it. This property is called structural sharing.

Read the docs Check the code Talks [Video (7min)] <>_ [Slides] <>_ The tragedy of the value based architecture (MeetingC++ 2016)

.. attention:: This library is work in progress and its API is not complete enough yet.

A stable release is scheduled for early Q2 2017. This release will use a more liberal license, which is yet to be determined.

.. admonition:: Sponsorship :class: tip

This library is so far a non-remunerated full time job and months of research and development are invested in it. To ensure it’s long term sustainability, we will be launching a sponsoring program in early 2017.

Should your organization be interested in supporting it, contact: [email protected]

.. include:index/end


.. github does not support the literalinclude directive. This example is copy pasted form example/vector/intro.cpp

.. code-block:: c++

#include int main() { const auto v0 = immer::vector{}; const auto v1 = v0.push_back(13); assert(v0.size() == 0 && v1.size() == 1 && v1[0] == 13);

   const auto v2 = v1.set(0, 42);
   assert(v1[0] == 13 && v2[0] == 42);



In the last few years, there has been a growing interest in immutable data structures, motivated by the horizontal scaling of our processing power and the ubiquity of highly interactive systems. Languages like Clojure_ and Scala_ provide them by default, and implementations for JavaScript like Mori_ and Immutable.js_ are widely used, specially in combination with modern UI frameworks like React_.

Interactivity Thanks to persistence and structural sharing, new values can be efficiently compared with old ones. This enables simpler ways of reasoning about change that sit at the core of modern interactive systems programming paradigms like reactive programming_.

Concurrency Passing immutable data structures by value does not need to copy any data. In the absence of mutation, data can be safely read from multiple concurrent processes, and enable concurrency patterns like share by communicating_ efficiently.

Parallelism Some recent immutable data structures have interesting properties like :math:O(log(n)) concatenation, which enable new kinds of parallelization algorithms_.

.. _clojure: .. _scala:

.. _mori: .. _immutable.js: .. _react:

.. _reactive programming: .. _share by communicating: .. _parallelization algorithms:


Idiomatic This library doesn’t pretend that it is written in Haskell. It leverages features from recent standards to provide an API that is both efficient and natural for a C++ developer.

Performant You use C++ because you need this. Immer implements state of the art data structures with efficient cache utilization and have been proven production ready in other languages. It also includes our own improvements over that are only possible because of the C++’s ability to abstract over memory layout. We monitor the performance impact of every change by collecting benchmark results_ directly from CI.

.. _benchmark results:

Customizable We leverage templates and policy-based design_ to build data-structures that can be adapted to work efficiently for various purposes and architectures, for example, by choosing among various :doc:memory management strategies<memory>. This turns immer into a good foundation to provide immutable data structures to higher level languages with a C runtime, like Python_ or Guile_.

.. _python: .. _guile: .. _policy-based design:


This library is written in C++14 and a compliant compiler is necessary. It is continuously tested_ with Clang 3.8 and GCC 6, but it might work with other compilers and versions.

No external library is necessary and there are no other requirements.

.. _continuously tested:

.. note:: Some optional modules do have other dependencies, but this is noted in their respective documentation pages.


This is a header only library. Just make sure that the project root is in your include path.


One may generate a development project using CMake_::

mkdir build && cd build
cmake ..

To automatically fetch and build all depedencies required to build and run the tests and benchmarks run::

make deps

From then on, one may build and run all tests by doing::

make check

In order to build and run all benchmarks when running make check, run cmake again with the option -DCHECK_BENCHMARKS=1. The results of running the benchmarks will be saved to a folder reports/ in the project root.

.. _cmake:


This software is licensed under the GPLv3 license_.

.. admonition:: License header

Copyright (C) 2016 Juan Pedro Bolivar Puente

This file is part of immer.

immer is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

immer is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with immer.  If not, see <>.

.. _gplv3 license:

.. image:: :alt: GPL3 logo :target:

Related Repositories



Create the next immutable state by mutating the current one ...



Postmodern immutable and persistent data structures for C++ ...



Use immer to drive state with a React hooks ...



Create the next immutable state by mutating the current one ...