From f9497d64c53e93f68b05b89bcf41fc8dcc21cdb2 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Thu, 27 Sep 2018 13:34:32 +0100 Subject: [PATCH] Handle a couple of TODOs --- syndicate/mc/preserve.md | 47 ++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/syndicate/mc/preserve.md b/syndicate/mc/preserve.md index 6bb6d39..c8d9668 100644 --- a/syndicate/mc/preserve.md +++ b/syndicate/mc/preserve.md @@ -324,11 +324,9 @@ Numeric data follow the [JSON grammar](https://tools.ietf.org/html/rfc8259#section-6), with the addition of a trailing "f" distinguishing `Float` from `Double` values. `Float`s and `Double`s always have either a fractional part or -an exponent part, where `SignedInteger`s never have either. - -TODO: talk about precise reading of floats, and the need for arbitrary -precision. Your language will often have a good floating-point reading -library. +an exponent part, where `SignedInteger`s never have +either.[^reading-and-writing-floats-accurately] +[^arbitrary-precision-signedinteger] Float = flt %i"f" Double = flt @@ -341,12 +339,36 @@ library. exp = %i"e" ["-"/"+"] 1*DIGIT flt = int (frac exp / frac / exp) + [^reading-and-writing-floats-accurately]: **Implementation note.** + Your language's standard library likely has a good routine for + converting between decimal notation and IEEE 754 floating-point. + However, if not, or if you are interested in the challenges of + accurately reading and writing floating point numbers, see the + excellent matched pair of 1990 papers by Clinger and Steele & + White, and a recent follow-up by Jaffer: + + Clinger, William D. ‘How to Read Floating Point Numbers + Accurately’. In Proc. PLDI. White Plains, New York, 1990. + . + + Steele, Guy L., Jr., and Jon L. White. ‘How to Print + Floating-Point Numbers Accurately’. In Proc. PLDI. White Plains, + New York, 1990. . + + Jaffer, Aubrey. ‘Easy Accurate Reading and Writing of + Floating-Point Numbers’. ArXiv:1310.8121 [Cs], 27 October 2013. + . + + [^arbitrary-precision-signedinteger]: **Implementation note.** Be + aware when implementing reading and writing of `SignedInteger`s + that the data model *requires* arbitrary-precision integers. Your + I/O routines must not truncate precision either when reading or + writing a `SignedInteger`. + `String`s are, [as in JSON](https://tools.ietf.org/html/rfc8259#section-7), possibly escaped text surrounded by double quotes. The escaping rules are the -same as for JSON.[^string-json-correspondence] - -TODO: discuss surrogate pairs in \uXXXX form +same as for JSON.[^string-json-correspondence] [^escaping-surrogate-pairs] String = %x22 *char %x22 char = unescaped / %x7C / escape (escaped / %x22 / %s"u" 4HEXDIG) @@ -366,6 +388,12 @@ TODO: discuss surrogate pairs in \uXXXX form `string`. Some auxiliary definitions (e.g. `escaped`) are lifted largely unmodified from the text of RFC 8259. + [^escaping-surrogate-pairs]: In particular, note JSON's rules around + the use of surrogate pairs for code points not in the Basic + Multilingual Plane. We encourage implementations to avoid escaping + such characters when producing output, and instead to rely on the + UTF-8 encoding of the entire document to handle them correctly. + A `ByteString` may be written in any of three different forms. The first is similar to a `String`, but prepended with a hash sign @@ -411,7 +439,8 @@ TODO: More unicode in unescaped symbols? ### Printing -Recommend a JSON-compatible print mode. Recommend a submode with trailing commas. +TODO: Recommend a JSON-compatible print mode. Recommend a submode with +trailing commas. ## Compact Binary Syntax