Changes done for v1.1.2.

Senthil Nathan · Senthil Nathan · commit 2ec911d9dc7d · 2021-10-16T18:23:45.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changes
 
+## v1.1.2
+* Oct/16/2021
+* Added a new function compare_tuple_attributes to compare the attribute values of two tuples that are based on the same schema and then give back a list containing the attribute names that have differing values in the two tuples being compared.
+
 ## v1.1.1
 * Sep/04/2021
 * Added two new operational verbs: equalsCI and notEqualsCI.
diff --git a/README.md b/README.md
@@ -106,14 +106,86 @@ if(error == 0) {
 // It is a void function that returns nothing.
 ```
 
+**compare_tuple_attributes** is another C++ native function provided via this toolkit. This function compares the attribute values of two tuples that are based on the same schema. It will give back a list containing attribute names that have differing values in the two tuples being compared. It supports primitive types (int32, float64, rstring etc.) as well as collection types (set, list and map). It also allows flat tuples as well as deeply nested tuples to be compared.
+
+```
+// This namespace usage declaration is needed at the top of an application.
+use com.ibm.streamsx.eval_predicate::*;
+
+// Schema can include other deeply nested types.
+type NestedType1_t = int32 x, float64 y, rstring z, list<int32> l;
+type NestedType2_t = NestedType1_t m, map<int32, boolean> n, timestamp o;
+type Test_t = boolean a, int32 b, uint64 c, float32 d, float64 e,
+              rstring f, set<int32> g, list<rstring> h, map<int32, rstring> i,
+              map<rstring, float64> j, NestedType2_t k;
+					
+// Create two tuples that are based on the same schema.
+mutable Test_t myTuple1 = {};
+mutable Test_t myTuple2 = {};
+mutable list<rstring> differingAttributes = [];
+					
+// Populate the tuple with some data.
+myTuple1.a = true;
+myTuple1.b = 456;
+myTuple1.c = 789ul;
+myTuple1.d = (float32)123.45;
+myTuple1.e = 987.65;
+myTuple1.f = "Life is mainly there to have fun.";
+myTuple1.g = {5, 9, 2, 6};
+myTuple1.h = ['One', 'Two', 'Three'];
+myTuple1.i = {1:'One', 2:'Two', 3:'Three'};
+myTuple1.j = {"One":1.0, "Two":2.0, "Three":3.0};
+myTuple1.k.m.x = 678;
+myTuple1.k.m.y = 936.27;
+myTuple1.k.m.z = "String inside a nested tuple.";
+myTuple1.k.m.l = [67, 78, 89];
+myTuple1.k.n = {1:true, 2:false, 3:true}; 
+myTuple1.k.o = getTimestamp();
+						
+// Make the second tuple same as the first tuple.
+myTuple2 = myTuple1;
+// Make some changes to certain attribute values in the second tuple.
+myTuple2.a = false;
+myTuple2.d = (float32)145.12;
+myTuple2.f = "Life is mainly there to have joy and peace.";
+myTuple2.i = {10:'Ten', 9:'Nine', 8:'Eight'};
+myTuple2.k.m.y = 27.93;
+myTuple2.k.m.z = "Different string inside a nested tuple.";
+myTuple2.k.n = {1:true, 2:true, 3:true};
+// Wait for 2 seconds for time to change.
+block(2.0);
+myTuple2.k.o = getTimestamp(); 
+					
+// Compare them now.
+compare_tuple_attributes(myTuple1, myTuple2, differingAttributes, 
+                         error, $EVAL_PREDICATE_TRACING);
+	    			
+if(error == 0) {
+   printStringLn("Compare tuple attributes function returned successfully. " +
+      "differingAttributes = " + (rstring)differingAttributes);
+} else {
+   printStringLn("Compare tuple attributes function returned an error. Error=" + (rstring)error);
+}
+					}
+// Following is the usage description for the get_tuple_attribute_value function.
+//
+// Arg1: Your tuple1
+// Arg2: Your tuple2
+// Arg3: A mutable variable of list<string> type in which the
+//       attribute names that differ in their values will be returned.
+// Arg4: A mutable int32 variable to receive non-zero error code if any.
+// Arg5: A boolean value to enable debug tracing inside this function.
+// It is a void function that returns nothing.
+```
+
 ## Design considerations
 This toolkit came into existence for a specific need with which a large enterprise customer approached the author of this toolkit. There is already a built-in function named *evalPredicate* that is available in the official IBM Streams product. However, that function has certain limitations. To fill that gap, this toolkit with its own **eval_predicate** function is being made available freely via the publicly accessible IBMStreams GitHub. The **eval_predicate** function from this toolkit differs from the *evalPredicate* built-in function in the IBM Streams product in the following ways.
 
 1. This new eval_predicate function allows the user defined rule expression to access map based tuple attributes.
 
 2. This new eval_predicate function allows the user defined rule expression to access nested tuple attributes.
 
-3. This new eval_predicate function allows the user defined rule expression to have operation verbs such as contains, startsWith, endsWith, notContains, notStartsWith, notEndsWith, in, containsCI, startsWithCI, endsWithCI, notContainsCI, notStartsWithCI, notEndsWithCI, inCI, sizeEQ, sizeNE, sizeLT, sizeLE, sizeGT, sizeGE.
+3. This new eval_predicate function allows the user defined rule expression to have operation verbs such as contains, startsWith, endsWith, notContains, notStartsWith, notEndsWith, in, containsCI, startsWithCI, endsWithCI, notContainsCI, notStartsWithCI, notEndsWithCI, inCI, equalsCI, notEqualsCI, sizeEQ, sizeNE, sizeLT, sizeLE, sizeGT, sizeGE.
 
 4. This new eval_predicate function supports the following operations inside the rule.
 
@@ -123,7 +195,7 @@ This toolkit came into existence for a specific need with which a large enterpri
 
    c. It supports these arithmetic operations: +, -, *, /, %
 
-   d. It supports these special operations for rstring, set, list and map: contains, startsWith, endsWith, notContains, notStartsWith, notEndsWith, in, containsCI, startsWithCI, endsWithCI, notContainsCI, notStartsWithCI, notEndsWithCI, inCI, sizeEQ, sizeNE, sizeLT, sizeLE, sizeGT, sizeGE
+   d. It supports these special operations for rstring, set, list and map: contains, startsWith, endsWith, notContains, notStartsWith, notEndsWith, in, containsCI, startsWithCI, endsWithCI, notContainsCI, notStartsWithCI, notEndsWithCI, inCI, equalsCI, notEqualsCI, sizeEQ, sizeNE, sizeLT, sizeLE, sizeGT, sizeGE
 
    e. No bitwise operations are supported at this time.
 
diff --git a/com.ibm.streamsx.eval_predicate/EvalPredicateExample.spl b/com.ibm.streamsx.eval_predicate/EvalPredicateExample.spl
@@ -8,7 +8,7 @@
 /*
 ==================================================================
 First created on: Mar/05/2021
-Last modified on: Sep/04/2021
+Last modified on: Oct/16/2021
 
 This is an example application that shows how to use the
 eval_predicate function to evaluate an SPL expression a.k.a
@@ -102,6 +102,13 @@ that is expressed via a user provided string input.
 In this example, you can search for get_tuple_attribute_value to
 see 10 different test cases on that topic.
 
+Another feature available in the eval_prediate toolkit is to
+compare the attribute values of two tuples that are made of
+the same schema and to return a list containing the 
+attribute names that differ in their values. In this example,
+you can search for compare_tuple_attributes to see a few
+test cases on that topic.
+
 How can you use this new eval_predicate function?
 -------------------------------------------------
 Any other application that wants to use this function must
@@ -392,6 +399,89 @@ composite EvalPredicateExample {
 						printStringLn("Testcase 2.6: Tuple attribute value was not fetched successfully. Error=" + (rstring)error);
 					}
 
+					// Compare the attribute values of two tuples that are based on the same schema.
+					// Arg1: Your tuple1
+					// Arg2: Your tuple2
+					// Arg3: A mutable variable of list<string> type in which the
+					//       attribute names that differ in their values will be returned.
+					// Arg4: A mutable int32 variable to receive non-zero error code if any.
+					// Arg5: A boolean value to enable debug tracing inside this function.
+					//
+					// 2.7
+					// Compare two tuples that have no differing attribute values.
+					//
+					// Declare a nested tuple data structure to be used in this test case.
+					type NestedType1_t = int32 x, float64 y, rstring z, list<int32> l;
+					type NestedType2_t = NestedType1_t m, map<int32, boolean> n, timestamp o;
+					type Test_t = boolean a, int32 b, uint64 c, float32 d, float64 e,
+						rstring f, set<int32> g, list<rstring> h, map<int32, rstring> i,
+						map<rstring, float64> j, NestedType2_t k;
+					
+					// Create two tuples that are based on the same schema.
+					mutable Test_t myTuple1 = {};
+					mutable Test_t myTuple2 = {};
+					mutable list<rstring> differingAttributes = [];
+					
+					// Populate the tuple with some data.
+					myTuple1.a = true;
+					myTuple1.b = 456;
+					myTuple1.c = 789ul;
+					myTuple1.d = (float32)123.45;
+					myTuple1.e = 987.65;
+					myTuple1.f = "Life is mainly there to have fun.";
+					myTuple1.g = {5, 9, 2, 6};
+					myTuple1.h = ['One', 'Two', 'Three'];
+					myTuple1.i = {1:'One', 2:'Two', 3:'Three'};
+					myTuple1.j = {"One":1.0, "Two":2.0, "Three":3.0};
+					myTuple1.k.m.x = 678;
+					myTuple1.k.m.y = 936.27;
+					myTuple1.k.m.z = "String inside a nested tuple.";
+					myTuple1.k.m.l = [67, 78, 89];
+					myTuple1.k.n = {1:true, 2:false, 3:true}; 
+					myTuple1.k.o = getTimestamp();
+						
+					// Make the second tuple same as the first tuple.
+					myTuple2 = myTuple1;
+					
+					// Compare them now.
+					compare_tuple_attributes(myTuple1, myTuple2,
+	    				differingAttributes, error, $EVAL_PREDICATE_TRACING);
+	    			
+					if(error == 0) {
+						printStringLn("Testcase 2.7: Compare tuple attributes function returned successfully. " +
+							"differingAttributes = " + (rstring)differingAttributes);
+					} else {
+						printStringLn("Testcase 2.7: Compare tuple attributes function returned an error. Error=" + (rstring)error);
+					}
+	    					
+					// 2.8
+					// Compare two tuples that have differing attribute values.
+					//
+					// Make the second tuple to have a few different attribute values than the first tuple.
+					myTuple2.a = false;
+					myTuple2.d = (float32)145.12;
+					myTuple2.f = "Life is mainly there to have joy and peace.";
+					myTuple2.i = {10:'Ten', 9:'Nine', 8:'Eight'};
+					myTuple2.k.m.y = 27.93;
+					myTuple2.k.m.z = "Different string inside a nested tuple.";
+					myTuple2.k.n = {1:true, 2:true, 3:true};
+					// Wait for 2 seconds for time to change.
+					block(2.0);
+					myTuple2.k.o = getTimestamp(); 
+					
+					// Clear the list.
+					differingAttributes = (list<rstring>)[];
+					// Compare them now.
+					compare_tuple_attributes(myTuple1, myTuple2,
+	    				differingAttributes, error, $EVAL_PREDICATE_TRACING);
+	    			
+					if(error == 0) {
+						printStringLn("Testcase 2.8: Compare tuple attributes function returned successfully. " +
+							"differingAttributes = " + (rstring)differingAttributes);
+					} else {
+						printStringLn("Testcase 2.8: Compare tuple attributes function returned an error. Error=" + (rstring)error);
+					}
+					
 					// ============== TESTCASE GROUP 3 ============== 
 					mutable City_t myCity = {};
 					myCity.name = "White Plains";
diff --git a/com.ibm.streamsx.eval_predicate/FunctionalTests.spl b/com.ibm.streamsx.eval_predicate/FunctionalTests.spl
@@ -8,7 +8,7 @@
 /*
 ==================================================================
 First created on: Mar/28/2021
-Last modified on: Sep/04/2021
+Last modified on: Oct/16/2021
 
 This application is meant for doing several hundred 
 functional tests to provide as much coverage as possible to 
@@ -40,6 +40,13 @@ that is expressed via a user provided string input.
 You can search below for get_tuple_attribute_value to
 see a few dozen different test cases on that topic.
 
+Another feature available in the eval_prediate toolkit is to
+compare the attribute values of two tuples that are made of
+the same schema and to return a list containing the 
+attribute names that differ in their values. In this example,
+you can search for compare_tuple_attributes to see a few
+test cases on that topic.
+
 How can you build this test application?
 ----------------------------------------
 1) If you are a command line person, you can use the
@@ -8242,6 +8249,11 @@ composite FunctionalTests {
 		
 		// In this operator, we will do tests for getting
 		// tuple attribute values in different ways.
+		// In addition, we will do test cases for comparing
+		// two tuples that are made of the same schema and
+		// then to return a list containing the attribute
+		// names that differ in their values across those
+		// two tuples.
 		() as FetchValueSink = Custom(MyTestData as MTD) {
 			logic
 				state: {
@@ -9042,6 +9054,90 @@ composite FunctionalTests {
 					} else {
 						printStringLn("Testcase C1.48: Tuple attribute value was not fetched successfully. Error=" + (rstring)error);
 					}
+					
+					// Compare the attribute values of two tuples that are based on the same schema.
+					// Arg1: Your tuple1
+					// Arg2: Your tuple2
+					// Arg3: A mutable variable of list<string> type in which the
+					//       attribute names that differ in their values will be returned.
+					// Arg4: A mutable int32 variable to receive non-zero error code if any.
+					// Arg5: A boolean value to enable debug tracing inside this function.
+					//
+					// C1.49
+					// Compare two tuples that have no differing attribute values.
+					//
+					// Declare a nested tuple data structure to be used in this test case.
+					type NestedType1_t = int32 x, float64 y, rstring z, list<int32> l;
+					type NestedType2_t = NestedType1_t m, map<int32, boolean> n, timestamp o;
+					type Test_t = boolean a, int32 b, uint64 c, float32 d, float64 e,
+						rstring f, set<int32> g, list<rstring> h, map<int32, rstring> i,
+						map<rstring, float64> j, NestedType2_t k;
+					
+					// Create two tuples that are based on the same schema.
+					mutable Test_t myTuple1 = {};
+					mutable Test_t myTuple2 = {};
+					mutable list<rstring> differingAttributes = [];
+					
+					// Populate the tuple with some data.
+					myTuple1.a = true;
+					myTuple1.b = 456;
+					myTuple1.c = 789ul;
+					myTuple1.d = (float32)123.45;
+					myTuple1.e = 987.65;
+					myTuple1.f = "Life is mainly there to have fun.";
+					myTuple1.g = {5, 9, 2, 6};
+					myTuple1.h = ['One', 'Two', 'Three'];
+					myTuple1.i = {1:'One', 2:'Two', 3:'Three'};
+					myTuple1.j = {"One":1.0, "Two":2.0, "Three":3.0};
+					myTuple1.k.m.x = 678;
+					myTuple1.k.m.y = 936.27;
+					myTuple1.k.m.z = "String inside a nested tuple.";
+					myTuple1.k.m.l = [67, 78, 89];
+					myTuple1.k.n = {1:true, 2:false, 3:true};
+					myTuple1.k.o = getTimestamp();
+
+					// Make the second tuple same as the first tuple.
+					myTuple2 = myTuple1;
+					
+					// Compare them now.
+					compare_tuple_attributes(myTuple1, myTuple2,
+	    				differingAttributes, error, $EVAL_PREDICATE_TRACING);
+	    			
+					if(error == 0) {
+						printStringLn("Testcase C1.49: Compare tuple attributes function returned successfully. " +
+							"differingAttributes = " + (rstring)differingAttributes);
+					} else {
+						printStringLn("Testcase C1.49: Compare tuple attributes function returned an error. Error=" + (rstring)error);
+					}
+	    					
+					// C1.50
+					// Compare two tuples that have differing attribute values.
+					//
+					// Make the second tuple to have a few different attribute values than the first tuple.
+					myTuple2.a = false;
+					myTuple2.d = (float32)145.12;
+					myTuple2.f = "Life is mainly there to have joy and peace.";
+					myTuple2.i = {10:'Ten', 9:'Nine', 8:'Eight'};
+					myTuple2.k.m.y = 27.93;
+					myTuple2.k.m.z = "Different string inside a nested tuple.";
+					myTuple2.k.n = {1:true, 2:true, 3:true}; 
+					// Wait for 2 seconds for time to change.
+					block(2.0);
+					myTuple2.k.o = getTimestamp(); 
+
+					// Clear the list.
+					differingAttributes = (list<rstring>)[];
+					// Compare them now.
+					compare_tuple_attributes(myTuple1, myTuple2,
+	    				differingAttributes, error, $EVAL_PREDICATE_TRACING);
+	    			
+					if(error == 0) {
+						printStringLn("Testcase C1.50: Compare tuple attributes function returned successfully. " +
+							"differingAttributes = " + (rstring)differingAttributes);
+					} else {
+						printStringLn("Testcase C1.50: Compare tuple attributes function returned an error. Error=" + (rstring)error);
+					}
+					
 					// -------------------------
 					
 					// Let us add below a few test cases for the
diff --git a/com.ibm.streamsx.eval_predicate/native.function/function.xml b/com.ibm.streamsx.eval_predicate/native.function/function.xml
@@ -28,6 +28,19 @@ It fetches the value of a user given attribute name if it is present in the user
 		</description>
         <prototype>&lt;tuple T1, any T2> public void get_tuple_attribute_value(rstring attributeName, T1 myTuple, mutable T2 value, mutable int32 error, boolean trace)</prototype>
       </function>
+      
+      <function>
+        <description>
+It compares the attribute values of two tuples that are made of the same schema and returns a list containing the attribute names that have differing values.
+@param myTuple1 First of the two user given tuples to be compared. Type: Tuple
+@param myTuple2 Second of the two user given tuples to be compared. Type: Tuple
+@param differingAttributes A mutable list variable that will contain the attribute names that have differing values. Type: list&lt;rstring&gt;
+@param error A mutable variable that will contain a non-zero error code if an error occurs. Type: int32 
+@param trace A boolean value to enable tracing inside this function. Type: boolean
+@return It returns nothing.  Type: void
+		</description>
+        <prototype>&lt;tuple T1> public void compare_tuple_attributes(T1 myTuple1, T1 myTuple2, mutable list&lt;rstring&gt; differingAttributes, mutable int32 error, boolean trace)</prototype>
+      </function>
     </functions>
     
     <dependencies>
diff --git a/impl/include/eval_predicate.h b/impl/include/eval_predicate.h
diff --git a/info.xml b/info.xml
