Next: error() Up: MacAnova Help File Previous: enterchars()   Contents

equal()

Usage:
equal(a, b [,chknames:F,chklabels:T,chknotes:T,fuzz:eps,relative:T,\
  explain:T), a and b any two defined variables except GRAPH variables,
  eps > 0 a small REAL scalar



Keywords: general, variables
                              Introduction
You can use equal() to test for exact or approximate equality of two
defined variables of any type except GRAPH.

                                  Usage
equal(arg1, arg2) returns True or False depending on whether or not arg1
and arg2 are exactly equal.  arg1 and arg2 can be any defined variables
except GRAPH variables, including macros, NULL variables, and
structures.

See below for keywords 'fuzz' and 'relative' which allow for approximate
equality and for keywords 'chknames', 'chklabels' and 'chknotes' that
control what non-data items are checked for equality.

If x is defined, equal(x,x) always returns True, even when x is a GRAPH
variable.

Two NULL variables are always treated as equal.

When arg1 and arg2 are structures, the are considered equal only if
every component or subcomponent is equal and component names are the same.

equal(arg1, arg2, explain:T) makes the same comparison but returns
structure(equal:T or F, why:Explanation), where Explanation is a
CHARACTER scalar that is either "Arguments are equal" or an explanation
of the inequality such as "Argument values differ" or "Component
dimensions differ".  In case of inequality, the first applicable reason
is given.  If arg1 and arg2 are unequal structures, the number of the
component or subcomponent where inequality was detected is part of the
explanation.

                     Keywords 'fuzz' and 'relative'
When you are comparing numerical results of computation, exact equality
may not be appropriate because real numbers are not perfectly
represented in the computer.  You can specify that REAL variables and
components are to be considered equal if the differences between their
elements are small enough, either in an absolute or relative sense.

equal(arg1, arg2, fuzz:epsilon), where epsilon > 0 is small, returns
True if all differences d = x1 - x2 of elements of REAL variables or
structure components satisfy abs(d) <= epsilon.

equal(arg1, arg2, fuzz:epsilon, relative:T) returns True if all
differences d = x1 - x2 satisfiy abs(d) <= epsilon*(abs(x1)+abs(x2)).

                           Keywords 'chkxxxx'
By default, equal() compares structure component names for equality but
ignores coordinate labels or attached notes.  You can change this
behavior by including any of 'chknames:F', 'chklabels:T' and
'chknotes:T' as arguments.

                                Examples
Examples:
  Cmd> x1 <- .001*run(3); x2 <- x1 + 1e-10

  Cmd> equal(x1,x2) # exact equality test
  (1) F

  Cmd> equal(x1,x2,fuzz:1e-9) # absolute differences small enough
  (1) T

  Cmd> equal(x1,x2,fuzz:1e-9,relative:T) # relative difference too big
  (1) F

  Cmd> equal(asLong(run(3)), asLong(run(2,4)))
  (1) F

  Cmd> a <- run(3); b <- run(4); c <- vector(a,label:"A")

  Cmd> equal(a,b) # different shapes
  (1) F

  Cmd> equal(a,b,explain:T)
  component: equal
  (1) F
  component: reason
  (1) "Argument dimensions differ"

  Cmd> equal(a,c) # labels are ignorded by default
  (1) T

  Cmd> equal(a,c,chklabels:T,explain:T) # check labels for equality
  component: equal
  (1) F
  component: why
  (1) "Argument labels differ"

  Cmd> equal(structure(a,b),structure(c,b),explain:T)
  component: equal
  (1) F
  component: why
  (1) "Structure component [1] names differ"

  Cmd> equal(structure(a,b),structure(c,b),chknames:F)#ignore comp names
  (1) T

  Cmd> A <- structure(PI,structure(a)) # nested structures

  Cmd> B <- structure(PI,structure(b)) # nested structures

  Cmd> equal(A, B, explain:T) # compare nested structures
  component: equal
  (1) F
  component: why
  (1) "Structure component [2][1] dimensions differ"

In the last example, the explanation identifies the inequality as being
in structure component 1 of structure component 2 (A[2][1] differs from
B[2][1]).

                            Cross references
See also topics 'variables', 'arithmetic', 'logic', 'notes', 'labels',
structure(), 'structures'.


Gary Oehlert 2005-08-12