Skip to content
Newer
Older
100644 85 lines (65 sloc) 3.69 KB
b6fe0d8 @stuarthalloway initial commit
stuarthalloway authored
1 # algo.generic
2
bcbacd0 @khinsen README filled with useful content
khinsen authored
3 Generic versions of commonly used functions, implemented as multimethods
4 that can be implemented for any data type.
5
6 ## Usage
7
8 Each submodule of clojure.algo.generic defines a set of related
9 multimethods that have the same names as their type-specific
10 counterparts in clojure.core. Implementations for standard Clojure
11 data types are provided and behave identically to the clojure.core
12 versions.
13
14 ### Arities
15
16 Arithmetic and comparison functions are defined for the same arities
17 that the corresponding clojure.core functions support. Arities higher
18 than 2 are reduced to unary and binary calls. To provide a multimethod
19 implementation for binary calls with a given pair of types, use
20 `[type1 type2]` as the dispatch value. For a unary call, the dispatch
21 value is `type` as usual. Note that `[type1 type2]` is different from
22 `[type2 type1]` (in most cases you will want to provide both) and that
23 `[type type]` (binary operation with both arguments of the same type)
24 is different from `type` (unary operation).
25
26 ### Root type
27
28 This section applies only to binary operations dispatching on type
29 pairs, and only for types that are *not* Java classes. Types
30 created by `deftype` and `defrecord` are Java classes, meaning that
31 most Clojure programmers can go on with the next section.
32
33 One difficulty with binary operations is that there is no predefined
34 way to provide a default implementation. For single dispatch there is
35 `:default`, but there is nothing equivalent to `[:default :default]`.
36 The algo.generic library therefore defines a *root type*, accessible
37 as `clojure.algo.generic/root-type`, which is used in the default
38 implementations of binary operations. To integrate your own type into
39 this system, you must add the clause `(derive my-type
40 clojure.algo.generic/root-type)` after your type definition. This is
41 not required for Java classes because `java.lang.Object` is
42 already derived from `root-type`.
43
44 ### Submodules
45
46 * **algo.generic.arithmetic** provides generic `+` `-` `*` `/` for all
47 the arities that the corresponding clojure.core functions support.
48 The minimal implementations required for full arithmetic on a given
49 type is binary `+` and `*` and unary `-` and `/`. You may wish to
50 provide explicit implementations for binary `-` and `/` for
51 efficiency, otherwise the default implementations are `(- a b) => (+ a (- b))`
52 and `(/ a b) => (* a (/ b))`.
53
54 * **algo.generic.collection** provides generic versions of `assoc`,
55 `dissoc`, `get`, `conj`, `empty`, `into`, and `seq`. `into` has a
56 default implementation in terms of `conj` and `seq`, but you may
57 wish to provide a more efficient one for your types.
58
59 * **algo.generic.comparison** provides the comparison and test
60 functions `=`, `not=`, `<`, `>`, `<=`, `>=`, `zero?`, `pos?`,
61 `neg?`, `min`, and ` max`. `not=`, `min`, and `max` cannot be
62 redefined, they are standard functions that are implemented in
63 terms of the generic functions of the module. A minimal
64 implementation of the binary comparison functions consists of
65 `=` and `>`. Default implementations for `<`, `<=`, and `>=`
66 call `>`, but more efficient implementations can be provided.
67
68 * **algo.generic.math-functions** provides generic versions of the
69 common math functions from `java.lang.Math`, plus `sgn`, `sqr`, and
70 `conjugate`.
71
b6fe0d8 @stuarthalloway initial commit
stuarthalloway authored
72
73 ## License
74
75 Copyright (c) Rich Hickey and contributors. All rights reserved.
76
77 The use and distribution terms for this software are covered by the
78 Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
79 which can be found in the file epl.html at the root of this distribution.
80 By using this software in any fashion, you are agreeing to be bound by
81 the terms of this license.
82 You must not remove this notice, or any other, from this software.
83
84
Something went wrong with that request. Please try again.