From 09b633e38c11da98fcff8a34a524d0296bc8594c Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Thu, 17 Sep 2020 21:15:39 +0000 Subject: [PATCH] fix: moving from docs --- data-model-layer/numeric-size.md | 95 ++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 data-model-layer/numeric-size.md diff --git a/data-model-layer/numeric-size.md b/data-model-layer/numeric-size.md new file mode 100644 index 00000000..ba44b646 --- /dev/null +++ b/data-model-layer/numeric-size.md @@ -0,0 +1,95 @@ +Numeric sizes +============= + + +Integers +-------- + +In principle, we consider the range of integers to be infinite. +In practice, many libraries may choose to implement things in such a way that numbers may have limited sizes. + +We require that IPLD libraries support integers up to at least size 2^53 in order to be considered a full-featured core-compliant IPLD library. + +We love IPLD libraries that support arbitrarily large numbers. But 2^53 is the critical minimum. + + +### Why? + +Because. + +But let's ask more detailed questions, and answer those: + +### Why have size limits at all? + +Most programming languages and compilers already have size limits when working with numbers. + +Being in denial about this when we describe IPLD is unconstructive: +It's important for us to be able to provide concrete recommendations about what we expect from IPLD libraries -- +and if that guidance is "always use a bigint type, regardless of whether you language and ecosystem provides a usable and widely adopted one", +then that guidance will be frequently ignored, regardless of how principled and well-intentioned it may be. + +### Why 2^53? + +This 2^53 number is chosen because it's reasonably high (e.g., you can use it for timestamps), +and also because it's reasonably practical (it happens to be the number above which javascript's handling of numbers gets Interesting). + +**Above this number, it's likely that you'll want to consider application-level and language-level numeric compatibility issues which are bigger in scope than IPLD _anyway_.** + +32-bit signed, 32-bit unsigned, 64-bit signed, and 64-bit unsigned integers are also all common numeric sizes to consider, +because those are often the well-supported numeric types in programming languages. +When writing a new IPLD library, we suggest you pick "64-bit signed" if these are your options. + +(32-bit numbers are definitely small enough to get you into trouble; +the [2038 problem](https://en.wikipedia.org/wiki/Year_2038_problem) is coming up *very* soon now. +By contrast, a 53-bit integer used to represent a second-granularity timestamp should get you to about the year 285,618,384. +So... it should suffice.) + +### What if I want to write an IPLD library that supports arbitrarily large ints? + +**Go for it.** + +If it is possible to support arbitrary "BigInt" in your library, that's fantastic. Do it. + +We just don't _mandate_ this as part of the minimum core feature checklist for IPLD libraries, +because we understand that it's impractical in some programming languages, +either because the "BigInt" types have different performance characteristics, +or aren't widely agreed upon in the community, +or are otherwise simply syntactically or ergonomically clunky to handle, etc. +But if you see it as easy to support: _go for it_. + +### What if I ship an IPLD library that only supports 2^47? + +(... or some other completely arbitrary number.) + +Fine. + +Please be very clear about that in your documentation. + +We won't list your library in our own docs as being a full-featured core-compliant IPLD library. + +But go nuts; nobody's going to stop you. +Your library may run into hard times processing data that's produced by other IPLD libraries, but that's a choice you're free to make. + +### What if my IPLD library encounters serialized numbers that are bigger than it supports? + +Then it must error. Clearly, one would hope. + +IPLD libraries must not quietly round down to their max (or up to their min) supported values -- they must error. + +Fortunately, this rule gets us pretty far, pretty easily -- because we don't *do math* in IPLD, +these errors can really only arise during deserialization, +and should fit naturally into the error reporting flow that deserialization already naturally needs. + + + + + +Floating point +-------------- + +// a lot of text can go here. + +// it would be nice if at least some of it can talk about the inherent issues of precision ambiguity in floating point, +// and how fixed point is actually an important consideration in many sufficiently scientific applications. +// discussion of fractions and how floating point approximations of them are necessarily wrong would also be appropriate. +// in general it would be great if this document can remind people that floats are rarely "the answer", and are certainly not the only answer.