User Guide

Table of Contents

Audience
Introduction
History
Project Setup
Supported Envs
Sets
Maps
ClojureScript

Audience

You want to learn more about how to use the ordered library from your app, library or script.

Introduction

ordered provides sets and maps that preserve insertion order.

History

2011 Alan Malloy publishes the first release ordered/ordered to Clojars. It is described as "Pure-clojure implementation of ruby’s ordered hash and set types".
2012 The library gets a new name and a new home. Alan’s ordered github repo gets duplicated to flatland/ordered. Flatland was created by Geni to host their open-source works. The first release of org.flatland/ordered is published to Clojars.
2018 Alan’s original GitHub repository (amalloy/ordered) is transferred to clj-commons/ordered for continued maintenance and care. We continue to publish releases to org.flatland/ordered maven coordinates. Our first release was v1.5.7. We are now the canonical repository for ordered.

Project Setup

Tools Deps

Include the following dependency in your deps.edn file:

org.flatland/ordered {:mvn/version "1.16.13"}

Leiningen

Include the following dependency in your project.clj file:

[org.flatland/ordered "1.16.13"]

Babashka

ordered is a babashka built-in library. There is no project setup.

Supported Envs

For usage from Clojure on the JVM we support:

JDK 11+ (Clojure 1.13 requires JDK 17+)
Clojure v1.10.3 and above

For ClojureScript, we support the current release of ClojureScript.

We test on macOS, Windows, and Linux.

Sets

(require '[flatland.ordered.set :as oset])

(oset/ordered-set 4 3 1 8 2)
=> #ordered/set (4 3 1 8 2)

(conj (oset/ordered-set 9 10) 1 2 3)
=> #ordered/set (9 10 1 2 3)

(into (oset/ordered-set) [7 6 1 5 6])
=> #ordered/set (7 6 1 5)

(disj (oset/ordered-set 8 1 7 2 6) 7)
=> #ordered/set (8 1 2 6)

;; Adding an element already in an ordered set does not change its
;; position in the order.
(conj (oset/ordered-set 4 3 1 8 2) 8)
=> #ordered/set (4 3 1 8 2)

;; Removing an element, then adding it back in, puts it at the end,
;; just as it would if it were never part of the set.
(-> (oset/ordered-set 4 3 1 8 2) (disj 8) (conj 8))
=> #ordered/set (4 3 1 2 8)

;; You can check if you are dealing with a flatland ordered set
(oset/ordered-set? (oset/ordered-set :a :b :c))
=> true

In Clojure, you can use transient on ordered sets:

(def t (transient (oset/ordered-set)))
(oset/ordered-set? t)
=> false
(def os (persistent! t))
(oset/ordered-set? os)
=> true

Maps

(require '[flatland.ordered.map :as omap])

(omap/ordered-map :b 2 :a 1 :d 4)
=> #ordered/map ([:b 2] [:a 1] [:d 4])

(assoc (omap/ordered-map :b 2 :a 1 :d 4) :c 3)
=> #ordered/map ([:b 2] [:a 1] [:d 4] [:c 3])

(into (omap/ordered-map) [[:c 3] [:a 1] [:d 4]])
=> #ordered/map ([:c 3] [:a 1] [:d 4])

(dissoc (omap/ordered-map :c 3 :a 1 :d 4) :a)
=> #ordered/map ([:c 3] [:d 4])

;; Adding a key already in an ordered map does not change its position
;; in the order.
(assoc (omap/ordered-map :b 2 :a 1 :d 4) :b 7)
=> #ordered/map ([:b 7] [:a 1] [:d 4])

;; Removing a key, then adding it back in, puts it at the end, just as
;; it would if it were never part of the map.
(-> (omap/ordered-map :b 2 :a 1 :d 4) (dissoc :b) (assoc :b 7))
=> #ordered/map ([:a 1] [:d 4] [:b 7])

;; You can check if you are dealing with a flatland ordered map
(omap/ordered-map? (omap/ordered-map :a 1))
=> true

In Clojure, you can use transient on ordered maps:

(def t (transient (omap/ordered-map)))
(omap/ordered-map? t)
=> false
(def om (persistent! t))
(omap/ordered-map? om)
=> true

ClojureScript

Both flatland.ordered.map and flatland.ordered.set work in ClojureScript. #ordered/map and #ordered/set literals are supported in ClojureScript source at compile time.

To read these literals at runtime, you must register the tags:

(require '[cljs.reader :as reader]
         '[flatland.ordered.map :as omap]
         '[flatland.ordered.set :as oset])

;; we get reader errors if tags are not registered for runtime usage:
(reader/read-string "#ordered/map ([:b 1] [:a 2])")
=> ... No reader function for tag ordered/map.
(reader/read-string "#ordered/set (4 3 2)")
=> ... No reader function for tag ordered/set.

;; but if we register our tags first...
(reader/register-tag-parser! 'ordered/map omap/ordered-map)
(reader/register-tag-parser! 'ordered/set oset/into-ordered-set)

;; ... then we are fine:
(reader/read-string "#ordered/map ([:b 1] [:a 2])")
=> #ordered/map ([:b 1] [:a 2])
(reader/read-string "#ordered/set (4 3 2)")
=> #ordered/set (4 3 2)

Things are JVM Clojure only:

transient support
flatland.ordered.common/compact

On ClojureScript, disj on an ordered-set is O(n) rather than O(1).

Developer Guide❯

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field