@@ -1,113 +1,119 @@
1−# 0.6 series
1+0.7.0.0
22
3−Much improved documentation.
3+ * The performance of encoding to and decoding of bytestrings
4+ have both improved by up to 2x, while also using less
5+ memory.
46
5−Angle brackets are now escaped in JSON strings, to help avoid XSS
6−attacks.
7+ * New dependency: the scientific package lets us parse
8+ floating point numbers more quickly and accurately.
79
8−Fixed up handling of nullary constructors when using generic encoding.
10+ * eitherDecode, decodeStrictWith: fixed bugs.
911
10−Added ToJSON/FromJSON instances for:
12+ * Added FromJSON and ToJSON instances for Tree and Scientific.
1113
12−* The `Fixed` class
14+ * Fixed the ToJSON instances for UTCTime and ZonedTime.
1315
14−* ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
16+0.6 series
1517
16−Added accessor functions for inspecting `Value`s.
18+ * Much improved documentation.
1719
18−Added `eitherDecode` function that returns an error message if
19−decoding fails.
20+ * Angle brackets are now escaped in JSON strings, to help avoid XSS
21+ attacks.
2022
21−# 0.5 to 0.6
23+ * Fixed up handling of nullary constructors when using generic
24+ encoding.
2225
23−This release introduces a slightly obscure, but
24−backwards-incompatible, change.
26+ * Added ToJSON/FromJSON instances for:
2527
26−In the generic APIs of versions 0.4 and 0.5, fields whose names began
27−with a "`_`" character would have this character removed. This no
28−longer occurs, as [it was both buggy and
29−surprising](https://github.com/bos/aeson/issues/53).
28+ * The Fixed class
29+ * ISO-8601 dates: UTCTime, ZonedTime, and TimeZone
3030
31−Also:
31+ * Added accessor functions for inspecting Values.
3232
33−* Fixed [a bug in generic decoding of nullary constructors](https://github.com/bos/aeson/issues/62)
33+ * Added eitherDecode function that returns an error message if
34+ decoding fails.
3435
35−# 0.4 to 0.5
36+0.5 to 0.6
3637
37−When used with the UTF-8 encoding performance improvements introduced
38−in version 0.11.1.12 of the text package, this release improves
39−aeson's JSON encoding performance by 33% relative to aeson 0.4.
38+ * This release introduces a slightly obscure, but
39+ backwards-incompatible, change.
4040
41−As part of achieving this improvement, an API change was necessary.
42−The `fromValue` function in the `Data.Aeson.Encode` module now uses
43−the text package's `Builder` type instead of the blaze-builder
44−package's `Builder` type.
41+ In the generic APIs of versions 0.4 and 0.5, fields whose
42+ names began with a "_" character would have this character
43+ removed. This no longer occurs, as it was both buggy and
44+ surprising (https://github.com/bos/aeson/issues/53).
4545
46−# 0.3 to 0.4
46+ * Fixed a bug in generic decoding of nullary constructors
47+ (https://github.com/bos/aeson/issues/62).
4748
48−## Ease of use
49+0.4 to 0.5
4950
50−The new [`decode`
51−function](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson.html#v:decode)
52−complements the longstanding `encode` function, and makes the API
53−simpler.
51+ * When used with the UTF-8 encoding performance improvements
52+ introduced in version 0.11.1.12 of the text package, this
53+ release improves aeson's JSON encoding performance by 33%
54+ relative to aeson 0.4.
5455
55−[New examples](https://github.com/bos/aeson/tree/master/examples) make
56−it easier to learn to use the package.
56+ As part of achieving this improvement, an API change was
57+ necessary. The fromValue function in the
58+ Data.Aeson.Encode module now uses the text package's
59+ Builder type instead of the blaze-builder package's
60+ Builder type.
5761
62+0.3 to 0.4
5863
59−## Generics support
64+ * The new decode function complements the longstanding
65+ encode function, and makes the API simpler.
6066
61−aeson's support for data-type generic programming makes it possible to
62−use JSON encodings of most data types without writing any boilerplate
63−instances.
67+ * New examples make it easier to learn to use the package
68+ (https://github.com/bos/aeson/tree/master/examples).
6469
65−Thanks to Bas Van Dijk, aeson now supports the two major schemes for
66−doing datatype-generic programming:
70+ * Generics support
6771
68−* the modern mechanism, [built into GHC
69− itself](http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
72+ aeson's support for data-type generic programming makes it
73+ possible to use JSON encodings of most data types without
74+ writing any boilerplate instances.
7075
71−* the older mechanism, based on SYB (aka "scrap your boilerplate")
76+ Thanks to Bas Van Dijk, aeson now supports the two major
77+ schemes for doing datatype-generic programming:
7278
73−The modern GHC-based generic mechanism is fast and terse: in fact, its
74−performance is generally comparable in performance to hand-written and
75−TH-derived `ToJSON` and `FromJSON` instances. To see how to use GHC
76−generics, refer to
77−[`examples/Generic.hs`](https://github.com/bos/aeson/blob/master/examples/Generic.hs).
79+ * the modern mechanism, built into GHC itself
80+ (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
7881
79−The SYB-based generics support lives in
80−[Data.Aeson.Generic](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson-Generic.html),
81−and is provided mainly for users of GHC older than 7.2. SYB is far
82−slower (by about 10x) than the more modern generic mechanism. To see
83−how to use SYB generics, refer to
84−[`examples/GenericSYB.hs`](https://github.com/bos/aeson/blob/master/examples/GenericSYB.hs).
82+ * the older mechanism, based on SYB (aka "scrap your
83+ boilerplate")
8584
85+ The modern GHC-based generic mechanism is fast and terse: in
86+ fact, its performance is generally comparable in performance
87+ to hand-written and TH-derived ToJSON and FromJSON
88+ instances. To see how to use GHC generics, refer to
89+ examples/Generic.hs.
8690
87−## Improved performance
91+ The SYB-based generics support lives in Data.Aeson.Generic
92+ and is provided mainly for users of GHC older than 7.2. SYB
93+ is far slower (by about 10x) than the more modern generic
94+ mechanism. To see how to use SYB generics, refer to
95+ examples/GenericSYB.hs.
8896
89−* We switched the intermediate representation of JSON objects from
90− `Data.Map` to
91− [`Data.HashMap`](http://hackage.haskell.org/package/unordered-containers),
92− which has improved type conversion performance.
97+ * We switched the intermediate representation of JSON objects
98+ from Data.Map to Data.HashMap which has improved type
99+ conversion performance.
93100
94−* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and
95− 70% faster than in 0.3.
101+ * Instances of ToJSON and FromJSON for tuples are between 45%
102+ and 70% faster than in 0.3.
96103
104+ * Evaluation control
97105
98−## Evaluation control
106+ This version of aeson makes explicit the decoupling between
107+ *identifying* an element of a JSON document and *converting*
108+ it to Haskell. See the Data.Aeson.Parser documentation for
109+ details.
99110
100−This version of aeson makes explicit the decoupling between
101−*identifying* an element of a JSON document and *converting* it to
102−Haskell. See the
103−[`Data.Aeson.Parser`](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson-Parser.html)
104−documentation for details.
111+ The normal aeson decode function performs identification
112+ strictly, but defers conversion until needed. This can
113+ result in improved performance (e.g. if the results of some
114+ conversions are never needed), but at a cost in increased
115+ memory consumption.
105116
106−The normal aeson `decode` function performs identification strictly,
107−but defers conversion until needed. This can result in improved
108−performance (e.g. if the results of some conversions are never
109−needed), but at a cost in increased memory consumption.
110−
111−The new `decode'` function performs identification and conversion
112−immediately. This incurs an up-front cost in CPU cycles, but reduces
113−reduce memory consumption.
117+ The new decode' function performs identification and
118+ conversion immediately. This incurs an up-front cost in CPU
119+ cycles, but reduces reduce memory consumption.