Skip to content

Commit

Permalink
Add important admonition about using System.Decimal POCO property typ…
Browse files Browse the repository at this point in the history
…es (elastic#2495)

Bump AsciiDoctNet to support additional asciidoc syntax
Closes elastic#2463
Conflicts:
	src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs
  • Loading branch information
russcam authored and awelburn committed Nov 6, 2017
1 parent 2de1567 commit 6e39dde
Show file tree
Hide file tree
Showing 9 changed files with 54 additions and 9 deletions.
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 @@ -290,6 +290,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 @@ -264,7 +264,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 @@ -300,7 +300,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 @@ -200,7 +200,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
24 changes: 23 additions & 1 deletion src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,28 @@ 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
Expand Down Expand Up @@ -969,7 +991,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 6e39dde

Please sign in to comment.