aimx/info_library/
set_cards.rs

1//! Set function documentation cards.
2//!
3//! Provides comprehensive FunctionCard instances for all 7 set manipulation
4//! functions in the Aim standard library, including detailed set theory
5//! explanations, practical examples, and performance characteristics.
6
7use super::function_card::{ArgumentInfo, FunctionCard};
8
9/// All set function documentation cards.
10pub const SET_CARDS: &[FunctionCard] = &[
11    // union(set_a, set_b) -> Vec<Value>
12    FunctionCard {
13        identifier: "union",
14        signature: "union(set_a, set_b)",
15        brief: "Return the union of two sets (all unique elements from both sets).",
16        description: "Combines elements from both input arrays into a single set containing \
17                     all unique elements. This operation implements the mathematical union \
18                     (A ∪ B) and is fundamental for merging datasets, combining categories, \
19                     or aggregating distinct values. The result maintains the order of \
20                     first occurrence while eliminating duplicates.",
21        arguments: &[
22            &ArgumentInfo {
23                label: "set_a",
24                description: "First array to include in union",
25                type_hint: "Array",
26                optional: false,
27            },
28            &ArgumentInfo {
29                label: "set_b",
30                description: "Second array to include in union",
31                type_hint: "Array",
32                optional: false,
33            },
34        ],
35        returns: "Array containing all unique elements from both sets",
36        errors: "Returns error if either argument is not an array",
37        categories: &["set", "collection"],
38        examples: &[
39            "union((1, 2, 3), (2, 3, 4)) => (1, 2, 3, 4)",
40            "union((\"a\", \"b\"), (\"b\", \"c\")) => (\"a\", \"b\", \"c\")",
41            "union((1, 2), ()) => (1, 2)",
42        ],
43    },
44    
45    // intersection(set_a, set_b) -> Vec<Value>
46    FunctionCard {
47        identifier: "intersection",
48        signature: "intersection(set_a, set_b)",
49        brief: "Return the intersection of two sets (elements common to both sets).",
50        description: "Finds elements that exist in both input arrays, implementing the \
51                     mathematical intersection (A ∩ B). This operation is essential for \
52                     finding common customers, shared features, overlapping schedules, \
53                     or any scenario where you need to identify what two datasets have \
54                     in common. The result preserves the order from the first set.",
55        arguments: &[
56            &ArgumentInfo {
57                label: "set_a",
58                description: "First array to find intersection with",
59                type_hint: "Array",
60                optional: false,
61            },
62            &ArgumentInfo {
63                label: "set_b",
64                description: "Second array to find intersection with",
65                type_hint: "Array",
66                optional: false,
67            },
68        ],
69        returns: "Array containing elements present in both sets",
70        errors: "Returns error if either argument is not an array",
71        categories: &["set", "collection"],
72        examples: &[
73            "intersection((1, 2, 3), (2, 3, 4)) => (2, 3)",
74            "intersection((\"a\", \"b\", \"c\"), (\"b\", \"c\", \"d\")) => (\"b\", \"c\")",
75            "intersection((1, 2), (3, 4)) => ()",
76        ],
77    },
78    
79    // difference(set_a, set_b) -> Vec<Value>
80    FunctionCard {
81        identifier: "difference",
82        signature: "difference(set_a, set_b)",
83        brief: "Return the difference of two sets (elements in first set but not in second).",
84        description: "Finds elements that exist in the first array but not in the second, \
85                     implementing the set difference (A - B). This operation is useful for \
86                     identifying what's unique to one dataset, finding removed items, \
87                     filtering out unwanted elements, or determining what needs to be added \
88                     to make sets equal. The result preserves the order from the first set.",
89        arguments: &[
90            &ArgumentInfo {
91                label: "set_a",
92                description: "Array to subtract from",
93                type_hint: "Array",
94                optional: false,
95            },
96            &ArgumentInfo {
97                label: "set_b",
98                description: "Array to subtract elements of",
99                type_hint: "Array",
100                optional: false,
101            },
102        ],
103        returns: "Array containing elements in first set but not in second",
104        errors: "Returns error if either argument is not an array",
105        categories: &["set", "collection"],
106        examples: &[
107            "difference((1, 2, 3, 4), (2, 4)) => (1, 3)",
108            "difference((\"a\", \"b\", \"c\"), (\"b\", \"d\")) => (\"a\", \"c\")",
109            "difference((1, 2), (1, 2, 3)) => ()",
110        ],
111    },
112    
113    // exclusive(set_a, set_b) -> Vec<Value>
114    FunctionCard {
115        identifier: "exclusive",
116        signature: "exclusive(set_a, set_b)",
117        brief: "Return the symmetric difference (elements in exactly one set).",
118        description: "Finds elements that exist in exactly one of the two arrays, \
119                     implementing the symmetric difference or exclusive or (A Δ B). \
120                     This operation is useful for finding changes between versions, \
121                     identifying unique characteristics, detecting differences, or \
122                     finding elements that distinguish one set from another. The result \
123                     combines elements unique to each set.",
124        arguments: &[
125            &ArgumentInfo {
126                label: "set_a",
127                description: "First array for symmetric difference",
128                type_hint: "Array",
129                optional: false,
130            },
131            &ArgumentInfo {
132                label: "set_b",
133                description: "Second array for symmetric difference",
134                type_hint: "Array",
135                optional: false,
136            },
137        ],
138        returns: "Array containing elements in exactly one set",
139        errors: "Returns error if either argument is not an array",
140        categories: &["set", "collection"],
141        examples: &[
142            "exclusive((1, 2, 3), (2, 3, 4)) => (1, 4)",
143            "exclusive((\"a\", \"b\"), (\"b\", \"c\")) => (\"a\", \"c\")",
144            "exclusive((1, 2), (1, 2)) => ()",
145        ],
146    },
147    
148    // is_subset(set_a, set_b) -> bool
149    FunctionCard {
150        identifier: "is_subset",
151        signature: "is_subset(set_a, set_b)",
152        brief: "Test if first set is a subset of second set.",
153        description: "Determines whether all elements of the first array are contained \
154                     within the second array, implementing the subset relationship (A ⊆ B). \
155                     This operation is useful for permission checking, requirement \
156                     validation, category testing, or verifying that one dataset is \
157                     completely contained within another. Returns true if the first set \
158                     is a subset, false otherwise.",
159        arguments: &[
160            &ArgumentInfo {
161                label: "set_a",
162                description: "Potential subset to test",
163                type_hint: "Array",
164                optional: false,
165            },
166            &ArgumentInfo {
167                label: "set_b",
168                description: "Set to test against",
169                type_hint: "Array",
170                optional: false,
171            },
172        ],
173        returns: "Boolean indicating if first set is subset of second",
174        errors: "Returns error if either argument is not an array",
175        categories: &["set", "logical"],
176        examples: &[
177            "is_subset((1, 2), (1, 2, 3, 4)) => true",
178            "is_subset((1, 5), (1, 2, 3, 4)) => false",
179            "is_subset((), (1, 2, 3)) => true",
180        ],
181    },
182    
183    // set_equals(set_a, set_b) -> bool
184    FunctionCard {
185        identifier: "set_equals",
186        signature: "set_equals(set_a, set_b)",
187        brief: "Test if two sets contain exactly the same elements.",
188        description: "Determines whether two arrays contain exactly the same elements, \
189                     implementing set equality (A = B). This operation ignores order and \
190                     duplicates, focusing only on the unique elements present. It is \
191                     useful for comparing datasets, validating results, checking for \
192                     equivalence, or ensuring data consistency between sources.",
193        arguments: &[
194            &ArgumentInfo {
195                label: "set_a",
196                description: "First set to compare",
197                type_hint: "Array",
198                optional: false,
199            },
200            &ArgumentInfo {
201                label: "set_b",
202                description: "Second set to compare",
203                type_hint: "Array",
204                optional: false,
205            },
206        ],
207        returns: "Boolean indicating if sets contain same elements",
208        errors: "Returns error if either argument is not an array",
209        categories: &["set", "logical"],
210        examples: &[
211            "set_equals((1, 2, 3), (3, 2, 1)) => true",
212            "set_equals((1, 2), (1, 2, 3)) => false",
213            "set_equals((1, 1, 2), (2, 1)) => true",
214        ],
215    },
216    
217    // overlaps(set_a, set_b) -> bool
218    FunctionCard {
219        identifier: "overlaps",
220        signature: "overlaps(set_a, set_b)",
221        brief: "Test if two sets share any common elements.",
222        description: "Determines whether two arrays have at least one element in common, \
223                     testing for set intersection without computing the full intersection. \
224                     This operation is useful for conflict detection, overlap checking, \
225                     compatibility testing, or determining if datasets have any relationship. \
226                     More efficient than computing intersection when only boolean result needed.",
227        arguments: &[
228            &ArgumentInfo {
229                label: "set_a",
230                description: "First set to test for overlap",
231                type_hint: "Array",
232                optional: false,
233            },
234            &ArgumentInfo {
235                label: "set_b",
236                description: "Second set to test for overlap",
237                type_hint: "Array",
238                optional: false,
239            },
240        ],
241        returns: "Boolean indicating if sets share any elements",
242        errors: "Returns error if either argument is not an array",
243        categories: &["set", "logical"],
244        examples: &[
245            "overlaps((1, 2, 3), (3, 4, 5)) => true",
246            "overlaps((1, 2), (3, 4)) => false",
247            "overlaps((\"a\", \"b\"), (\"b\", \"c\")) => true",
248        ],
249    },
250];
aimx/info_library/set_cards.rs

aimx/info_library/
set_cards.rs
