@@ -1,90 +1,95 @@
1−0.10.0.0
1+# 0.10.0.0
22
3−SPEEDUPS:
3+## Performance improvements
44
5−* Direct encoding via toEncoding is over 2x faster than under 0.9 and
6− earlier. (You must write or code-gen a toEncoding implementation to
7− unlock this speedup. See below for details.)
5+* Direct encoding via the new `toEncoding` method is over 2x faster
6+ than `toJSON`. (You must write or code-gen a `toEncoding`
7+ implementation to unlock this speedup. See below for details.)
88
99* Improved string decoding gives a 12% speed win in parsing
1010 string-heavy JSON payloads (very common).
1111
1212* Encoding and decoding of time-related types are 10x faster (!!) as a
13− result of bypassing Data.Time.Format and arbitrary-precision Integers.
13+ result of bypassing `Data.Time.Format` and the arbitrary-precision
14+ `Integer` type.
1415
15−* When using toEncoding, [Char] can be encoded without a conversion to
16− Text. This is fast and efficient.
16+* When using `toEncoding`, `[Char]` can be encoded without a conversion to
17+ `Text`. This is fast and efficient.
1718
18−* Parsing into an Object is now 5% faster and more
19+* Parsing into an `Object` is now 5% faster and more
1920 allocation-efficient.
2021
21−MANY API CHANGES, READ CAREFULLY.
22+## MANY API CHANGES, READ CAREFULLY
2223
2324With the exception of long-deprecated code, the API changes below
24−should be upwards compatible from older versions of aeson. If you run
25+should be upwards compatible from older versions of `aeson`. If you run
2526into upgrade problems, please file an issue with details.
2627
27−* The ToJSON class has a new method, toEncoding, that allows direct
28− encoding from a Haskell value to a lazy bytestring without
28+* The `ToJSON` class has a new method, `toEncoding`, that allows
29+ direct encoding from a Haskell value to a lazy bytestring without
2930 construction of an intermediate Value.
3031
3132 The performance benefits of direct encoding are significant: more
32− than 3x faster than before, with less than 1/3 the memory usage.
33+ than 2x faster than before, with less than 1/3 the memory usage.
3334
3435 To preserve API compatibility across upgrades from older versions of
35− this library, toEncoding is implemented using toJSON. You will not
36− see a performance improvement unless you write an implementation of
37− toEncoding.
36+ this library, the default implementation of `toEncoding` uses
37+ `toJSON`. You will *not* see any performance improvement unless you
38+ write an implementation of toEncoding.
39+
40+ (Behind the scenes, the `encode` function uses `toEncoding` now, so
41+ if you implement `toEncoding` for your types, you should see a
42+ speedup immediately.)
3843
3944 If you use Template Haskell or GHC Generics to auto-generate your
40− ToJSON instances, you'll benefit from fast toEncoding
45+ `ToJSON` instances, you'll benefit from fast toEncoding
4146 implementations for free!
4247
43−* When converting from a Value to a target Haskell type, FromJSON
48+* When converting from a `Value` to a target Haskell type, `FromJSON`
4449 instances now provide much better error messages, including a
4550 complete JSON path from the root of the object to the offending
4651 element. This greatly eases debugging.
4752
48−* If you used to use the camelTo function to rename fields when using
49− TH or generics, the new camelTo2 function is smarter. For example,
50− camelTo will rename `CamelAPICase` to `camelapi_case`, while
51− camelTo2 will map it to `camel_api_case`.
53+* If you used to use the `camelTo` function to rename fields when
54+ using TH or generics, the new `camelTo2` function is smarter. For
55+ example, `camelTo` will rename `CamelAPICase` to `camelapi_case`,
56+ while `camelTo2` will map it to `camel_api_case`.
5257
53−* New ToJSON and FromJSON instances for the following time-related
54− types: Day, LocalTime.
58+* New `ToJSON` and `FromJSON` instances for the following time-related
59+ types: `Day`, `LocalTime`.
5560
56−* The Result type is now an instance of Foldable and Traversable.
61+* The `Result` type is now an instance of `Foldable` and `Traversable`.
5762
58−* The Data.Aeson.Generic module has been removed. It was deprecated in
63+* The `Data.Aeson.Generic` module has been removed. It was deprecated in
5964 late 2013.
6065
6166* GHC 7.2 and older are no longer supported.
6267
63−* The instance of Monad for the Result type lacked an implementation
64− of fail. This has been corrected.
68+* The instance of `Monad` for the `Result` type lacked an implementation
69+ of fail (oops). This has been corrected.
6570
6671
6772
68−0.9.0.1
73+# 0.9.0.1
6974
70−* A stray export of encodeToBuilder got away!
75+* A stray export of `encodeToBuilder` got away!
7176
72−0.9.0.0
77+# 0.9.0.0
7378
74−* The json and json' parsers are now synonyms for value and value', in
75− conformance with the looser semantics of RFC 7159.
79+* The `json` and `json'` parsers are now synonyms for `value` and
80+ `value'`, in conformance with the looser semantics of RFC 7159.
7681
77−* Renamed encodeToByteStringBuilder to the more compact
78− encodeToBuilder.
82+* Renamed `encodeToByteStringBuilder` to the more compact
83+ `encodeToBuilder`.
7984
80−0.8.1.1
85+# 0.8.1.1
8186
82−* The dependency on the unordered-containers package was too lax, and
83− has been corrected.
87+* The dependency on the `unordered-containers` package was too lax,
88+ and has been corrected.
8489
85−0.8.1.0
90+# 0.8.1.0
8691
87−* Encoding a Scientific value with a huge exponent is now handled
92+* Encoding a `Scientific` value with a huge exponent is now handled
8893 efficiently. (This would previously allocate a huge
8994 arbitrary-precision integer, potentially leading to a denial of
9095 service.)
@@ -94,55 +99,56 @@ into upgrade problems, please file an issue with details.
9499 megabyte of consecutive backslashes, the new implementation is 27x
95100 faster and uses 42x less memory.
96101
97−* The ToJSON instance for UTCTime is rendered with higher (picosecond)
98− resolution.
102+* The `ToJSON` instance for `UTCTime` is rendered with higher
103+ (picosecond) resolution.
99104
100105* The value parser now correctly handles leading whitespace.
101106
102−* New instances of ToJSON and FromJSON for Data.Sequence and
103− Data.Functor.Identity. The Value type now has a Read instance.
107+* New instances of `ToJSON` and `FromJSON` for `Data.Sequence` and
108+ `Data.Functor.Identity`. The `Value` type now has a `Read` instance.
104109
105−* ZonedTime parser ordering now favours the standard JSON format,
110+* `ZonedTime` parser ordering now favours the standard `JSON` format,
106111 increasing efficiency in the common case.
107112
108−* Encoding to a Text.Builder now escapes '<' and '>' characters, to
109− reduce XSS risk.
113+* Encoding to a `Text.Builder` now escapes `'<'` and `'>'` characters,
114+ to reduce XSS risk.
110115
111−0.8.0.2
116+# 0.8.0.2
112117
113−* Fix ToJSON instance for 15-tuples (see #223).
118+* Fix `ToJSON` instance for 15-tuples (see #223).
114119
115−0.8.0.1
120+# 0.8.0.1
116121
117−* Support time-1.5.
122+* Support `time-1.5`.
118123
119−0.8.0.0
124+# 0.8.0.0
120125
121−* Add ToJSON and FromJSON instances for tuples of up to 15 elements.
126+* Add `ToJSON` and `FromJSON` instances for tuples of up to 15
127+ elements.
122128
123−0.7.1.0
129+# 0.7.1.0
124130
125131* Major compiler and library compatibility changes: we have dropped
126− support for GHC older than 7.4, text older than 1.1, and bytestring
127− older than 0.10.4.0. Supporting the older versions had become
128− increasingly difficult, to the point where it was no longer worth
129− it.
132+ support for GHC older than 7.4, `text` older than 1.1, and
133+ `bytestring` older than 0.10.4.0. Supporting the older versions had
134+ become increasingly difficult, to the point where it was no longer
135+ worth it.
130136
131−0.7.0.0
137+# 0.7.0.0
132138
133139* The performance of encoding to and decoding of bytestrings have both
134140 improved by up to 2x, while also using less memory.
135141
136−* New dependency: the scientific package lets us parse floating point
142+* New dependency: the `scientific` package lets us parse floating point
137143 numbers more quickly and accurately.
138144
139−* eitherDecode, decodeStrictWith: fixed bugs.
145+* `eitherDecode`, `decodeStrictWith`: fixed bugs.
140146
141−* Added FromJSON and ToJSON instances for Tree and Scientific.
147+* Added `FromJSON` and `ToJSON` instances for `Tree` and `Scientific`.
142148
143−* Fixed the ToJSON instances for UTCTime and ZonedTime.
149+* Fixed the `ToJSON` instances for `UTCTime` and `ZonedTime`.
144150
145−0.6 series
151+# 0.6 series
146152
147153* Much improved documentation.
148154
@@ -152,44 +158,44 @@ into upgrade problems, please file an issue with details.
152158* Fixed up handling of nullary constructors when using generic
153159 encoding.
154160
155−* Added ToJSON/FromJSON instances for:
161+* Added `ToJSON`/`FromJSON` instances for:
156162
157− * The Fixed class
158− * ISO-8601 dates: UTCTime, ZonedTime, and TimeZone
163+ * The `Fixed` class
164+ * ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
159165
160166* Added accessor functions for inspecting Values.
161167
162168* Added eitherDecode function that returns an error message if
163169 decoding fails.
164170
165−0.5 to 0.6
171+# 0.5 to 0.6
166172
167173* This release introduces a slightly obscure, but
168174 backwards-incompatible, change.
169175
170176 In the generic APIs of versions 0.4 and 0.5, fields whose names
171− began with a "_" character would have this character removed. This
177+ began with a `"_"` character would have this character removed. This
172178 no longer occurs, as it was both buggy and surprising
173179 (https://github.com/bos/aeson/issues/53).
174180
175181* Fixed a bug in generic decoding of nullary constructors
176182 (https://github.com/bos/aeson/issues/62).
177183
178−0.4 to 0.5
184+# 0.4 to 0.5
179185
180186* When used with the UTF-8 encoding performance improvements
181− introduced in version 0.11.1.12 of the text package, this release
182− improves aeson's JSON encoding performance by 33% relative to aeson
183− 0.4.
187+ introduced in version 0.11.1.12 of the `text` package, this release
188+ improves `aeson`'s JSON encoding performance by 33% relative to
189+ `aeson` 0.4.
184190
185191 As part of achieving this improvement, an API change was necessary.
186− The fromValue function in the Data.Aeson.Encode module now uses the
187− text package's Builder type instead of the blaze-builder package's
188− Builder type.
192+ The `fromValue` function in the `Data.Aeson.Encode` module now uses
193+ the `text` package's `Builder` type instead of the `blaze-builder`
194+ package's `Builder` type.
189195
190−0.3 to 0.4
196+# 0.3 to 0.4
191197
192−* The new decode function complements the longstanding encode
198+* The new `decode` function complements the longstanding `encode`
193199 function, and makes the API simpler.
194200
195201* New examples make it easier to learn to use the package
@@ -197,12 +203,12 @@ into upgrade problems, please file an issue with details.
197203
198204* Generics support
199205
200− aeson's support for data-type generic programming makes it possible
201− to use JSON encodings of most data types without writing any
202− boilerplate instances.
206+ `aeson`'s support for data-type generic programming makes it
207+ possible to use JSON encodings of most data types without writing
208+ any boilerplate instances.
203209
204− Thanks to Bas Van Dijk, aeson now supports the two major schemes for
205− doing datatype-generic programming:
210+ Thanks to Bas Van Dijk, `aeson` now supports the two major schemes
211+ for doing datatype-generic programming:
206212
207213 * the modern mechanism, built into GHC itself
208214 (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
@@ -212,32 +218,32 @@ into upgrade problems, please file an issue with details.
212218
213219 The modern GHC-based generic mechanism is fast and terse: in fact,
214220 its performance is generally comparable in performance to
215− hand-written and TH-derived ToJSON and FromJSON instances. To see
216− how to use GHC generics, refer to examples/Generic.hs.
221+ hand-written and TH-derived `ToJSON` and `FromJSON` instances. To
222+ see how to use GHC generics, refer to `examples/Generic.hs`.
217223
218− The SYB-based generics support lives in Data.Aeson.Generic and is
224+ The SYB-based generics support lives in `Data.Aeson.Generic` and is
219225 provided mainly for users of GHC older than 7.2. SYB is far slower
220226 (by about 10x) than the more modern generic mechanism. To see how
221− to use SYB generics, refer to examples/GenericSYB.hs.
227+ to use SYB generics, refer to `examples/GenericSYB.hs`.
222228
223229* We switched the intermediate representation of JSON objects from
224− Data.Map to Data.HashMap which has improved type conversion
230+ `Data.Map` to `Data.HashMap` which has improved type conversion
225231 performance.
226232
227−* Instances of ToJSON and FromJSON for tuples are between 45% and 70%
233+* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and 70%
228234 faster than in 0.3.
229235
230236* Evaluation control
231237
232238 This version of aeson makes explicit the decoupling between
233239 *identifying* an element of a JSON document and *converting* it to
234− Haskell. See the Data.Aeson.Parser documentation for details.
240+ Haskell. See the `Data.Aeson.Parser` documentation for details.
235241
236− The normal aeson decode function performs identification strictly,
237− but defers conversion until needed. This can result in improved
238− performance (e.g. if the results of some conversions are never
239− needed), but at a cost in increased memory consumption.
242+ The normal `aeson` `decode` function performs identification
243+ strictly, but defers conversion until needed. This can result in
244+ improved performance (e.g. if the results of some conversions are
245+ never needed), but at a cost in increased memory consumption.
240246
241− The new decode' function performs identification and conversion
247+ The new `decode'` function performs identification and conversion
242248 immediately. This incurs an up-front cost in CPU cycles, but
243249 reduces reduce memory consumption.