Awesome

Finger trees and miscellaneous functions for ClojureScript data structures.

Overview

Finger trees are based on https://github.com/wagjo/ftree which is based on https://github.com/clojure/data.finger-tree

Resources on finger trees:

• https://github.com/Chouser/talk-finger-tree
• http://www.soi.city.ac.uk/~ross/papers/FingerTree.html
• http://blip.tv/clojure/chris-houser-finger-trees-custom-persistent-collections-4632874

Usage

Add the following dependency to your project.clj file:

[com.wagjo/data-cljs "0.1.0-SNAPSHOT"]

Introduction

Most of functions working with data structures use polymorphism. This is slow (as of early 2013) in ClojureScript. Faster variants are implemented here in separate namespaces. Faster variants does not have plymorphism nor multiple arities.

Nearly every data manipulation function works with seqs. In ClojureScript, this is very slow, e.g. for use in games (see Chris Granger's talk). Specialized functions (e.g. for arrays and vectors) are placed directly in clojure.core namespace and are given a strange names (alength, subvec). This library provides separate namespace for each data structure.

Functions are provided for following data structures:

• Javascript Array
• Javascript String
• PersistentVector (for now, most functions there are very slow)
• Finger Tree
• miscellaneous functions for characters

Notable functionalities include:

• fast eager variants of map and map-indexed
• fast variants of reduce and reduce-kv
• reduce-reverse and reduce-kv-reverse
• finger trees supporting standard clojure fns (conj, seq, count, nth, assoc, reduce, ...)

This library provides a fast finger tree implementation. Until https://github.com/michalmarczyk/flexvec gets ported to CLJS, finger trees are good candidate for data structure which provides fast insert/remove.

Note that most of functions for persistent vector are very slow. This too will be fixed when flexvec gets ported.

List of functions

Following functions are provided for each data structure. Moreover, some data structures provide additional functions, e.g. array provides additional mutating functions.

Creation

• empty [] - clojure.core/empty (without argument)

Access

• empty? [o] - clojure.core/empty?
• count [o] - clojure.core/count
• nth [o index] - clojure.core/nth without not-found
• nth* [o index not-found] - clojure.core/nth with not-found
• nth-unchecked [o index] - clojure.core/nth without boundary check
• peekl [o] - like clojure.core/peek but always from left
• peekr [o] - like clojure.core/peek but always from right
• peek [o] - clojure.core/peek
• peekl-unchecked [o] - like peekl but without boundary check
• peekr-unchecked [o] - like peekr but without boundary check
• peek-unchecked [o] - like peek but without boundary check

Modify

• slice [o start end] - like clojure.core/subvec
• slice-from [o start] - like slice, but until the end of o
• slice-to [o end] - like slice, but from the beginning of o
• split-at [o index] - clojure.core/split-at
• cat [o o2] - eager variant of clojure.core/concat
• popl [o] - like clojure.core/pop, but always from left
• popr [o] - like clojure.core/pop, but always from right
• pop [o] - clojure.core/pop
• popl-unchecked [o] - like popl, but without boundary check
• popr-unchecked [o] - like popr, but without boundary check
• pop-unchecked [o] - like pop, but without boundary check
• assoc [o index val] - clojure.core/assoc
• update [o index f] - like clojure.core/update-in, one level only
• conjl [o val] - like clojure.core/conj, but always from left
• conjr [o val] - like clojure.core/conj, but always from right
• conj [o val] - clojure.core/conj
• conjl-arr [o val-arr] - like conjl, but with array of vals
• conjr-arr [o val-arr] - like conjr, but with array of vals
• conj-arr [o val-arr] - like conj, but with array of vals
• splice [o index n val] - fast remove and insert in one go
• splice-arr [o index n val-arr] - fast remove and insert in one go
• insert-before [o index val] - insert one item inside coll
• insert-before-arr [o index val] - insert array of items inside coll
• remove-at [o index] - remove one item from index pos
• remove-n [o index n] - remove n items starting at index pos
• rip [o index] - rips coll and returns [pre-coll item-at suf-coll]
• sew [pre-coll item-arr suf-coll] - opposite of rip, but with arr
• triml [o n] - trims n items from left
• trimr [o n] - trims n items from right
• trim [o nl nr] - trims nl items from left and nr items from right

Use

• mape [f o] - eager version of clojure.core/map
• mape-indexed [f o] - eager version of clojure.core/map-indexed
• reduce [f init o] - faster version of clojure.core/reduce
• reduce2 [f o] - faster version of clojure.core/reduce
• reduce-reverse [f init o] - like reduce but in reverse order
• reduce2-reverse [f o] - like reduce but in reverse order
• reduce-kv [f init o] - faster version of clojure.core/reduce-kv
• reduce2-kv [f o] - faster version of clojure.core/reduce-kv
• reduce-kv-reverse [f init o] - like reduce-kv but in reverse order
• reduce2-kv-reverse [f o] - like reduce-kv but in reverse order
• index-of [o val] - search for val inside o
• index-of-from [o val index-from] - index-of, starting at index-from

License

Copyright (C) 2011, 2012, 2013 Rich Hickey, Chris Houser, Jozef Wagner.

The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) which can be found in the file epl-v10.html at the root of this distribution.

By using this software in any fashion, you are agreeing to be bound by the terms of this license.

You must not remove this notice, or any other, from this software.