aimx/info_library/
math_cards.rs

1//! Mathematical function documentation cards.
2//!
3//! Provides comprehensive FunctionCard instances for all 38 mathematical functions
4//! and constants in the Aim standard library, including detailed usage examples
5//! and mathematical context.
6
7use super::function_card::{ArgumentInfo, FunctionCard};
8
9/// All math function documentation cards.
10pub const MATH_CARDS: &[FunctionCard] = &[
11    // Basic Arithmetic Functions (9)
12    
13    // abs(x) -> f64
14    FunctionCard {
15        identifier: "abs",
16        signature: "abs(x)",
17        brief: "Return the absolute value of a number.",
18        description: "Returns the non-negative value of the input number, removing any sign. \
19                     For positive numbers and zero, returns the same value. For negative \
20                     numbers, returns the positive equivalent. This function is useful for \
21                     calculating distances, magnitudes, and working with values that should \
22                     always be positive.",
23        arguments: &[
24            &ArgumentInfo {
25                label: "x",
26                description: "Number to get absolute value of",
27                type_hint: "f64",
28                optional: false,
29            },
30        ],
31        returns: "Absolute value (f64)",
32        errors: "None - always succeeds",
33        categories: &["math"],
34        examples: &[
35            "abs(-5.7) => 5.7",
36            "abs(3.14) => 3.14",
37            "abs(0) => 0",
38        ],
39    },
40    
41    // sign(x) -> f64
42    FunctionCard {
43        identifier: "sign",
44        signature: "sign(x)",
45        brief: "Return the sign of a number (-1, 0, or 1).",
46        description: "Returns -1 for negative numbers, 0 for zero, and 1 for positive numbers. \
47                     This function is useful for determining the direction of a value, \
48                     implementing sign-based logic, or normalizing vectors while preserving \
49                     direction.",
50        arguments: &[
51            &ArgumentInfo {
52                label: "x",
53                description: "Number to get sign of",
54                type_hint: "f64",
55                optional: false,
56            },
57        ],
58        returns: "Sign value (-1, 0, or 1) (f64)",
59        errors: "None - always succeeds",
60        categories: &["math"],
61        examples: &[
62            "sign(-5) => -1",
63            "sign(0) => 0",
64            "sign(7.5) => 1",
65        ],
66    },
67    
68    // floor(x) -> f64
69    FunctionCard {
70        identifier: "floor",
71        signature: "floor(x)",
72        brief: "Round down to the nearest integer.",
73        description: "Returns the largest integer less than or equal to the input value. \
74                     This function is useful for discretizing continuous values, implementing \
75                     grid-based systems, or truncating decimal portions while always rounding \
76                     down (towards negative infinity).",
77        arguments: &[
78            &ArgumentInfo {
79                label: "x",
80                description: "Number to round down",
81                type_hint: "f64",
82                optional: false,
83            },
84        ],
85        returns: "Floored value (f64)",
86        errors: "None - always succeeds",
87        categories: &["math"],
88        examples: &[
89            "floor(3.7) => 3",
90            "floor(-2.3) => -3",
91            "floor(5) => 5",
92        ],
93    },
94    
95    // ceil(x) -> f64
96    FunctionCard {
97        identifier: "ceil",
98        signature: "ceil(x)",
99        brief: "Round up to the nearest integer.",
100        description: "Returns the smallest integer greater than or equal to the input value. \
101                     This function is useful for discretizing continuous values, calculating \
102                     minimum container sizes, or truncating decimal portions while always \
103                     rounding up (towards positive infinity).",
104        arguments: &[
105            &ArgumentInfo {
106                label: "x",
107                description: "Number to round up",
108                type_hint: "f64",
109                optional: false,
110            },
111        ],
112        returns: "Ceiling value (f64)",
113        errors: "None - always succeeds",
114        categories: &["math"],
115        examples: &[
116            "ceil(3.2) => 4",
117            "ceil(-2.7) => -2",
118            "ceil(5) => 5",
119        ],
120    },
121    
122    // round(x) -> f64
123    FunctionCard {
124        identifier: "round",
125        signature: "round(x)",
126        brief: "Round to the nearest integer.",
127        description: "Returns the integer closest to the input value. Values ending in .5 are \
128                     rounded away from zero. This function is useful for normalizing decimal \
129                     values to whole numbers, implementing rounding rules, or reducing \
130                     precision for display purposes.",
131        arguments: &[
132            &ArgumentInfo {
133                label: "x",
134                description: "Number to round",
135                type_hint: "f64",
136                optional: false,
137            },
138        ],
139        returns: "Rounded value (f64)",
140        errors: "None - always succeeds",
141        categories: &["math"],
142        examples: &[
143            "round(3.7) => 4",
144            "round(3.2) => 3",
145            "round(-2.5) => -3",
146        ],
147    },
148    
149    // trunc(x) -> f64
150    FunctionCard {
151        identifier: "trunc",
152        signature: "trunc(x)",
153        brief: "Remove the decimal part of a number.",
154        description: "Returns the integer part of the input value by removing all decimal \
155                     digits. This function always rounds towards zero, effectively truncating \
156                     the number. It's useful for extracting whole number components, implementing \
157                     integer division, or removing fractional parts without rounding.",
158        arguments: &[
159            &ArgumentInfo {
160                label: "x",
161                description: "Number to truncate",
162                type_hint: "f64",
163                optional: false,
164            },
165        ],
166        returns: "Truncated value (f64)",
167        errors: "None - always succeeds",
168        categories: &["math"],
169        examples: &[
170            "trunc(3.7) => 3",
171            "trunc(-2.9) => -2",
172            "trunc(5) => 5",
173        ],
174    },
175    
176    // min(array) -> f64
177    FunctionCard {
178        identifier: "min",
179        signature: "min(array)",
180        brief: "Return the minimum value from an array.",
181        description: "Finds and returns the smallest numeric value in the input array. For \
182                     empty arrays, returns positive infinity. This function is useful for \
183                     finding extremes in data sets, implementing bounds checking, or \
184                     determining minimum requirements.",
185        arguments: &[
186            &ArgumentInfo {
187                label: "array",
188                description: "Array of numbers to find minimum of",
189                type_hint: "Vec<f64>",
190                optional: false,
191            },
192        ],
193        returns: "Minimum value (f64)",
194        errors: "None - always succeeds",
195        categories: &["math", "aggregate"],
196        examples: &[
197            "min((1, 5, 3, 9, 2)) => 1",
198            "min((-10, -5, -1)) => -10",
199            "min((42)) => 42",
200        ],
201    },
202    
203    // max(array) -> f64
204    FunctionCard {
205        identifier: "max",
206        signature: "max(array)",
207        brief: "Return the maximum value from an array.",
208        description: "Finds and returns the largest numeric value in the input array. For \
209                     empty arrays, returns negative infinity. This function is useful for \
210                     finding extremes in data sets, implementing bounds checking, or \
211                     determining maximum capabilities.",
212        arguments: &[
213            &ArgumentInfo {
214                label: "array",
215                description: "Array of numbers to find maximum of",
216                type_hint: "Vec<f64>",
217                optional: false,
218            },
219        ],
220        returns: "Maximum value (f64)",
221        errors: "None - always succeeds",
222        categories: &["math", "aggregate"],
223        examples: &[
224            "max((1, 5, 3, 9, 2)) => 9",
225            "max((-10, -5, -1)) => -1",
226            "max((42)) => 42",
227        ],
228    },
229    
230    // clamp(x, min, max) -> f64
231    FunctionCard {
232        identifier: "clamp",
233        signature: "clamp(x, min, max)",
234        brief: "Constrain a value to a specified range.",
235description: "Limits the input value to lie within the specified minimum and maximum \
236                      bounds. If the value is below the minimum, returns the minimum. If the \
237                      value is above the maximum, returns the maximum. Otherwise, returns the \
238                      original value. This function is useful for implementing bounds checking, \
239                      normalizing values, or preventing overflow. See also: lerp.",
240        arguments: &[
241            &ArgumentInfo {
242                label: "x",
243                description: "Value to constrain",
244                type_hint: "f64",
245                optional: false,
246            },
247            &ArgumentInfo {
248                label: "min",
249                description: "Minimum allowed value",
250                type_hint: "f64",
251                optional: false,
252            },
253            &ArgumentInfo {
254                label: "max",
255                description: "Maximum allowed value",
256                type_hint: "f64",
257                optional: false,
258            },
259        ],
260        returns: "Clamped value (f64)",
261        errors: "None - always succeeds",
262        categories: &["math"],
263        examples: &[
264            "clamp(5, 1, 10) => 5",
265            "clamp(15, 1, 10) => 10",
266            "clamp(-3, 1, 10) => 1",
267        ],
268    },
269    
270    // Power & Roots Functions (4)
271    
272    // sqrt(x) -> f64
273    FunctionCard {
274        identifier: "sqrt",
275        signature: "sqrt(x)",
276        brief: "Calculate the square root of a number.",
277        description: "Returns the non-negative square root of the input value. For negative \
278                     inputs, returns NaN (Not a Number). This function is useful for \
279                     calculating distances, implementing geometric formulas, or solving \
280                     quadratic equations.",
281        arguments: &[
282            &ArgumentInfo {
283                label: "x",
284                description: "Non-negative number to find square root of",
285                type_hint: "f64",
286                optional: false,
287            },
288        ],
289        returns: "Square root value (f64)",
290        errors: "Returns NaN for negative inputs",
291        categories: &["math"],
292        examples: &[
293            "sqrt(16) => 4",
294            "sqrt(2) => 1.4142135623730951",
295            "sqrt(0) => 0",
296        ],
297    },
298    
299    // pow(base, exponent) -> f64
300    FunctionCard {
301        identifier: "pow",
302        signature: "pow(base, exponent)",
303        brief: "Raise a number to a power.",
304        description: "Calculates the base number raised to the specified exponent. This \
305                     function supports both integer and fractional exponents, enabling \
306                     calculations like squares, cubes, square roots, and arbitrary powers. \
307                     It's fundamental for exponential growth calculations, compound interest, \
308                     and scientific notation.",
309        arguments: &[
310            &ArgumentInfo {
311                label: "base",
312                description: "Base number to raise to a power",
313                type_hint: "f64",
314                optional: false,
315            },
316            &ArgumentInfo {
317                label: "exponent",
318                description: "Power to raise the base to",
319                type_hint: "f64",
320                optional: false,
321            },
322        ],
323        returns: "Power result (f64)",
324        errors: "None - always succeeds",
325        categories: &["math"],
326        examples: &[
327            "pow(2, 3) => 8",
328            "pow(4, 0.5) => 2",
329            "pow(10, -2) => 0.01",
330        ],
331    },
332    
333    // exp(x) -> f64
334    FunctionCard {
335        identifier: "exp",
336        signature: "exp(x)",
337        brief: "Calculate e raised to the power of x.",
338        description: "Returns e (Euler's number, approximately 2.71828) raised to the power \
339                     of the input value. This function is fundamental in exponential growth \
340                     and decay models, compound interest calculations, probability distributions, \
341                     and many areas of science and engineering.",
342        arguments: &[
343            &ArgumentInfo {
344                label: "x",
345                description: "Exponent for e",
346                type_hint: "f64",
347                optional: false,
348            },
349        ],
350        returns: "e^x result (f64)",
351        errors: "None - always succeeds",
352        categories: &["math"],
353        examples: &[
354            "exp(0) => 1",
355            "exp(1) => 2.718281828459045",
356            "exp(2) => 7.38905609893065",
357        ],
358    },
359    
360    // exp2(x) -> f64
361    FunctionCard {
362        identifier: "exp2",
363        signature: "exp2(x)",
364        brief: "Calculate 2 raised to the power of x.",
365        description: "Returns 2 raised to the power of the input value. This function is \
366                     commonly used in computer science for calculating memory sizes, \
367                     implementing binary algorithms, and working with powers of two. It's \
368                     particularly useful for bit manipulation and binary tree calculations.",
369        arguments: &[
370            &ArgumentInfo {
371                label: "x",
372                description: "Exponent for 2",
373                type_hint: "f64",
374                optional: false,
375            },
376        ],
377        returns: "2^x result (f64)",
378        errors: "None - always succeeds",
379        categories: &["math"],
380        examples: &[
381            "exp2(3) => 8",
382            "exp2(10) => 1024",
383            "exp2(-1) => 0.5",
384        ],
385    },
386    
387    // Logarithmic Functions (4)
388    
389    // ln(x) -> f64
390    FunctionCard {
391        identifier: "ln",
392        signature: "ln(x)",
393        brief: "Calculate the natural logarithm (base e).",
394description: "Returns the natural logarithm of the input value, which is the logarithm \
395                      to the base e (Euler's number). This function is fundamental in calculus, \
396                      exponential growth/decay models, and many scientific applications. It's \
397                      the inverse of the exp function. See also: log10, log2, exp.",
398        arguments: &[
399            &ArgumentInfo {
400                label: "x",
401                description: "Positive number to find natural log of",
402                type_hint: "f64",
403                optional: false,
404            },
405        ],
406        returns: "Natural logarithm (f64)",
407        errors: "Returns NaN for non-positive inputs",
408        categories: &["math"],
409        examples: &[
410            "ln(E) => 1",
411            "ln(1) => 0",
412            "ln(7.389) => 2",
413        ],
414    },
415    
416    // log10(x) -> f64
417    FunctionCard {
418        identifier: "log10",
419        signature: "log10(x)",
420        brief: "Calculate the base-10 logarithm.",
421        description: "Returns the logarithm of the input value to base 10. This function is \
422                     commonly used in scientific calculations, pH calculations, decibel \
423                     measurements, and when working with orders of magnitude. It's useful \
424                     for compressing large ranges of values into manageable scales. See also: ln, log2.",
425        arguments: &[
426            &ArgumentInfo {
427                label: "x",
428                description: "Positive number to find base-10 log of",
429                type_hint: "f64",
430                optional: false,
431            },
432        ],
433        returns: "Base-10 logarithm (f64)",
434        errors: "Returns NaN for non-positive inputs",
435        categories: &["math"],
436        examples: &[
437            "log10(100) => 2",
438            "log10(1000) => 3",
439            "log10(1) => 0",
440        ],
441    },
442    
443    // log2(x) -> f64
444    FunctionCard {
445        identifier: "log2",
446        signature: "log2(x)",
447        brief: "Calculate the base-2 logarithm.",
448description: "Returns the logarithm of the input value to base 2. This function is \
449                      essential in computer science for analyzing algorithm complexity, \
450                      calculating binary tree depths, determining memory requirements, and \
451                      working with binary data structures. It's the inverse of the exp2 function. See also: ln, log10.",
452        arguments: &[
453            &ArgumentInfo {
454                label: "x",
455                description: "Positive number to find base-2 log of",
456                type_hint: "f64",
457                optional: false,
458            },
459        ],
460        returns: "Base-2 logarithm (f64)",
461        errors: "Returns NaN for non-positive inputs",
462        categories: &["math"],
463        examples: &[
464            "log2(8) => 3",
465            "log2(1024) => 10",
466            "log2(1) => 0",
467        ],
468    },
469    
470    // log(x) -> f64 (alias for ln)
471    FunctionCard {
472        identifier: "log",
473        signature: "log(x)",
474        brief: "Calculate the natural logarithm (alias for ln).",
475        description: "Returns the natural logarithm of the input value, identical to the ln \
476                     function. This alias provides compatibility with mathematical notation \
477                     where 'log' commonly refers to the natural logarithm, especially in \
478                     advanced mathematics and scientific contexts.",
479        arguments: &[
480            &ArgumentInfo {
481                label: "x",
482                description: "Positive number to find natural log of",
483                type_hint: "f64",
484                optional: false,
485            },
486        ],
487        returns: "Natural logarithm (f64)",
488        errors: "Returns NaN for non-positive inputs",
489        categories: &["math"],
490        examples: &[
491            "log(E) => 1",
492            "log(1) => 0",
493            "log(7.389) => 2",
494        ],
495    },
496    
497    // Trigonometric Functions (9)
498    
499    // sin(x) -> f64
500    FunctionCard {
501        identifier: "sin",
502        signature: "sin(x)",
503        brief: "Calculate the sine of an angle in radians.",
504description: "Returns the sine of the input angle, where the angle is specified in \
505                      radians. The sine function is fundamental in trigonometry, representing \
506                      the ratio of the opposite side to the hypotenuse in a right triangle. \
507                      It's used extensively in physics, engineering, and graphics programming. See also: cos, tan, asin.",
508        arguments: &[
509            &ArgumentInfo {
510                label: "x",
511                description: "Angle in radians",
512                type_hint: "f64",
513                optional: false,
514            },
515        ],
516        returns: "Sine value (f64)",
517        errors: "None - always succeeds",
518        categories: &["math"],
519        examples: &[
520            "sin(0) => 0",
521            "sin(PI/2) => 1",
522            "sin(PI) => 0",
523        ],
524    },
525    
526    // cos(x) -> f64
527    FunctionCard {
528        identifier: "cos",
529        signature: "cos(x)",
530        brief: "Calculate the cosine of an angle in radians.",
531description: "Returns the cosine of the input angle, where the angle is specified in \
532                      radians. The cosine function is fundamental in trigonometry, representing \
533                      the ratio of the adjacent side to the hypotenuse in a right triangle. \
534                      It's used extensively in physics, engineering, and graphics programming. See also: sin, tan, acos.",
535        arguments: &[
536            &ArgumentInfo {
537                label: "x",
538                description: "Angle in radians",
539                type_hint: "f64",
540                optional: false,
541            },
542        ],
543        returns: "Cosine value (f64)",
544        errors: "None - always succeeds",
545        categories: &["math"],
546        examples: &[
547            "cos(0) => 1",
548            "cos(PI/2) => 0",
549            "cos(PI) => -1",
550        ],
551    },
552    
553    // tan(x) -> f64
554    FunctionCard {
555        identifier: "tan",
556        signature: "tan(x)",
557        brief: "Calculate the tangent of an angle in radians.",
558description: "Returns the tangent of the input angle, where the angle is specified in \
559                      radians. The tangent function represents the ratio of sine to cosine, \
560                      or the ratio of the opposite side to the adjacent side in a right triangle. \
561                      It has vertical asymptotes at odd multiples of π/2. See also: sin, cos, atan.",
562        arguments: &[
563            &ArgumentInfo {
564                label: "x",
565                description: "Angle in radians",
566                type_hint: "f64",
567                optional: false,
568            },
569        ],
570        returns: "Tangent value (f64)",
571        errors: "Returns NaN at odd multiples of π/2",
572        categories: &["math"],
573        examples: &[
574            "tan(0) => 0",
575            "tan(PI/4) => 1",
576            "tan(PI) => 0",
577        ],
578    },
579    
580    // asin(x) -> f64
581    FunctionCard {
582        identifier: "asin",
583        signature: "asin(x)",
584        brief: "Calculate the arcsine (inverse sine) in radians.",
585description: "Returns the angle in radians whose sine is the input value. The result \
586                      is in the range [-π/2, π/2]. This function is the inverse of sin and is \
587                      used to find angles when the sine value is known. It's commonly used in \
588                      triangulation and inverse kinematics. See also: sin, cos, tan.",
589        arguments: &[
590            &ArgumentInfo {
591                label: "x",
592                description: "Sine value (must be between -1 and 1)",
593                type_hint: "f64",
594                optional: false,
595            },
596        ],
597        returns: "Angle in radians (f64)",
598        errors: "Returns NaN for inputs outside [-1, 1]",
599        categories: &["math"],
600        examples: &[
601            "asin(0) => 0",
602            "asin(1) => PI/2",
603            "asin(-1) => -PI/2",
604        ],
605    },
606    
607    // acos(x) -> f64
608    FunctionCard {
609        identifier: "acos",
610        signature: "acos(x)",
611        brief: "Calculate the arccosine (inverse cosine) in radians.",
612description: "Returns the angle in radians whose cosine is the input value. The result \
613                      is in the range [0, π]. This function is the inverse of cos and is used \
614                      to find angles when the cosine value is known. It's commonly used in \
615                      triangulation and computer graphics. See also: cos, sin, tan.",
616        arguments: &[
617            &ArgumentInfo {
618                label: "x",
619                description: "Cosine value (must be between -1 and 1)",
620                type_hint: "f64",
621                optional: false,
622            },
623        ],
624        returns: "Angle in radians (f64)",
625        errors: "Returns NaN for inputs outside [-1, 1]",
626        categories: &["math"],
627        examples: &[
628            "acos(1) => 0",
629            "acos(0) => PI/2",
630            "acos(-1) => PI",
631        ],
632    },
633    
634    // atan(x) -> f64
635    FunctionCard {
636        identifier: "atan",
637        signature: "atan(x)",
638        brief: "Calculate the arctangent (inverse tangent) in radians.",
639description: "Returns the angle in radians whose tangent is the input value. The result \
640                      is in the range [-π/2, π/2]. This function is the inverse of tan and is \
641                      used to find angles when the tangent value is known. It's commonly used \
642                      in coordinate conversion and slope calculations. See also: tan, atan2.",
643        arguments: &[
644            &ArgumentInfo {
645                label: "x",
646                description: "Tangent value",
647                type_hint: "f64",
648                optional: false,
649            },
650        ],
651        returns: "Angle in radians (f64)",
652        errors: "None - always succeeds",
653        categories: &["math"],
654        examples: &[
655            "atan(0) => 0",
656            "atan(1) => PI/4",
657            "atan(∞) => PI/2",
658        ],
659    },
660    
661    // atan2(y, x) -> f64
662    FunctionCard {
663        identifier: "atan2",
664        signature: "atan2(y, x)",
665        brief: "Calculate the arctangent of y/x with proper quadrant handling.",
666description: "Returns the angle in radians between the positive x-axis and the point \
667                      (x, y). Unlike atan, this function considers the signs of both arguments \
668                      to determine the correct quadrant, providing results in the range [-π, π]. \
669                      It's essential for converting Cartesian coordinates to polar coordinates. See also: atan.",
670        arguments: &[
671            &ArgumentInfo {
672                label: "y",
673                description: "Y-coordinate",
674                type_hint: "f64",
675                optional: false,
676            },
677            &ArgumentInfo {
678                label: "x",
679                description: "X-coordinate",
680                type_hint: "f64",
681                optional: false,
682            },
683        ],
684        returns: "Angle in radians (f64)",
685        errors: "None - always succeeds",
686        categories: &["math"],
687        examples: &[
688            "atan2(1, 1) => PI/4",
689            "atan2(0, -1) => PI",
690            "atan2(-1, 0) => -PI/2",
691        ],
692    },
693    
694    // sinh(x) -> f64
695    FunctionCard {
696        identifier: "sinh",
697        signature: "sinh(x)",
698        brief: "Calculate the hyperbolic sine.",
699description: "Returns the hyperbolic sine of the input value. Hyperbolic functions are \
700                      analogs of trigonometric functions but for a hyperbola rather than a \
701                      circle. The hyperbolic sine is defined as (e^x - e^(-x))/2 and appears \
702                      in solutions to differential equations and physics problems. See also: cosh, tanh.",
703        arguments: &[
704            &ArgumentInfo {
705                label: "x",
706                description: "Input value",
707                type_hint: "f64",
708                optional: false,
709            },
710        ],
711        returns: "Hyperbolic sine value (f64)",
712        errors: "None - always succeeds",
713        categories: &["math"],
714        examples: &[
715            "sinh(0) => 0",
716            "sinh(1) => 1.1752011936438014",
717            "sinh(-1) => -1.1752011936438014",
718        ],
719    },
720    
721    // cosh(x) -> f64
722    FunctionCard {
723        identifier: "cosh",
724        signature: "cosh(x)",
725        brief: "Calculate the hyperbolic cosine.",
726description: "Returns the hyperbolic cosine of the input value. The hyperbolic cosine \
727                      is defined as (e^x + e^(-x))/2 and represents the shape of a hanging \
728                      chain or cable (catenary curve). It's used in physics, engineering, and \
729                      special relativity calculations. See also: sinh, tanh.",
730        arguments: &[
731            &ArgumentInfo {
732                label: "x",
733                description: "Input value",
734                type_hint: "f64",
735                optional: false,
736            },
737        ],
738        returns: "Hyperbolic cosine value (f64)",
739        errors: "None - always succeeds",
740        categories: &["math"],
741        examples: &[
742            "cosh(0) => 1",
743            "cosh(1) => 1.5430806348152437",
744            "cosh(-1) => 1.5430806348152437",
745        ],
746    },
747    
748    // tanh(x) -> f64
749    FunctionCard {
750        identifier: "tanh",
751        signature: "tanh(x)",
752        brief: "Calculate the hyperbolic tangent.",
753description: "Returns the hyperbolic tangent of the input value. The hyperbolic tangent \
754                      is defined as sinh(x)/cosh(x) or (e^x - e^(-x))/(e^x + e^(-x)). It's \
755                      commonly used as an activation function in neural networks and appears \
756                      in physics equations for velocity addition in special relativity. See also: sinh, cosh.",
757        arguments: &[
758            &ArgumentInfo {
759                label: "x",
760                description: "Input value",
761                type_hint: "f64",
762                optional: false,
763            },
764        ],
765        returns: "Hyperbolic tangent value (f64)",
766        errors: "None - always succeeds",
767        categories: &["math"],
768        examples: &[
769            "tanh(0) => 0",
770            "tanh(1) => 0.7615941559557649",
771            "tanh(∞) => 1",
772        ],
773    },
774    
775    // Aggregate Functions (3)
776    
777    // sum(array) -> f64
778    FunctionCard {
779        identifier: "sum",
780        signature: "sum(array)",
781        brief: "Calculate the sum of all values in an array.",
782description: "Returns the arithmetic sum of all numeric values in the input array. \
783                      For empty arrays, returns 0. This function is fundamental for statistical \
784                      calculations, financial computations, and any scenario requiring the \
785                      accumulation of values. See also: product, average.",
786        arguments: &[
787            &ArgumentInfo {
788                label: "array",
789                description: "Array of numbers to sum",
790                type_hint: "Vec<f64>",
791                optional: false,
792            },
793        ],
794        returns: "Sum of values (f64)",
795        errors: "None - always succeeds",
796        categories: &["math", "aggregate"],
797        examples: &[
798            "sum((1, 2, 3, 4, 5)) => 15",
799            "sum((-1, -2, -3)) => -6",
800            "sum(()) => 0",
801        ],
802    },
803    
804    // product(array) -> f64
805    FunctionCard {
806        identifier: "product",
807        signature: "product(array)",
808        brief: "Calculate the product of all values in an array.",
809description: "Returns the result of multiplying all numeric values in the input array \
810                      together. For empty arrays, returns 1 (the multiplicative identity). \
811                      This function is useful for calculating compound growth rates, \
812                      combinations, and factorial-like computations. See also: sum, average.",
813        arguments: &[
814            &ArgumentInfo {
815                label: "array",
816                description: "Array of numbers to multiply",
817                type_hint: "Vec<f64>",
818                optional: false,
819            },
820        ],
821        returns: "Product of values (f64)",
822        errors: "None - always succeeds",
823        categories: &["math", "aggregate"],
824        examples: &[
825            "product((2, 3, 4)) => 24",
826            "product((1, 2, 3, 4)) => 24",
827            "product(()) => 1",
828        ],
829    },
830    
831    // average(array) -> f64
832    FunctionCard {
833        identifier: "average",
834        signature: "average(array)",
835        brief: "Calculate the arithmetic mean of an array.",
836description: "Returns the average (arithmetic mean) of all numeric values in the input \
837                      array. Calculated as the sum of values divided by the count of values. \
838                      For empty arrays, returns 0. This function is fundamental for statistical \
839                      analysis, data summarization, and performance metrics. See also: sum, product.",
840        arguments: &[
841            &ArgumentInfo {
842                label: "array",
843                description: "Array of numbers to average",
844                type_hint: "Vec<f64>",
845                optional: false,
846            },
847        ],
848        returns: "Average value (f64)",
849        errors: "None - always succeeds",
850        categories: &["math", "aggregate"],
851        examples: &[
852            "average((1, 2, 3, 4, 5)) => 3",
853            "average((10, 20)) => 15",
854            "average(()) => 0",
855        ],
856    },
857    
858    // Constants (4)
859    
860    // PI -> f64
861    FunctionCard {
862        identifier: "PI",
863        signature: "PI()",
864        brief: "Mathematical constant π (pi).",
865        description: "Returns the mathematical constant π (pi), approximately 3.141592653589793. \
866                     Pi represents the ratio of a circle's circumference to its diameter and \
867                     is fundamental in geometry, trigonometry, and many areas of mathematics \
868                     and science. It appears in formulas for circles, spheres, waves, and \
869                     periodic phenomena. See also: E.",
870        arguments: &[],
871        returns: "π constant (f64)",
872        errors: "None - always succeeds",
873        categories: &["math", "constant"],
874        examples: &[
875            "PI() => 3.141592653589793",
876            "2 * PI() => 6.283185307179586",
877            "PI() / 2 => 1.5707963267948966",
878        ],
879    },
880    
881    // E -> f64
882    FunctionCard {
883        identifier: "E",
884        signature: "E()",
885        brief: "Mathematical constant e (Euler's number).",
886description: "Returns the mathematical constant e (Euler's number), approximately \
887                      2.718281828459045. Euler's number is the base of the natural logarithm \
888                      and is fundamental in calculus, exponential growth, compound interest, \
889                      and many areas of mathematics and science. It's defined as the limit \
890                      of (1 + 1/n)^n as n approaches infinity. See also: PI.",
891        arguments: &[],
892        returns: "e constant (f64)",
893        errors: "None - always succeeds",
894        categories: &["math", "constant"],
895        examples: &[
896            "E() => 2.718281828459045",
897            "exp(1) => E()",
898            "ln(E()) => 1",
899        ],
900    },
901    
902    // NaN -> f64
903    FunctionCard {
904        identifier: "NaN",
905        signature: "NaN()",
906        brief: "Not-a-Number constant.",
907        description: "Returns the special floating-point value NaN (Not-a-Number). This \
908                     constant represents an undefined or unrepresentable value, typically \
909                     resulting from invalid mathematical operations like 0/0 or ∞-∞. NaN is \
910                     useful for representing missing data, error conditions, or undefined \
911                     results in numerical computations.",
912        arguments: &[],
913        returns: "NaN constant (f64)",
914        errors: "None - always succeeds",
915        categories: &["math", "constant"],
916        examples: &[
917            "NaN() => NaN",
918            "NaN() + 1 => NaN",
919            "is_nan(NaN()) => true",
920        ],
921    },
922    
923    // random() -> f64
924    FunctionCard {
925        identifier: "random",
926        signature: "random()",
927        brief: "Generate a random number between 0 and 1.",
928        description: "Returns a uniformly distributed random floating-point number in the \
929                     range [0, 1). Each call produces a different random value. This function \
930                     is useful for simulations, random sampling, probability calculations, \
931                     and generating test data. The underlying implementation uses a \
932                     cryptographically secure random number generator.",
933        arguments: &[],
934        returns: "Random number [0, 1) (f64)",
935        errors: "None - always succeeds",
936        categories: &["math", "constant"],
937        examples: &[
938            "random() => 0.123456789",
939            "random() => 0.987654321",
940            "random() => 0.543216789",
941        ],
942    },
943    
944    // Additional Functions (4)
945    
946    // lerp(a, b, t) -> f64
947    FunctionCard {
948        identifier: "lerp",
949        signature: "lerp(a, b, t)",
950        brief: "Perform linear interpolation between two values.",
951description: "Calculates a value between a and b based on the interpolation parameter t. \
952                      When t is 0, returns a. When t is 1, returns b. For values between 0 and 1, \
953                      returns a weighted average. The parameter t is clamped to [0, 1] to ensure \
954                      the result stays within the range [a, b]. This function is essential for \
955                      animations, transitions, and smooth value changes. See also: clamp.",
956        arguments: &[
957            &ArgumentInfo {
958                label: "a",
959                description: "Starting value",
960                type_hint: "f64",
961                optional: false,
962            },
963            &ArgumentInfo {
964                label: "b",
965                description: "Ending value",
966                type_hint: "f64",
967                optional: false,
968            },
969            &ArgumentInfo {
970                label: "t",
971                description: "Interpolation factor [0, 1]",
972                type_hint: "f64",
973                optional: false,
974            },
975        ],
976        returns: "Interpolated value (f64)",
977        errors: "None - always succeeds",
978        categories: &["math"],
979        examples: &[
980            "lerp(0, 10, 0.5) => 5",
981            "lerp(100, 200, 0) => 100",
982            "lerp(100, 200, 1) => 200",
983        ],
984    },
985    
986    // gcd(a, b) -> f64
987    FunctionCard {
988        identifier: "gcd",
989        signature: "gcd(a, b)",
990        brief: "Calculate the greatest common divisor of two numbers.",
991description: "Returns the largest positive integer that divides both input numbers \
992                      without a remainder. This function uses a scaled integer algorithm to \
993                      handle floating-point inputs with decimal precision. It's fundamental \
994                      in number theory, fraction reduction, and solving Diophantine equations. See also: lcm.",
995        arguments: &[
996            &ArgumentInfo {
997                label: "a",
998                description: "First number",
999                type_hint: "f64",
1000                optional: false,
1001            },
1002            &ArgumentInfo {
1003                label: "b",
1004                description: "Second number",
1005                type_hint: "f64",
1006                optional: false,
1007            },
1008        ],
1009        returns: "Greatest common divisor (f64)",
1010        errors: "Returns 0 for zero or infinite inputs",
1011        categories: &["math"],
1012        examples: &[
1013            "gcd(12, 18) => 6",
1014            "gcd(17, 13) => 1",
1015            "gcd(0, 5) => 0",
1016        ],
1017    },
1018    
1019    // lcm(a, b) -> f64
1020    FunctionCard {
1021        identifier: "lcm",
1022        signature: "lcm(a, b)",
1023        brief: "Calculate the least common multiple of two numbers.",
1024description: "Returns the smallest positive integer that is divisible by both input \
1025                      numbers. This function uses a scaled integer algorithm to handle \
1026                      floating-point inputs with decimal precision. It's fundamental in number \
1027                      theory, fraction operations, and scheduling problems. See also: gcd.",
1028        arguments: &[
1029            &ArgumentInfo {
1030                label: "a",
1031                description: "First number",
1032                type_hint: "f64",
1033                optional: false,
1034            },
1035            &ArgumentInfo {
1036                label: "b",
1037                description: "Second number",
1038                type_hint: "f64",
1039                optional: false,
1040            },
1041        ],
1042        returns: "Least common multiple (f64)",
1043        errors: "Returns 0 for zero or infinite inputs",
1044        categories: &["math"],
1045        examples: &[
1046            "lcm(4, 6) => 12",
1047            "lcm(15, 25) => 75",
1048            "lcm(7, 11) => 77",
1049        ],
1050    },
1051    
1052// is_nan(x) -> bool
1053    FunctionCard {
1054        identifier: "is_nan",
1055        signature: "is_nan(x)",
1056        brief: "Check if a value is NaN (Not-a-Number).",
1057description: "Returns true if the input value is NaN (Not-a-Number), false otherwise. \
1058                       This function is useful for validating numerical results, handling \
1059                       error conditions, and checking for undefined mathematical operations. \
1060                       It's essential for robust numerical computing where invalid results need \
1061                       to be detected and handled appropriately. See also: NaN constant.",
1062        arguments: &[
1063            &ArgumentInfo {
1064                label: "x",
1065                description: "Value to check for NaN",
1066                type_hint: "f64",
1067                optional: false,
1068            },
1069        ],
1070        returns: "Boolean indicating if value is NaN (bool)",
1071        errors: "None - always succeeds",
1072        categories: &["math", "logical"],
1073        examples: &[
1074            "is_nan(NaN()) => true",
1075            "is_nan(0/0) => true",
1076            "is_nan(42) => false",
1077        ],
1078    },
1079    
1080    
1081];
aimx/info_library/math_cards.rs

aimx/info_library/
math_cards.rs
