mirror/stedolan-jq
1
0
Fork 0
mirror of https://github.com/stedolan/jq.git synced 2024-05-11 05:55:39 +00:00
Code Issues Releases Activity

manual.yml: revise section on identity, clarifying what is subject to change

Browse Source 
Mostly clarifications w.r.t. numbers.

The anomalous behavior of leading minus signs is documented, with an explicit notice that this will probably change.
This commit is contained in:
pkoppstein
2023-07-19 22:25:10 -04:00
committed by Nico Williams
parent a192e647c5
commit 3ec66c858c
3 changed files with 95 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/content/manual/manual.yml
View File

@@ -312,36 +312,66 @@ sections:
- title: "Identity: `.`"
body: |
The absolute simplest filter is `.` . This is a filter that
takes its input and produces it unchanged as output. That is,
this is the identity operator.
The absolute simplest filter is `.` . This filter takes its
input and produces the same value as output. That is, this
is the identity operator.
Since jq by default pretty-prints all output, this trivial
program can be a useful way of formatting JSON output from,
say, `curl`.
Since jq by default pretty-prints all output, a trivial
program consisting of nothing but `.` can be used to format
JSON output from, say, `curl`.
An important point about the identity filter is that it
guarantees to preserve the literal decimal representation
of values. This is particularly important when dealing with numbers
which can't be losslessly converted to an IEEE754 double precision
Although the identity filter never modifies the value of its
input, jq processing can sometimes make it appear as though
it does. For example, using the current implementation of
jq, we would see that the expression:
`1E1234567890 | .`
produces `1.7976931348623157e+308` on at least one platform.
This is because, in the process of parsing the number, this
particular version of jq has converted it to an IEEE754
double-precision representation, losing precision.
The way in which jq handles numbers has changed over time
and further changes are likely within the parameters set by
the relevant JSON standards. The following remarks are
therefore offered with the understanding that they are
intended to be descriptive of the current version of jq and
should not be interpreted as being prescriptive:
(1) Any arithmetic operation on a number that has not
already been converted to an IEEE754 double precision
representation will trigger a conversion to the IEEE754
representation.
jq doesn't truncate the literal numbers to double unless there
is a need to make arithmetic operations with the number.
Comparisons are carried out over the untruncated big decimal
representation of the number.
(2) jq will attempt to maintain the original decimal
precision of number literals, but in expressions such
`1E1234567890`, precision will be lost if the exponent is
too large.
jq will also try to maintain the original decimal precision of the provided
number literal. See below for examples.
(3) In jq programs, a leading minus sign will trigger the
conversion of the number to an IEEE754 representation.
(4) Comparisons are carried out using the untruncated
big decimal representation of numbers if available, as
illustrated in one of the following examples.
examples:
- program: '.'
input: '"Hello, world!"'
output: ['"Hello, world!"']
- program: '. | tojson'
- program: '.'
input: '0.12345678901234567890123456789'
output: ['0.12345678901234567890123456789']
- program: '[., tojson]'
input: '12345678909876543212345'
output: ['"12345678909876543212345"']
output: ['[12345678909876543212345,"12345678909876543212345"]']
- program: '. < 0.12345678901234567890123456788'
input: '0.12345678901234567890123456789'
output: ['false']
- program: 'map([., . == 1]) | tojson'
input: '[1, 1.000, 1.0, 100e-2]'