From 9541b1276b8798d28ba4c6e4893994bad9f98297 Mon Sep 17 00:00:00 2001 From: dkf Date: Thu, 6 Jun 2019 17:58:33 +0000 Subject: Tests and docs --- doc/expr.n | 59 ++++++++++++++++++++++++++++++++++++++++++------ doc/mathop.n | 67 ++++++++++++++++++++++++++++++++++++++++++++++--------- tests/expr.test | 20 +++++++++++++++++ tests/mathop.test | 44 ++++++++++++++++++++++++++++++++++-- 4 files changed, 171 insertions(+), 19 deletions(-) diff --git a/doc/expr.n b/doc/expr.n index 0210348..a7939f8 100644 --- a/doc/expr.n +++ b/doc/expr.n @@ -97,7 +97,7 @@ and the value of \fBb\fR is 6. The command on the left side of each line produces the value on the right side. .PP .CS -.ta 6c +.ta 8c \fBexpr\fR 3.1 + $a \fI6.1\fR \fBexpr\fR 2 + "$a.$b" \fI5.6\fR \fBexpr\fR 4*[llength "6 2"] \fI8\fR @@ -159,7 +159,18 @@ A right shift always propagates the sign bit. .TP 20 \fB<\0\0>\0\0<=\0\0>=\fR . -Boolean less than, greater than, less than or equal, and greater than or equal. +Boolean numeric-preferring comparisons: less than, greater than, less than or +equal, and greater than or equal. If either argument is not numeric, the +comparison is done using UNICODE string comparison, as with the string +comparison operators below, which have the same precedence. +.TP 20 +\fBlt\0\0gt\0\0le\0\0ge\fR +.VS "8.7, TIP461" +Boolean string comparisons: less than, greater than, less than or equal, and +greater than or equal. These always compare values using their UNICODE strings +(also see \fBstring compare\fR), unlike with the numeric-preferring +comparisons abov, which have the same precedence. +.VE "8.7, TIP461" .TP 20 \fB==\0\0!=\fR . @@ -190,16 +201,20 @@ Bit-wise OR. Valid for integer operands. \fB&&\fR . Logical AND. If both operands are true, the result is 1, or 0 otherwise. - +This operator evaluates lazily; it only evaluates its right-hand side if it +must in order to determine its result. .TP 20 \fB||\fR . Logical OR. If both operands are false, the result is 0, or 1 otherwise. +This operator evaluates lazily; it only evaluates its right-hand side if it +must in order to determine its result. .TP 20 -\fIx\fB?\fIy\fB:\fIz\fR +\fIx \fB?\fI y \fB:\fI z\fR . If-then-else, as in C. If \fIx\fR is false , the result is the value of \fIy\fR. Otherwise the result is the value of \fIz\fR. +This operator evaluates lazily; it only evaluates one of \fIy\fR or \fIz\fR. .PP The exponentiation operator promotes types in the same way that the multiply and divide operators do, and the result is is the same as the result of @@ -339,37 +354,67 @@ substitution on the value before \fBexpr\fR is called. In the following example, the value of the expression is 11 because the Tcl parser first substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR. Enclosing the expression in braces would result in a syntax error. +.PP .CS set a 3 set b {$a + 2} \fBexpr\fR $b*4 .CE .PP - -When an expression is generated at runtime, like the one above is, the bytcode +When an expression is generated at runtime, like the one above is, the bytecode compiler must ensure that new code is generated each time the expression is evaluated. This is the most costly kind of expression from a performance perspective. In such cases, consider directly using the commands described in the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR. - +.PP Most expressions are not formed at runtime, but are literal strings or contain substitutions that don't introduce other substitutions. To allow the bytecode compiler to work with an expression as a string literal at compilation time, ensure that it contains no substitutions or that it is enclosed in braces or otherwise quoted to prevent Tcl from performing substitutions, allowing \fBexpr\fR to perform them instead. +.PP +If it is necessary to include a non-constant expression string within the +wider context of an otherwise-constant expression, the most efficient +technique is to put the varying part inside a recursive \fBexpr\fR, as this at +least allows for the compilation of the outer part, though it does mean that +the varying part must itself be evaluated as a separate expression. Thus, in +this example the result is 20 and the outer expression benefits from fully +cached bytecode compilation. +.PP +.CS +set a 3 +set b {$a + 2} +\fBexpr\fR {[\fBexpr\fR $b] * 4} +.CE +.PP +In general, you should enclose your expression in braces wherever possible, +and where not possible, the argument to \fBexpr\fR should be an expression +defined elsewhere as simply as possible. It is usually more efficient and +safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR +namespace) than it is to do complex expression generation. .SH EXAMPLES .PP A numeric comparison whose result is 1: +.PP .CS \fBexpr\fR {"0x03" > "2"} .CE .PP A string comparison whose result is 1: +.PP .CS \fBexpr\fR {"0y" > "0x12"} .CE .PP +.VS "8.7, TIP461" +A forced string comparison whose result is 0: +.PP +.CS +\fBexpr\fR {"0x03" gt "2"} +.CE +.VE "8.7, TIP461" +.PP Define a procedure that computes an .QW interesting mathematical function: diff --git a/doc/mathop.n b/doc/mathop.n index 84cf308..1c70e95 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -55,6 +55,16 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathop::ne\fR \fIarg arg\fR .br +.VS "8.7, TIP461" +\fB::tcl::mathop::lt\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::le\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::gt\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::ge\fR ?\fIarg\fR ...? +.VE "8.7, TIP461" +.br \fB::tcl::mathop::in\fR \fIarg list\fR .br \fB::tcl::mathop::ni\fR \fIarg list\fR @@ -76,7 +86,8 @@ The following operator commands are supported: \fB/\fR \fB%\fR \fB**\fR \fB&\fR \fB|\fR \fB^\fR \fB>>\fR \fB<<\fR \fB==\fR \fBeq\fR \fB!=\fR \fBne\fR \fB<\fR \fB<=\fR \fB>\fR -\fB>=\fR \fBin\fR \fBni\fR +\fB>=\fR \fBin\fR \fBni\fR \fBlt\fR \fBle\fR +\fBgt\fR \fBge\fR .DE .SS "MATHEMATICAL OPERATORS" .PP @@ -192,8 +203,8 @@ after the first having to be strictly more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBlt\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB<=\fR ?\fIarg\fR ...? . @@ -202,8 +213,8 @@ after the first having to be equal to or more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBle\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB>\fR ?\fIarg\fR ...? . @@ -212,8 +223,8 @@ after the first having to be strictly less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBgt\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB>=\fR ?\fIarg\fR ...? . @@ -222,8 +233,40 @@ after the first having to be equal to or less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBge\fR +operator or the \fBstring compare\fR command should be used instead. +.TP +\fBlt\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be strictly more than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBle\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be equal to or strictly more than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBgt\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be strictly less than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBge\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be equal to or strictly less than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" .SS "BIT-WISE OPERATORS" .PP The behaviors of the bit-wise operator commands (all of which only operate on @@ -299,8 +342,12 @@ set gotIt [\fBin\fR 3 $list] \fI# Test to see if a value is within some defined range\fR set inRange [\fB<=\fR 1 $x 5] -\fI# Test to see if a list is sorted\fR +\fI# Test to see if a list is numerically sorted\fR set sorted [\fB<=\fR {*}$list] + +\fI# Test to see if a list is lexically sorted\fR +set alphaList {a b c d e f} +set sorted [\fBle\fR {*}$alphaList] .CE .SH "SEE ALSO" expr(n), mathfunc(n), namespace(n) diff --git a/tests/expr.test b/tests/expr.test index cb0c24d..01c5213 100644 --- a/tests/expr.test +++ b/tests/expr.test @@ -411,6 +411,26 @@ test expr-8.34 {expr edge cases} -body { test expr-8.35 {expr edge cases} -body { expr {1ea} } -returnCodes error -match glob -result * +test expr-8.36 {CompileEqualtyExpr: string comparison ops} { + set x 012 + set y 0x0 + list [expr {$x < $y}] [expr {$x lt $y}] [expr {$x lt $x}] +} {0 1 0} +test expr-8.37 {CompileEqualtyExpr: string comparison ops} { + set x 012 + set y 0x0 + list [expr {$x <= $y}] [expr {$x le $y}] [expr {$x le $x}] +} {0 1 1} +test expr-8.38 {CompileEqualtyExpr: string comparison ops} { + set x 012 + set y 0x0 + list [expr {$x > $y}] [expr {$x gt $y}] [expr {$x gt $x}] +} {1 0 0} +test expr-8.39 {CompileEqualtyExpr: string comparison ops} { + set x 012 + set y 0x0 + list [expr {$x >= $y}] [expr {$x ge $y}] [expr {$x ge $x}] +} {1 0 1} test expr-9.1 {CompileRelationalExpr: just shift expr} {expr 3<<2} 12 test expr-9.2 {CompileRelationalExpr: just shift expr} {expr 0xff>>2} 63 diff --git a/tests/mathop.test b/tests/mathop.test index a1a3f80..958a56f 100644 --- a/tests/mathop.test +++ b/tests/mathop.test @@ -95,7 +95,7 @@ proc TestOp {op args} { } return [lindex $results 0] } - + # start of tests namespace eval ::testmathop { @@ -1342,6 +1342,46 @@ test mathop-26.2 { misc ops, corner cases } { set res } [list 2147483648 9223372036854775808 9223372036854775808 4294967296 18446744073709551616] +test mathop-27.1 {lt operator} {::tcl::mathop::lt} 1 +test mathop-27.2 {lt operator} {::tcl::mathop::lt a} 1 +test mathop-27.3 {lt operator} {::tcl::mathop::lt a b} 1 +test mathop-27.4 {lt operator} {::tcl::mathop::lt b a} 0 +test mathop-27.5 {lt operator} {::tcl::mathop::lt a a} 0 +test mathop-27.6 {lt operator} {::tcl::mathop::lt a b c} 1 +test mathop-27.7 {lt operator} {::tcl::mathop::lt b a c} 0 +test mathop-27.8 {lt operator} {::tcl::mathop::lt a c b} 0 +test mathop-27.9 {lt operator} {::tcl::mathop::lt 012 0x0} 1 + +test mathop-28.1 {le operator} {::tcl::mathop::le} 1 +test mathop-28.2 {le operator} {::tcl::mathop::le a} 1 +test mathop-28.3 {le operator} {::tcl::mathop::le a b} 1 +test mathop-28.4 {le operator} {::tcl::mathop::le b a} 0 +test mathop-28.5 {le operator} {::tcl::mathop::le a a} 1 +test mathop-28.6 {le operator} {::tcl::mathop::le a b c} 1 +test mathop-28.7 {le operator} {::tcl::mathop::le b a c} 0 +test mathop-28.8 {le operator} {::tcl::mathop::le a c b} 0 +test mathop-28.9 {le operator} {::tcl::mathop::le 012 0x0} 1 + +test mathop-29.1 {gt operator} {::tcl::mathop::gt} 1 +test mathop-29.2 {gt operator} {::tcl::mathop::gt a} 1 +test mathop-29.3 {gt operator} {::tcl::mathop::gt a b} 0 +test mathop-29.4 {gt operator} {::tcl::mathop::gt b a} 1 +test mathop-29.5 {gt operator} {::tcl::mathop::gt a a} 0 +test mathop-29.6 {gt operator} {::tcl::mathop::gt c b a} 1 +test mathop-29.7 {gt operator} {::tcl::mathop::gt b a c} 0 +test mathop-29.8 {gt operator} {::tcl::mathop::gt a c b} 0 +test mathop-29.9 {gt operator} {::tcl::mathop::gt 0x0 012} 1 + +test mathop-30.1 {ge operator} {::tcl::mathop::ge} 1 +test mathop-30.2 {ge operator} {::tcl::mathop::ge a} 1 +test mathop-30.3 {ge operator} {::tcl::mathop::ge a b} 0 +test mathop-30.4 {ge operator} {::tcl::mathop::ge b a} 1 +test mathop-30.5 {ge operator} {::tcl::mathop::ge a a} 1 +test mathop-30.6 {ge operator} {::tcl::mathop::ge c b a} 1 +test mathop-30.7 {ge operator} {::tcl::mathop::ge b a c} 0 +test mathop-30.8 {ge operator} {::tcl::mathop::ge a c b} 0 +test mathop-30.9 {ge operator} {::tcl::mathop::ge 0x0 012} 1 + if 0 { # Compare ops to expr bytecodes namespace import ::tcl::mathop::* @@ -1354,7 +1394,7 @@ if 0 { _X 3 4 5 set ::tcl_traceCompile 0 } - + # cleanup namespace delete ::testmathop namespace delete ::testmathop2 -- cgit v0.12