ListSame

Compares two lists and returns a boolean value.

Synopsis

ListSame(list1,list2)

Parameters

list1	An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List. The null string ("") is also treated as a valid list.
list2	An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List. The null string ("") is also treated as a valid list.

Description

ListSame compares the contents of two lists and returns 1 if the lists are identical. If the lists are not identical, ListSame returns 0. ListSame compares list elements using their string representations. ListSame comparisons are case-sensitive.

ListSame compares the two lists element-by-element in left-to-right order. Therefore ListSame returns a value of 0 when it encounters the first non-identical pair of list elements; it does not check subsequent items to determine if they are valid list elements. If a ListSame comparison encounters an invalid item, it issues a <LIST> error.

Examples

The following example returns 1, because the two lists are identical:

x = ListBuild("Red","Blue","Green")
y = ListBuild("Red","Blue","Green")
 PrintLn ListSame(x,y)

The following example returns 0, because the two lists are not identical:

 x = ListBuild("Red","Blue","Yellow")
 y = ListBuild("Red","Yellow","Blue")
 PrintLn ListSame(x,y)

Identical Lists

ListSame considers two lists to be identical if the string representations of the two lists are identical.

When comparing a numeric list element and a string list element, the string list element must represent the numeric in canonical form; this is because Caché always reduces numerics to canonical form before performing a comparison. In the following example, ListSame compares a string and a numeric. The first three ListSame functions return 1 (identical); the fourth ListSame function returns 0 (not identical) because the string representation is not in canonical form:

PrintLn ListSame(ListBuild("365"),ListBuild(365))
PrintLn ListSame(ListBuild("365"),ListBuild(365.0))
PrintLn ListSame(ListBuild("365.5"),ListBuild(365.5))
PrintLn ListSame(ListBuild("365.0"),ListBuild(365.0))

ListSame comparison is not the same equivalence test as the one used by other list operations, which test using the internal representation of a list. This distinction is easily seen when comparing a number and a numeric string, as in the following example:

 x = ListBuild("365")
 y = ListBuild(365)
   If x=y Then
      PrintLn "Equal sign: number/numeric string identical"
   Else
      PrintLn "Equal sign: number/numeric string differ"
   End If
   If 1=ListSame(x,y) Then
      PrintLn "ListSame: number/numeric string identical"
   Else
      PrintLn "ListSame: number/numeric string differ"
   End If

The equality (=) comparison tests the internal representations of these lists (which are not identical). ListSame performs a string conversion on both lists, compares them, and finds them identical.

The following example shows two lists with various representations of numeric elements. ListSame considers these two lists to be identical:

 x = ListBuild("360","361","362","363","364","365","366")
 y = ListBuild(00360.000,(19*19),+"362",363,364.0,+365,"3" & "66")
 PrintLn ListSame(x,y)," lists are identical"

Null String and Null List

A list containing the null string (an empty string) as its sole element is a valid list. The null string by itself is also considered a valid list. However these two (a null string and a null list) are not considered identical, as shown in the following example:

 PrintLn ListSame(ListBuild(""),ListBuild(""))," null lists"
 PrintLn ListSame("","")," null strings"
 PrintLn ListSame(ListBuild(""),"")," null list and null string"

Normally, a string is not a valid ListSame argument, and ListSame issues a <LIST> error. However, the following ListSame comparisons complete successfully and return 0 (values not identical). The null string and the string “abc” are compared and found not to be identical. These null string comparisons do not issue a <LIST> error:

 PrintLn ListSame("","abc")
 PrintLn ListSame("abc","")

The following ListSame comparisons do issue a <LIST> error, because a list (even a null list) cannot be compared with a string:

 x = ListBuild("")
 PrintLn ListSame("abc",x)
 PrintLn ListSame(x,"abc")

Comparing “Empty” Lists

ListValid considers all of the following as valid lists:

PrintLn ListValid("")
PrintLn ListValid(ListBuild())
PrintLn ListValid(ListBuild(NULL))
PrintLn ListValid(ListBuild(""))
PrintLn ListValid(ListBuild(Chr(0)))
PrintLn ListValid(ListBuild(,))

ListSame considers only the following pairs as identical:

PrintLn ListSame(ListBuild(),ListBuild(NULL))
PrintLn ListSame(ListBuild(,),ListBuild(NULL,NULL))
PrintLn ListSame(ListBuild(,),ListBuild() & ListBuild())

Empty Elements

A ListBuild can create empty elements by including extra commas between elements or appending one or more commas to either end of the element list. ListSame is aware of empty elements, and does not treat them as equivalent to null string elements.

The following ListSame examples all return 0 (not identical):

PrintLn ListSame(ListBuild(365,,367),ListBuild(365,367))
PrintLn ListSame(ListBuild(365,366,),ListBuild(365,366))
PrintLn ListSame(ListBuild(365,366,,),ListBuild(365,366,))
PrintLn ListSame(ListBuild(365,,367),ListBuild(365,"",367))

Nested and Concatenated Lists

ListSame does not support nested lists. It cannot compare two lists that contain lists, even if their contents are identical.

 x = ListBuild("365")
 y = ListBuild(365)
 PrintLn ListSame(x,y)," lists identical"
 PrintLn ListSame(ListBuild(x),ListBuild(y))," nested lists not identical"

In the following example, both ListSame comparisons returns 0, because these lists are not considered identical:

 x=ListBuild("Apple","Pear","Walnut","Pecan")
 y=ListBuild("Apple","Pear",ListBuild("Walnut","Pecan"))
 z=ListBuild("Apple","Pear","Walnut","Pecan","")
 PrintLn ListSame(x,y)," nested list"
 PrintLn ListSame(x,z)," null string is list item"

ListSame does support concatenated lists. The following example returns 1, because the lists are considered identical:

 x=ListBuild("Apple","Pear","Walnut","Pecan")
 y=ListBuild("Apple","Pear") & ListBuild("Walnut","Pecan")
 PrintLn ListSame(x,y)," concatenated list"