https://github.com/grillbaer/persistentds

Persistent data structures - immutable copy-on-write lists, maps and sets for Java
https://github.com/grillbaer/persistentds

copy-on-write immutability java persistent-data-structure

Last synced: 13 days ago
JSON representation

Persistent data structures - immutable copy-on-write lists, maps and sets for Java

• Host: GitHub
• URL: https://github.com/grillbaer/persistentds
• Owner: grillbaer
• License: apache-2.0
• Created: 2018-03-11T11:52:39.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2021-02-14T16:37:45.000Z (almost 5 years ago)
• Last Synced: 2026-01-11T19:38:53.412Z (15 days ago)
• Topics: copy-on-write, immutability, java, persistent-data-structure
• Language: Java
• Size: 94.7 KB
• Stars: 11
• Watchers: 2
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.grillbaer/persistentds/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.grillbaer/persistentds)

[![Build](https://github.com/grillbaer/persistentds/workflows/Maven%20Build/badge.svg)](https://github.com/grillbaer/persistentds/actions?query=workflow%3A%22Maven+Build%22)

[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=coverage)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=bugs)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=code_smells)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=security_rating)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=grillbaer_persistentds&metric=alert_status)](https://sonarcloud.io/dashboard?id=grillbaer_persistentds)

# Persistent Data Structures

Immutable copy-on-write collections for lists, maps and sets in Java. Based on auto-balancing binary trees.

## Why use them?

Persistent collections simplify synchronization on shared data in multi-threaded applications because they guarantee immutability of already existing instances. They also make it easy to pass both old and new states to observers.

## What does 'persistent' mean here?

A persistent collection is always immutable. Modification methods return new instances of the collection without changing the existing instance. So you don't have to fiddle with error-prone and concurrency-restricting locking, because immutable data objects are thread-safe by nature.

For good performance, `peristentsds` shares common parts between modified and previous versions of the data structures. This keeps the copy overhead as low as possible.

For an in-detail definition see [Persistent Data Structure on WIKIPEDIA](https://en.wikipedia.org/wiki/Persistent_data_structure).

# How to use?

Syntax and behaviour of the persistent collections' interfaces are similar to `java.util.Collection`. However, all modification methods return modified versions of the collection and will not change the original one.

Simply start with the static factory `PersistentCollections` to create new instances of persistent data structures.

## Dependencies

Requires at least Java 8. Needs no other libraries.

For dependency declaration in various build systems or download of compiled jar see [Maven Central](https://search.maven.org/search?q=g:io.github.grillbaer%20AND%20a:persistentds).

You may use this Maven dependency with the latest version number:

```xml

  io.github.grillbaer

  persistentds

  x.x.x

```

## Examples

### List

```java

PersistentList list = PersistentCollections.persistentBinTreeList();

list = list.add(1).add(2).add(3);

PersistentList modifiedList = list.add(4);

System.out.println("Original list=" + list + " => modified list=" + modifiedList);

```

prints

    Original list={1,2,3} => modified list={1,2,3,4}

### Set

```java

PersistentSet set = PersistentCollections.persistentBinTreeSet();

// or PersistentCollections.persistentHashSet();

set = set.put("A").put("B").put("C");

PersistentSet modifiedSet = set.remove("B");

System.out.println("Original set=" + set + " => modified set=" + modifiedSet);

```

prints

    Original set={A,B,C} => modified set={A,C}

### Map

```java

PersistentMap map = PersistentCollections.persistentBinTreeMap();

map = map.put(1, "one").put(2, "two");

PersistentMap modifiedMap = map.put(3, "three");

System.out.println("Original map=" + map + " => modified map=" + modifiedMap);

```

prints

    Original map={[1 -> one],[2 -> two]} => modified map={[1 -> one],[2 -> two],[3 -> three]}