Skip to content

Commit

Permalink
Add important admonition about using System.Decimal POCO property types
Browse files Browse the repository at this point in the history
Bump AsciiDoctNet to support additional asciidoc syntax
Closes #2463
  • Loading branch information
russcam committed Dec 14, 2016
1 parent a18b45c commit 5c5df6d
Show file tree
Hide file tree
Showing 10 changed files with 57 additions and 14 deletions.
2 changes: 0 additions & 2 deletions docs/aggregations/writing-aggregations.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,6 @@ return s => s
);
----
<1> a list of aggregation functions to apply

<2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions

Combining multipe `AggregationDescriptor`'s is also possible using the bitwise `&` operator
Expand Down Expand Up @@ -212,6 +211,5 @@ var maxPerChild = childAggregation.Max("max_per_child");
maxPerChild.Should().NotBeNull(); <2>
----
<1> Do something with the average per child. Here we just assert it's not null

<2> Do something with the max per child. Here we just assert it's not null

23 changes: 23 additions & 0 deletions docs/client-concepts/high-level/mapping/auto-map.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,29 @@ var expected = new
Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor);
----

[IMPORTANT]
====
Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type
commonly used to express currencies and other financial calculations that require large numbers of significant
integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the
nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point.
When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat
of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause
problems in _some_ edge cases.
As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states],
[quote, C# Specification section 6.2.1]
For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value.
While this conversion may lose precision, it never causes an exception to be thrown.
This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at
serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`,
respectively. In these cases, it is advisable to use `double` as the POCO property type.
====

[[auto-mapping-with-overrides]]
[float]
== Auto mapping with overrides
Expand Down
3 changes: 3 additions & 0 deletions docs/high-level.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ please modify the original csharp file found at the link and submit the PR with
[partintro]
--
The high level client, `ElasticClient`, provides a strongly typed query DSL that maps one-to-one with the Elasticsearch query DSL.

It can be installed from the Package Manager Console inside Visual Studio using

[source,shell]
Expand All @@ -22,8 +23,10 @@ Install-Package NEST
----

Or by searching for https://www.nuget.org/packages/NEST[NEST] in the Package Manager GUI.

NEST internally uses and still exposes the low level client, `ElasticLowLevelClient`, from <<elasticsearch-net,Elasticsearch.Net>> via
the `.LowLevel` property on `ElasticClient`.

There are a number of conventions that NEST uses for inference of

* <<index-name-inference, Index Names>>
Expand Down
1 change: 1 addition & 0 deletions docs/low-level.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ please modify the original csharp file found at the link and submit the PR with
--
The low level client, `ElasticLowLevelClient`, is a low level, dependency free client that has no
opinions about how you build and represent your requests and responses.

It can be installed from the Package Manager Console inside Visual Studio using

[source,shell]
Expand Down
2 changes: 1 addition & 1 deletion paket.lock
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
NUGET
remote: https://www.nuget.org/api/v2
AsciiDocNet (1.0.0-alpha3)
AsciiDocNet (1.0.0-alpha5)
Bogus (7.1.6)
NETStandard.Library (>= 1.6) - framework: >= netstandard13
Newtonsoft.Json (>= 9.0.1) - framework: >= net40, >= netstandard13
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ public override void Visit(SectionTitle sectionTitle)
var builder = new StringBuilder();
using (var writer = new AsciiDocVisitor(new StringWriter(builder)))
{
writer.Visit(sectionTitle.Elements);
writer.Visit((InlineContainer)sectionTitle);
}

var title = builder.ToString().PascalToHyphen();
Expand Down Expand Up @@ -301,7 +301,7 @@ private bool LastSectionTitleMatches(Func<string, bool> predicate)
var builder = new StringBuilder();
using (var visitor = new AsciiDocVisitor(new StringWriter(builder)))
{
visitor.Visit(lastSectionTitle.Elements);
visitor.Visit((InlineContainer)lastSectionTitle);
}

return predicate(builder.ToString());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,6 @@ private void CleanDocumentAndWriteToFile(string body, FileInfo destination)
{
document.Accept(new AsciiDocVisitor(file));
}

}
}
}
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection.Emit;
using System.Text.RegularExpressions;
using DocGenerator;

namespace DocGenerator.Documentation.Files
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ public override void SaveToDocumentationFolder()
{
var docFileName = this.CreateDocumentationLocation();

// copy for asciidoc to work (path is relative to file)
// copy for asciidoc to work when viewing a single asciidoc in the browser (path is relative to file)
this.FileLocation.CopyTo(docFileName.FullName, true);

// copy to the root as well, for the doc generation process (path is relative to root)
Expand Down
30 changes: 26 additions & 4 deletions src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs
Original file line number Diff line number Diff line change
Expand Up @@ -235,14 +235,36 @@ public void UsingAutoMap()
};

Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor);
}

}
/**[IMPORTANT]
* ====
* Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type
* commonly used to express currencies and other financial calculations that require large numbers of significant
* integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the
* nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point.
*
* When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat
* of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause
* problems in _some_ edge cases.
*
* As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states],
*
* [quote, C# Specification section 6.2.1]
* For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value.
* While this conversion may lose precision, it never causes an exception to be thrown.
*
* This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at
* serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`,
* respectively. In these cases, it is advisable to use `double` as the POCO property type.
* ====
*/

/**[float]
* == Auto mapping with overrides
* In most cases, you'll want to map more than just the vanilla datatypes and also provide
* various options for your properties (analyzer to use, whether to enable doc_values, etc...).
* In that case, it's possible to use `.AutoMap()` in conjunction with explicitly mapped properties.
*/
*/
[U]
public void OverridingAutoMappedProperties()
{
Expand Down Expand Up @@ -882,7 +904,7 @@ public void PutMappingAlsoAdheresToMaxRecursion()
//endhide

/**[float]
* == Applying conventions through the Visitor pattern
* == Applying conventions through the Visitor pattern
* It is also possible to apply a transformation on all or specific properties.
*
* `.AutoMap()` internally implements the https://en.wikipedia.org/wiki/Visitor_pattern[visitor pattern]. The default visitor, `NoopPropertyVisitor`,
Expand Down

0 comments on commit 5c5df6d

Please sign in to comment.