isequal tests the strict global equality between several objects, without equivalences

## Syntax

                t = isequal(a, b, ...)

## Arguments

a, b, ...

  objects: variable of any types ; expressions of any types of results.

t

  single boolean.

## Description

`isequal` compares its arguments. If all of them are equal then the function returns `%t`. Otherwise it returns `%f`.

2 objects `a` and `b` are equal whether they fulfill ALL the following conditions:

- they must have the same type of containers: both are matrices or hypermatrices with the same data types, or lists, or cells arrays, or structures arrays, or any mlists or tlists of same types.
- they must have the same sizes.
- they must have the same encoding: boolean, int8, uint8, int16, uint16, int32, uint32, int64, uint64, decimal, complex, sparse
- If they are mlists or tlists such as structures, they must have the same fields in the same order.
- They must have the same contents, the same values at the same places.
  `1/%z == -1/(-%z)` returns `%T`, while `1/%z == 2/(2*%z)`, `isequal(1/%z, -1/(-%z))` and `isequal(1/%z, 2/(2*%z))` are `%F`.

If at least one of these conditions is not fulfilled, the objects are considered not equal.

When comparing nested heterogeneous containers like lists, structures, cells, etc, comparisons are performed recursively.

With `isequal`, 2 compared NaN values are always considered not equal, according to the IEEE rule.

Comparing two objects including NaN values and considering that all NaN are equal can be done with `[ans,msg]=assert_checkequal(…)`.

## Examples

Comparisons answering %T (objects are equal):

    a = [1 2];
    isequal(a, [1 2])
    isequal(a, 1)
    isequal([1<2, %pi>%e], [3<10, %e>1])
    isequal(-0, +0)
    isequal([-%inf %inf], [-%inf %inf])
    isequal(%z, poly(0,"z"), poly([0 1], "z", "coeff"))

    // Functions "handles" can be compared:
    s = sin;   isequal(s, sin)   // Built-in function
    c = cosd;  isequal(c, cosd)  // Scilab function

    // Comparisons are done recursively (here in nested lists):
    L = list(%pi, "test", list(%t, 1/%z, 7), sin);
    n = %pi; t = "test"; r = 1/%z; s = sin;
    isequal(L, list(n, t, list(%t,r,7), s))

Comparisons answering %F (objects are NOT equal):

    // 1) Containers must be identical:
    isequal([1 %pi], {1, %pi})
    isequal([1 %pi], list(1, %pi))

    // 2) Encodings must be identical:
    isequal([1 7], int8([1 7]))
    isequal(uint8([1 7]), int8([1 7]))
    isequal(int8([1 7]), int16([1 7]))

    and([1 0]==[1 0*%i]) // is %T, but not as objects:
    //isequal([1 0], [1 0*%i])  // bug https://gitlab.com/scilab/scilab/-/issues/9153#note_1126223590

    p = (1+%z)^3
    pc = p + 0*%i
    p==pc
    //isequal(p, pc)           // bug https://gitlab.com/scilab/scilab/-/issues/9153#note_1126223590

    s = sprand(10,10,0.1); and(s==full(s)) // is %T, but not as objects:
    isequal(s, full(s))

    // 3) Sizes must be identical:
    isequal([7 11], [7 11]')

    // 4) fields of tlists or of mlists such as structures must be in the same order:
    s1 = struct("r", %pi,     "t", "Hello")
    s2 = struct("t", "Hello", "r", %pi)
    //isequal(s1,s2)           // bug https://gitlab.com/scilab/scilab/-/issues/9153#note_1126223613

Results for objects including NaN values:

    %nan == %nan                          // %F
    isequal(%nan, %nan)                   // %F
    isequal([3 %nan], [3 %nan])           // %F
    assert_checkequal([3 %nan], [3 %nan]) // %T

    L = list(3, "test", %z, list(1, %nan, %T));
    isequal(L, L)                         // %F
    assert_checkequal(L, L)               // %T

## See also

- ==
- strcmp
- NaN
- assert_checkequal
- assert_checkfilesequal
- intersect

## History

6.0.0 `isequalbitwise(…)` removed. `[ans,msg]=assert_checkequal(a,b)` may be used instead.