Skip to content

Commit 4833f62

Browse files
matt-lethargicmatt-lethargic
committed
2 parents ec24eb8 + 57d015a commit 4833f62

5 files changed

Lines changed: 156 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 152 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,154 @@
1-
[![Build and Test](https://github.com/GeoJSON-Net/GeoJSON.Text/actions/workflows/ci-build.yml/badge.svg?branch=main)](https://github.com/GeoJSON-Net/GeoJSON.Text/actions/workflows/ci-build.yml) [![codecov](https://codecov.io/gh/GeoJSON-Net/GeoJSON.Text/branch/main/graph/badge.svg?token=SE9XY1T8XO)](https://codecov.io/gh/GeoJSON-Net/GeoJSON.Text)
1+
[![Build and Test](https://github.com/GeoJSON-Net/GeoJSON.Text/actions/workflows/ci-build.yml/badge.svg?branch=main)](https://github.com/GeoJSON-Net/GeoJSON.Text/actions/workflows/ci-build.yml) [![codecov](https://codecov.io/gh/GeoJSON-Net/GeoJSON.Text/branch/main/graph/badge.svg?token=SE9XY1T8XO)](https://codecov.io/gh/GeoJSON-Net/GeoJSON.Text)
22

3+
# GeoJSON.Text
4+
GeoJSON.Text is a .NET library for the [RFC 7946 The GeoJSON Format](https://tools.ietf.org/html/rfc7946) and it uses and provides [System.Text.Json](https://docs.microsoft.com/en-us/dotnet/api/system.text.json?view=net-6.0) converters for serialization and deserialization of GeoJSON data.
35

4-
# GetJson.Text
5-
.Net library for GeoJSON types & corresponding System.TExt.Json (de)serializers
6+
## Installation & Usage
7+
8+
[GeoJSON.Text NuGet package](https://www.nuget.org/packages/GeoJSON.Text/):
9+
10+
`Install-Package GeoJSON.Text`
11+
12+
### Serialization
13+
14+
```csharp
15+
Position position = new Position(51.899523, -2.124156);
16+
Point point = new Point(position);
17+
18+
string json = JsonSerializer.Serialize(point);
19+
```
20+
21+
### Deserialization
22+
23+
```csharp
24+
string json = "{\"coordinates\":[-2.124156,51.899523],\"type\":\"Point\"}";
25+
26+
Point point = JsonSerializer.Deserialize<Point>(json);
27+
```
28+
29+
See the [Tests](https://github.com/GeoJSON-Net/GeoJSON.Text/tree/master/src/GeoJSON.Text.Test.Unit) for more examples.
30+
31+
## Special considerations for Newtonsoft.Json
32+
33+
GeoJSON.Text is made to support System.Text.Json, and does not support serializing or deserializing GeoJSON models using Newtonsoft.Json.
34+
35+
If Newtonsoft.Json support is needed, please use [GeoJSON.Net](https://github.com/GeoJSON-Net/GeoJSON.Net).
36+
37+
## GeoJSON.Text vs. GeoJSON.NET
38+
39+
This project uses the System.Text.Json serializers, which has become the default and recommended serializers in .NET Core 3.1+.
40+
41+
Benchmarks shows that serializing and deserializing using System.Text.Json is approximately 100% quicker then Newtonsoft.Json and result in 75% less memory allocation when deserializing and 50% less memory allocation when serializing.
42+
43+
<details>
44+
<summary>Benchmarks</summary>
45+
46+
### Serializing comparison
47+
48+
``` ini
49+
50+
BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19042.1415 (20H2/October2020Update)
51+
Intel Core i7-9850H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
52+
.NET SDK=6.0.100
53+
[Host] : .NET 6.0.0 (6.0.21.52210), X64 RyuJIT
54+
Job-WNYOAA : .NET 6.0.0 (6.0.21.52210), X64 RyuJIT
55+
Job-AAKTUU : .NET 5.0.13 (5.0.1321.56516), X64 RyuJIT
56+
Job-AEYDDU : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT
57+
58+
IterationCount=15 LaunchCount=2 WarmupCount=10
59+
60+
```
61+
| Method | Job | Runtime | Toolchain | N | Mean | Error | StdDev | Ratio | RatioSD | Rank | Gen 0 | Gen 1 | Gen 2 | Allocated |
62+
|------------------------ |----------- |-------------- |------------- |------- |---------:|---------:|---------:|------:|--------:|-----:|-----------:|----------:|---------:|----------:|
63+
| SerializeSystemTextJson | Job-WNYOAA | .NET 6.0 | net60 | 100000 | 167.3 ms | 7.28 ms | 10.44 ms | 1.00 | 0.00 | I | 2000.0000 | - | - | 35 MB |
64+
| | | | | | | | | | | | | | | |
65+
| SerializeSystemTextJson | Job-AAKTUU | .NET 5.0 | net50 | 100000 | 188.0 ms | 5.44 ms | 7.80 ms | ? | ? | I | 2000.0000 | - | - | 65 MB |
66+
| | | | | | | | | | | | | | | |
67+
| SerializeSystemTextJson | Job-AEYDDU | .NET Core 3.1 | netcoreapp31 | 100000 | 235.6 ms | 7.85 ms | 11.26 ms | ? | ? | I | 2333.3333 | 333.3333 | 333.3333 | 65 MB |
68+
| | | | | | | | | | | | | | | |
69+
| SerializeNewtonsoft | Job-WNYOAA | .NET 6.0 | net60 | 100000 | 352.3 ms | 17.33 ms | 24.86 ms | 2.11 | 0.16 | II | 14000.0000 | 3000.0000 | - | 112 MB |
70+
| | | | | | | | | | | | | | | |
71+
| SerializeNewtonsoft | Job-AAKTUU | .NET 5.0 | net50 | 100000 | 376.6 ms | 12.81 ms | 19.17 ms | ? | ? | II | 14000.0000 | 3000.0000 | - | 112 MB |
72+
| | | | | | | | | | | | | | | |
73+
| SerializeNewtonsoft | Job-AEYDDU | .NET Core 3.1 | netcoreapp31 | 100000 | 429.6 ms | 7.57 ms | 10.61 ms | ? | ? | II | 14000.0000 | 3000.0000 | - | 112 MB |
74+
75+
76+
<p align="center">
77+
<img src="benchmarkresult/SerializeFeatureCollectionLinestring-barplot.png" width="750" title="Serializing comparison">
78+
</p>
79+
80+
### Deserializing comparison
81+
82+
``` ini
83+
84+
BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19042.1415 (20H2/October2020Update)
85+
Intel Core i7-9850H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
86+
.NET SDK=6.0.100
87+
[Host] : .NET 6.0.0 (6.0.21.52210), X64 RyuJIT
88+
Job-WNYOAA : .NET 6.0.0 (6.0.21.52210), X64 RyuJIT
89+
Job-AAKTUU : .NET 5.0.13 (5.0.1321.56516), X64 RyuJIT
90+
Job-AEYDDU : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT
91+
92+
IterationCount=15 LaunchCount=2 WarmupCount=10
93+
94+
```
95+
| Method | Job | Runtime | Toolchain | N | Mean | Error | StdDev | Ratio | RatioSD | Rank | Gen 0 | Gen 1 | Gen 2 | Allocated |
96+
|-------------------------- |----------- |-------------- |------------- |------- |-----------:|---------:|---------:|------:|--------:|-----:|------------:|-----------:|----------:|----------:|
97+
| DeserializeSystemTextJson | Job-WNYOAA | .NET 6.0 | net60 | 100000 | 719.6 ms | 38.29 ms | 57.31 ms | 1.00 | 0.00 | I | 32000.0000 | 12000.0000 | 1000.0000 | 201 MB |
98+
| | | | | | | | | | | | | | | |
99+
| DeserializeSystemTextJson | Job-AAKTUU | .NET 5.0 | net50 | 100000 | 787.3 ms | 22.38 ms | 32.80 ms | ? | ? | I | 32000.0000 | 12000.0000 | 1000.0000 | 201 MB |
100+
| | | | | | | | | | | | | | | |
101+
| DeserializeSystemTextJson | Job-AEYDDU | .NET Core 3.1 | netcoreapp31 | 100000 | 894.6 ms | 25.84 ms | 37.87 ms | ? | ? | I | 32000.0000 | 12000.0000 | 1000.0000 | 200 MB |
102+
| | | | | | | | | | | | | | | |
103+
| DeserializeNewtonsoft | Job-WNYOAA | .NET 6.0 | net60 | 100000 | 1,410.8 ms | 27.59 ms | 40.44 ms | 1.96 | 0.13 | II | 146000.0000 | 37000.0000 | 1000.0000 | 870 MB |
104+
| | | | | | | | | | | | | | | |
105+
| DeserializeNewtonsoft | Job-AAKTUU | .NET 5.0 | net50 | 100000 | 1,430.7 ms | 31.66 ms | 46.40 ms | ? | ? | II | 146000.0000 | 37000.0000 | 1000.0000 | 870 MB |
106+
| | | | | | | | | | | | | | | |
107+
| DeserializeNewtonsoft | Job-AEYDDU | .NET Core 3.1 | netcoreapp31 | 100000 | 1,656.4 ms | 40.05 ms | 58.71 ms | ? | ? | II | 145000.0000 | 37000.0000 | 1000.0000 | 869 MB |
108+
109+
110+
<p align="center">
111+
<img src="benchmarkresult/DeserializeFeatureCollectionLinestring-barplot.png" width="750" title="Deserializing comparison">
112+
</p>
113+
</details>
114+
115+
116+
## Contributing
117+
Highly welcome! Just fork away and send a pull request. We try and review most pull requests within a couple of days.
118+
119+
## Thanks
120+
This library would be NOTHING without its [contributors](https://github.com/GeoJSON-Net/GeoJSON.Text/graphs/contributors) - thanks so much!!
121+
122+
## Sponsors
123+
124+
We have the awesome .NET tools from [JetBrains](http://www.jetbrains.com/).
125+
126+
[![Resharper](http://www.filehelpers.net/images/tools_resharper.gif)](http://www.jetbrains.com/resharper/)
127+
128+
## Contributors
129+
130+
This project exists thanks to all the people who contribute.
131+
<a href="https://github.com/GeoJSON-Net/GeoJSON.Text/graphs/contributors"><img src="https://opencollective.com/geojson-net/contributors.svg?width=890&button=false" /></a>
132+
133+
134+
## Backers
135+
136+
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/geojson-net#backer)]
137+
138+
<a href="https://opencollective.com/geojson-net#backers" target="_blank"><img src="https://opencollective.com/geojson-net/backers.svg?width=890"></a>
139+
140+
141+
## Sponsors
142+
143+
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/geojson-net#sponsor)]
144+
145+
<a href="https://opencollective.com/geojson-net/sponsor/0/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/0/avatar.svg"></a>
146+
<a href="https://opencollective.com/geojson-net/sponsor/1/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/1/avatar.svg"></a>
147+
<a href="https://opencollective.com/geojson-net/sponsor/2/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/2/avatar.svg"></a>
148+
<a href="https://opencollective.com/geojson-net/sponsor/3/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/3/avatar.svg"></a>
149+
<a href="https://opencollective.com/geojson-net/sponsor/4/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/4/avatar.svg"></a>
150+
<a href="https://opencollective.com/geojson-net/sponsor/5/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/5/avatar.svg"></a>
151+
<a href="https://opencollective.com/geojson-net/sponsor/6/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/6/avatar.svg"></a>
152+
<a href="https://opencollective.com/geojson-net/sponsor/7/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/7/avatar.svg"></a>
153+
<a href="https://opencollective.com/geojson-net/sponsor/8/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/8/avatar.svg"></a>
154+
<a href="https://opencollective.com/geojson-net/sponsor/9/website" target="_blank"><img src="https://opencollective.com/geojson-net/sponsor/9/avatar.svg"></a>

‎benchmarkresult/DeserializeFeatureCollectionLinestring-barplot.png‎

64.3 KB
Loading

‎benchmarkresult/SerializeFeatureCollectionLinestring-barplot.png‎

65 KB
Loading

‎src/GeoJSON.Text.Test.Benchmark/GeoJsonNetVsSystemText/Deserialize/DeserializeFeatureCollectionLinestring.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ public class DeserializeFeatureCollectionLinestring
88
{
99
string fileContents = "";
1010

11-
[Params(10000)]
11+
[Params(100000)]
1212
public int N;
1313

1414
[GlobalSetup]
@@ -18,12 +18,12 @@ public void Setup()
1818
}
1919

2020
[Benchmark]
21-
public Net.Feature.FeatureCollection DeserializeFeatureCollectionNewtonsoft() => Newtonsoft.Json.JsonConvert.DeserializeObject<Net.Feature.FeatureCollection>(fileContents ?? "")
21+
public Net.Feature.FeatureCollection DeserializeNewtonsoft() => Newtonsoft.Json.JsonConvert.DeserializeObject<Net.Feature.FeatureCollection>(fileContents ?? "")
2222
?? throw new NullReferenceException("Deserialization should not return a null value.");
2323

2424

2525
[Benchmark]
26-
public Text.Feature.FeatureCollection DeserializeFeatureCollectionSystemTextJson() => System.Text.Json.JsonSerializer.Deserialize<Text.Feature.FeatureCollection>(fileContents)
26+
public Text.Feature.FeatureCollection DeserializeSystemTextJson() => System.Text.Json.JsonSerializer.Deserialize<Text.Feature.FeatureCollection>(fileContents)
2727
?? throw new NullReferenceException("Deserialization should not return a null value.");
2828
}
2929
}

‎src/GeoJSON.Text.Test.Benchmark/GeoJsonNetVsSystemText/Serialize/SerializeFeatureCollectionLinestring.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ public class SerializeFeatureCollectionLinestring
1313
// GeoJson.Text
1414
private Text.Feature.FeatureCollection featureCollectionGeoJsonTEXT = new Text.Feature.FeatureCollection();
1515

16-
[Params(10000)]
16+
[Params(100000)]
1717
public int N;
1818

1919
[GlobalSetup]

0 commit comments

Comments
 (0)