Add Json.Folder

[travisbrown]

This change introduces a new way to fold Json values that's a little more verbose than Json#fold but is faster and involves fewer allocations. It also seems to perform better than pattern matching on the (package-private) Json constructors in the benchmark included here:

FoldingBenchmark.withFold          thrpt   40   6073.949 ±  47.519  ops/s
FoldingBenchmark.withFoldWith      thrpt   40  11401.499 ±  89.627  ops/s
FoldingBenchmark.withPatternMatch  thrpt   40   7537.532 ± 219.453  ops/s

The allocation rates also look pretty good:

FoldingBenchmark.withFold:gc.alloc.rate.norm          thrpt  5  150744.081 ±  0.003  B/op
FoldingBenchmark.withFoldWith:gc.alloc.rate.norm      thrpt  5  117752.045 ±  0.008  B/op
FoldingBenchmark.withPatternMatch:gc.alloc.rate.norm  thrpt  5  132024.068 ±  0.005  B/op

The benchmark is intended to test idiomatic use of the three styles.

The primary motivation for this change is #654—I'm adding a couple new Json constructors and would prefer to avoid using pattern matching even internally, but I don't want to pay the extra cost of fold. I believe it's a reasonable addition even apart from #654, though.

I've also added asNull and withNull methods for the sake of consistency, since I've found myself wanting these a couple of times recently.

After this addition the recommendation would continue to be something like "start with fold or the asX or withX methods" but with a new "unless you know the performance cost is unacceptable, in which case there's foldWith".

[codecov-io]

Codecov Report

Merging #656 into master will increase coverage by 0.58%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #656      +/-   ##
==========================================
+ Coverage   83.68%   84.27%   +0.58%     
==========================================
  Files          70       70              
  Lines        2090     2111      +21     
  Branches      150      146       -4     
==========================================
+ Hits         1749     1779      +30     
+ Misses        341      332       -9

Impacted Files	Coverage Δ
.../core/shared/src/main/scala/io/circe/Printer.scala	96.15% <100%> (+0.2%)	⬆️
...les/core/shared/src/main/scala/io/circe/Json.scala	78.84% <100%> (+4.54%)	⬆️
.../core/shared/src/main/scala/io/circe/Decoder.scala	90.97% <0%> (+0.36%)	⬆️
...re/shared/src/main/scala/io/circe/JsonNumber.scala	96.84% <0%> (+1.05%)	⬆️
...d/src/main/scala/io/circe/NonEmptySeqDecoder.scala	100% <0%> (+9.09%)	⬆️
...rc/main/scala/io/circe/shapes/SizedInstances.scala	92.85% <0%> (+14.28%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8fed678...fe54709. Read the comment docs.

[vkostyukov]

One cool trick that I learned from Flavio Brasi is embedding this valed functions into their parent scope/class. Somewhat - merging interfaces.

new Json.Folder[Int] with ((Int, Json) => Int) {
   def apply(i: Int, j: Json): Int = i + j.foldWith(this)
   ...
}

This will allocate less.

[travisbrown]

👍, yeah, this is neat. It only has a tiny effect on allocations in this benchmark, but I think it looks a little nicer anyway, so let's consider it idiomatic.

[vkostyukov]

Has printing benchmark numbers changed as well?

[travisbrown]

@vkostyukov Yep—the change is pretty small with this PR, but I've got a follow-up coming with some bigger improvements (In particular I'm thinking of adding an optional setting for printers that lets them reuse string builders via thread locals, which has a pretty big impact).

[vkostyukov]

Nice @travisbrown! That sounds pretty cool - I'd probably be down to have that setting on by default in finch-circe.

[travisbrown]

@vkostyukov Yeah, I think for most users it would make sense, but I'm wary of cases where it could cause problems in application servers, so it'll probably be behind a printer.reuseStringBuilders option, at least for now.