Explain how jot does rounding and truncation. Help from jmc@

ok jmc@ millert@ deraadt@

1 files changed, 122 insertions, 8 deletions

diff --git a/usr.bin/jot/jot.1 b/usr.bin/jot/jot.1
index cfa0273a028..daf00e31342 100644
--- a/usr.bin/jot/jot.1
+++ b/usr.bin/jot/jot.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: jot.1,v 1.13 2003/12/30 19:41:48 otto Exp $
+.\"	$OpenBSD: jot.1,v 1.14 2004/01/01 07:04:10 otto Exp $
 .\"	$NetBSD: jot.1,v 1.2 1994/11/14 20:27:36 jtc Exp $
 .\"
 .\" Copyright (c) 1993
@@ -146,6 +146,120 @@ The name
 derives in part from
 .Xr iota ,
 a function in APL.
+.Ss Rounding and truncation
+The
+.Nm
+utility uses double precision floating point arithmetic internally.
+Before printing a number, it is converted depending on the output
+format used.
+.Pp
+If no output format is specified or the output format is a
+floating point format
+.Po
+.Sq f ,
+.Sq e ,
+.Sq g ,
+.Sq E ,
+or
+.Sq G
+.Pc ,
+the value is rounded using the
+.Xr printf 3
+function, taking into account the requested precision.
+.Pp
+If the output format is an integer format
+.Po
+.Sq c ,
+.Sq d ,
+.Sq o ,
+.Sq x ,
+.Sq u ,
+.Sq D ,
+.Sq O ,
+.Sq X ,
+.Sq U ,
+or
+.Sq i
+.Pc ,
+the value is converted to an integer value by truncation.
+.Pp
+As an illustration, consider the following command:
+.Bd -literal -offset indent
+$ jot 6 1 10 0.5
+1
+2
+2
+2
+3
+4
+.Ed
+.Pp
+By requesting an explicit precision of 1, the values generated before rounding
+can be seen.
+The .5 values are rounded down if the integer part is even,
+up otherwise.
+.Bd -literal -offset indent
+$ jot -p 1 6 1 10 0.5
+1.0
+1.5
+2.0
+2.5
+3.0
+3.5
+.Ed
+.Pp
+By offsetting the values slightly, the values generated by the following
+command are always rounded down:
+.Bd -literal -offset indent
+$ jot -p 0 6 .9999999999 10 0.5
+1
+1
+2
+2
+3
+3
+.Ed
+.Pp
+Another way of achieving the same result is to force truncation by
+specifying an integer format:
+.Bd -literal -offset indent
+$ jot -w %d 6 1 10 0.5
+.Ed
+.Pp
+For random sequences, the output format also influences the range
+and distribution of the generated numbers:
+.Bd -literal -offset indent
+$ jot -r 100000 1 3 | sort -n | uniq -c
+24950 1
+50038 2
+25012 3
+.Ed
+.Pp
+The values at the beginning and end of the interval
+are generated less frequently than the other values.
+There are several ways to solve this problem and generate evenly distributed
+integers:
+.Bd -literal -offset indent
+$ jot -r -p 0 100000 0.5 3.5 | sort -n | uniq -c
+33374 1
+33363 2
+33263 3
+
+$ jot -w %d -r 100000 1 4 | sort -n | uniq -c
+33306 1
+33473 2
+33221 3
+.Ed
+.Pp
+Note that with random sequences, all numbers generated will
+be smaller than the upper bound.
+The largest value generated will be a tiny bit smaller than
+the upper bound.
+For floating point formats, the value is rounded as described
+before being printed.
+For integer formats, the highest value printed will be one less
+than the requested upper bound, because the generated value will
+be truncated.
 .Sh EXAMPLES
 Print 21 evenly spaced numbers increasing from \-1 to 1:
 .Pp
@@ -159,9 +273,14 @@ Generate the strings xaa through xaz:
 .Pp
 .Dl $ jot \-w xa%c 26 a
 .Pp
-Generate 20 random 8-letter strings:
+Generate 20 random 8-letter strings
+(note that the character
+.Sq {
+comes after the character
+.Sq z
+in the ASCII character set):
 .Pp
-.Dl "$ jot \-r \-c 160 a z | rs \-g 0 8"
+.Dl "$ jot \-r \-c 160 a { | rs \-g 0 8"
 .Pp
 Infinitely many
 .Xr yes 1 's
@@ -175,11 +294,6 @@ substitution commands applying to lines 2, 7, 12, etc. is the result of:
 .Pp
 .Dl $ jot \-w %ds/old/new/ 30 2 \- 5
 .Pp
-The stuttering sequence 9, 9, 8, 8, 7, etc. can be
-produced by suitable choice of precision and step size:
-.Pp
-.Dl $ jot 20 9 0 \-.475
-.Pp
 Create a file containing exactly 1024 bytes:
 .Pp
 .Dl $ jot \-b x 512 > block