"Fossies" - the Fresh Open Source Software Archive 
Member "mapm_4.9.5a/DOCS/function.ref" (21 Feb 2010, 41040 Bytes) of package /linux/misc/old/mapm-4.9.5a.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1
2 -----------------------------------------------------------------------------
3 MAPM Function Descriptions April 12, 2009
4 -----------------------------------------------------------------------------
5
6 Note that the default MAPM library is *NOT* thread safe. MAPM internal data
7 structures could get corrupted if multiple MAPM functions are active at the
8 same time. The user should guarantee that only one thread is performing
9 MAPM functions. This can usually be achieved by a call to the operating
10 system to obtain a 'semaphore', 'mutex', or 'critical code section' so
11 the operating system will guarantee that only one MAPM thread will be
12 active at a time.
13
14 -----------------------------------------------------------------------------
15
16 Prototype: char *m_apm_lib_version(char *);
17 char *m_apm_lib_short_version(char *);
18
19 Example: char lib_version[80];
20 m_apm_lib_version(lib_version);
21 m_apm_lib_short_version(lib_version);
22
23 These 2 functions return the current version of the library.
24 That is, the version of the library when it was compiled.
25
26 The return value is the pointer to the input string. The length
27 of the string will always be < 80 chars.
28
29 'm_apm_lib_version' will fill the string parameter with the
30 following format: (without the double quotes)
31
32 "MAPM Library Version x.y Copyright (C) 1999-2004, Michael C. Ring"
33 "MAPM Library Version x.y.z Copyright (C) 1999-2004, Michael C. Ring"
34
35 'm_apm_lib_short_version' will fill the string parameter with
36 the following format: (without the double quotes)
37
38 "x.y"
39 "x.y.z"
40
41 where x,y,z will be single digits indicating the current
42 version : "4.6.1", "4.7", etc.
43
44 -----------------------------------------------------------------------------
45
46 Prototype: M_APM m_apm_init(void);
47
48 Example: M_APM apmvalue;
49 apmvalue = m_apm_init();
50
51 This function initializes a new MAPM value. The value 0 is
52 assigned to the variable. This function must be called before
53 any MAPM operation is performed on the value. This is because
54 it is analogous to :
55
56 char *p;
57 .
58 .
59 memset(p, 'A', 100000);
60
61 The above example will likely fail because 'p' does not point
62 to a valid memory block yet. The same is true of an MAPM value
63 that is declared but not yet initialized.
64
65 -----------------------------------------------------------------------------
66
67 Prototype: void m_apm_free(M_APM);
68
69 Example: M_APM apmvalue;
70 m_apm_free(apmvalue);
71
72 This function will free the memory previously allocated by
73 'm_apm_init'.
74
75 -----------------------------------------------------------------------------
76
77 Prototype: void m_apm_free_all_mem(void);
78
79 Example: m_apm_free_all_mem();
80
81 This function will free ALL the memory that MAPM has allocated
82 internally. It will NOT free variables that the user has
83 initialized from m_apm_init(). The user is responsible for
84 free'ing their own variables. The variables that the user has
85 initialized are still valid MAPM numbers, but you won't be able
86 to do anything useful with them. A call to a MAPM library
87 function will likely result in a crash.
88
89 The intent of this function is to free all MAPM allocated
90 memory once your calculations are complete.
91
92 A subsequent call to 'm_apm_trim_mem_usage()' will re-initialize
93 the library and it will be ready for use again.
94
95 -----------------------------------------------------------------------------
96
97 Prototype: void m_apm_trim_mem_usage(void);
98
99 Example: m_apm_trim_mem_usage();
100
101 This function will reduce the memory used by MAPM to it's
102 initial start-up state.
103
104 The intent of this function is to minimize the memory footprint
105 of MAPM while still maintaining full capabilities.
106
107 -----------------------------------------------------------------------------
108
109 Prototype: void m_apm_cpp_precision(int);
110
111 Example: m_apm_cpp_precision(72);
112
113 This function is only used by the C++ MAPM wrapper class.
114
115 It specifies to the wrapper class the minimum number of
116 significant digits that should be calculated for a given
117 operation. This function specifies only the MINIMUM precision.
118 The example above specifies 72 significant digits. Consider
119 the statement y = sin(x); If 'x' contains < 72 digits, 'y'
120 will contain 72 digits of precision. If 'x' >= 72 digits,
121 'y' will contain the number of digits that 'x' contains.
122
123 The default is 30.
124
125 -----------------------------------------------------------------------------
126
127 Prototype: void m_apm_set_string(M_APM, char *);
128
129 Example: M_APM apmvalue;
130 char in_string[128];
131 m_apm_set_string(apmvalue, in_string);
132
133 This function will set the MAPM value to the value specified
134 by the string variable. Integers and floating point are supported
135 as is floating point with scientific notation.
136
137 o) Lead-in whitespace is ignored.
138 o) A lead-in '+' sign is optional.
139 o) A negative number must have '-' as the first non-whitespace char
140 o) An exponent, 'E' or 'e', is optional.
141 o) The decimal point is optional. The decimal point may be
142 anywhere in the number, but before the exponent.
143 o) The exponent may have an optional '+' sign.
144 o) The exponent must be an integer value (no decimal point)
145
146 m_apm_set_string(apmvalue, "-23");
147 m_apm_set_string(apmvalue, "1964.425206");
148 m_apm_set_string(apmvalue, "-9.344218785E-12");
149 m_apm_set_string(apmvalue, "+987622.87633e+27");
150 m_apm_set_string(apmvalue, ".0000004217");
151
152 -----------------------------------------------------------------------------
153
154 Prototype: void m_apm_set_long(M_APM, long);
155
156 Example: M_APM apmvalue;
157 long longval;
158 m_apm_set_long(apmvalue, longval);
159
160 This function will set the MAPM value to the value specified
161 by the long variable.
162
163 m_apm_set_long(apmvalue, -203L);
164 m_apm_set_long(apmvalue, 1964L);
165 m_apm_set_long(apmvalue, 5219954L);
166
167 -----------------------------------------------------------------------------
168
169 Prototype: void m_apm_set_double(M_APM, double);
170
171 Example: M_APM apmvalue;
172 double doubleval;
173 m_apm_set_double(apmvalue, doubleval);
174
175 This function will set the MAPM value to the value specified
176 by the double variable. The double value will be rounded to
177 the 15 most significant digits and then converted to the MAPM
178 value. If you want an 'exact' conversion, use the m_apm_set_string
179 function since some C floating point library's may round your
180 double in an unpredictable manner.
181
182 m_apm_set_double(apmvalue, -2.03);
183 m_apm_set_double(apmvalue, 21887.4421964);
184 m_apm_set_double(apmvalue, -9.4421E-3);
185
186 -----------------------------------------------------------------------------
187
188 Prototype: void m_apm_to_string(char *, int, M_APM);
189
190 Example: M_APM apmvalue;
191 int decimal_places;
192 char out_string[256];
193 m_apm_to_string(out_string, decimal_places, apmvalue);
194
195 This function will convert an MAPM value into a string and is
196 meant to be used with floating point MAPM values. The output
197 string must be large enough to hold the result. The output
198 string will always be in scientific (exponential) notation.
199 There will be a leading '-' sign for negative numbers. There
200 will be 'decimal_places' number of digits after the decimal
201 point. If decimal_places is >= 0, the value will be rounded to
202 that number of digits and then the string will be filled, with
203 trailing zero's appended if necessary to fill out the decimal
204 place specification. If decimal_places < 0, ALL the significant
205 digits of the MAPM number will be output. In some applications,
206 it is convenient to round the value yourself (see 'm_apm_round')
207 and then display ALL the digits.
208
209 If apmvalue is == 3.640083E-4 :
210
211 1) m_apm_to_string(out_string, 4, apmvalue);
212 out_string -> "3.6401E-4"
213
214 2) m_apm_to_string(out_string, 14, apmvalue);
215 out_string -> "3.64008300000000E-4"
216
217 3) m_apm_to_string(out_string, -1, apmvalue);
218 out_string -> "3.640083E-4"
219
220 -----------------------------------------------------------------------------
221
222 Prototype: void m_apm_to_fixpt_string(char *, int, M_APM);
223
224 Example: M_APM apmvalue;
225 int decimal_places;
226 char out_string[256];
227 m_apm_to_fixpt_string(out_string, decimal_places, apmvalue);
228
229 This function will convert an MAPM value into a string and the
230 output will be formatted in fixed point notation. The output
231 string must be large enough to hold the result.
232
233 If decimal_places < 0, ALL the significant digits of the MAPM
234 number will be output.
235
236 If decimal_places == 0, the output will be the MAPM value rounded
237 to the nearest integer and the decimal point will be suppressed.
238
239 If decimal_places is > 0, the value will be rounded to that number
240 of digits and then the string will be filled, with trailing zero's
241 appended if necessary to fill out the decimal place specification.
242
243
244 In some applications, it is convenient to round the value yourself
245 (see 'm_apm_round') and then display ALL the digits.
246
247 If apmvalue is == 3.6487451E+2 :
248
249 1) m_apm_to_fixpt_string(out_string, 10, apmvalue);
250 out_string -> "364.8745100000"
251
252 2) m_apm_to_fixpt_string(out_string, 1, apmvalue);
253 out_string -> "364.9"
254
255 3) m_apm_to_fixpt_string(out_string, 0, apmvalue);
256 out_string -> "365"
257
258 4) m_apm_to_fixpt_string(out_string, -1, apmvalue);
259 out_string -> "364.87451"
260
261 -----------------------------------------------------------------------------
262
263 Prototype: void m_apm_to_fixpt_stringex(char *, int, M_APM, char, char, int);
264
265 Example: char out_string[256];
266 int decimal_places;
267 M_APM apmvalue;
268 char radix;
269 char separator_char;
270 int separator_count;
271
272 m_apm_to_fixpt_stringex(out_string, decimal_places, apmvalue,
273 radix, separator_char, separator_count);
274
275
276 The output string must be large enough to hold the result.
277 This function is an extended version of the previous function,
278 there are 3 additional function parameters:
279
280 radix:
281
282 Specify the radix character desired. For example, use ',' to
283 set the radix char to a comma.
284
285 separator_char:
286 separator_count:
287
288 Specify a character separator every 'separator_count' characters.
289 This is used to split up a large number with a 'delimiter' for
290 easier readability. For example,
291
292 If separator_char = ',' and separator_count = 3, there will be a
293 comma inserted before every group of 3 digits in the output string.
294
295 6123456789.098765321 will be formatted as "6,123,456,789.098765321"
296
297 Note that only digits before the radix char are separated.
298
299 separator_char OR separator_count == 0 is used to disable
300 the 'char separator' feature. This would typically be used
301 when it is only desired to change the radix character.
302
303 -----------------------------------------------------------------------------
304
305 Prototype: char *m_apm_to_fixpt_stringexp(int, M_APM, char, char, int);
306
307 Example: char *out_string;
308 int decimal_places;
309 M_APM apmvalue;
310 char radix;
311 char separator_char;
312 int separator_count;
313
314 out_string = m_apm_to_fixpt_stringexp(decimal_places, apmvalue,
315 radix, separator_char, separator_count);
316
317 if (out_string != NULL)
318 {
319 printf("%s\n", out_string); <-- do something with the string
320 free(out_string); <-- now free the buffer
321 }
322
323
324 This function is almost identical to the previous function.
325 The difference is this function will malloc the desired buffer
326 and return it to the caller. In the previous function, the caller
327 supplied the buffer and the output had to fit in that buffer.
328
329 If the malloc in this function fails, NULL will be returned.
330
331 It is the callers responsibility to free the memory which this
332 function 'mallocs'. If the user has re-defined malloc/realloc/free
333 to use their own function wrappers, then your corresponding 'free'
334 function should be used.
335
336 -----------------------------------------------------------------------------
337
338 Prototype: void m_apm_to_integer_string(char *, M_APM);
339
340 Example: M_APM apmvalue;
341 char out_string[256];
342 m_apm_to_integer_string(out_string, apmvalue);
343
344 This function will convert an MAPM value into a string and is
345 meant to be used with integer values. The output string must
346 be large enough to hold the result. If the MAPM number is not
347 an integer, the function will truncate the value to the nearest
348 integer and the output will be formatted as an integer, with a
349 possible leading '-' sign.
350
351 Examples:
352
353 M_APM Value Output String
354 ----------- -------------
355 3.28E+2 "328"
356 -4.56993E+2 "-456"
357 4.32E-3 "0"
358 -1.62E+5 "-162000"
359
360 If you want the value 'rounded' to the nearest integer (NNN.99
361 becomes NNN+1), use m_apm_to_fixpt_string with 0 decimal places.
362
363 -----------------------------------------------------------------------------
364
365 Prototype: void m_apm_absolute_value(M_APM, M_APM);
366
367 Example: M_APM apmresult, apmvalue;
368 m_apm_absolute_value(apmresult, apmvalue);
369
370 This function will take the absolute value of 'apmvalue'
371 and put it in 'apmresult'. The 'apmresult' parameter cannot
372 be the other MAPM parameter.
373
374 -----------------------------------------------------------------------------
375
376 Prototype: void m_apm_negate(M_APM, M_APM);
377
378 Example: M_APM apmresult, apmvalue;
379 m_apm_negate(apmresult, apmvalue);
380
381 This function will negate the value of 'apmvalue' and put it
382 in 'apmresult'. The 'apmresult' parameter cannot be the
383 other MAPM parameter.
384
385 -----------------------------------------------------------------------------
386
387 Prototype: void m_apm_copy(M_APM, M_APM);
388
389 Example: M_APM apmresult, apmvalue;
390 m_apm_copy(apmresult, apmvalue);
391
392 This function will copy the value of 'apmvalue' and put it
393 in 'apmresult'. The 'apmresult' parameter cannot be the
394 other MAPM parameter.
395
396 -----------------------------------------------------------------------------
397
398 Prototype: void m_apm_round(M_APM, int, M_APM);
399
400 Example: M_APM apmresult, apmvalue;
401 int decimal_places;
402 m_apm_round(apmresult, decimal_places, apmvalue);
403
404 This function will round the value of 'apmvalue' to the number
405 of decimal places specified and put it in 'apmresult'. The
406 decimal places parameter is referenced to the number when the
407 number is in scientific notation. The 'apmresult' parameter
408 cannot be the other MAPM parameter.
409
410 -----------------------------------------------------------------------------
411
412 Prototype: int m_apm_compare(M_APM, M_APM);
413
414 Example: M_APM apm_num1, apm_num2;
415 int cmp_result;
416 cmp_result = m_apm_compare(apm_num1, apm_num2);
417
418 This function will compare the value of apm_num1 to apm_num2.
419 The function will return :
420 -1 : num1 < num2
421 0 : num1 = num2
422 1 : num1 > num2
423
424 -----------------------------------------------------------------------------
425
426 Prototype: int m_apm_sign(M_APM);
427
428 Example: M_APM apm_num;
429 int sign_result;
430 sign_result = m_apm_sign(apm_num);
431
432 This function will return the sign of apm_num.
433 The function will return :
434 -1 : num < 0
435 0 : num = 0
436 1 : num > 0
437
438 -----------------------------------------------------------------------------
439
440 Prototype: int m_apm_exponent(M_APM);
441
442 Example: M_APM apm_num;
443 int exponent;
444 exponent = m_apm_exponent(apm_num);
445
446 This function will return the exponent of apm_num.
447
448 If apm_num = 3.86742E+12, 12 will be returned.
449 = 9.61082E-56, -56 will be returned.
450 = 0.0 0 will be returned.
451
452 -----------------------------------------------------------------------------
453
454 Prototype: int m_apm_significant_digits(M_APM);
455
456 Example: M_APM apm_num;
457 int digits;
458 digits = m_apm_significant_digits(apm_num);
459
460 This function will return the number of significant digits
461 in apm_num. This may be used to determine how big to malloc
462 a char array so the full number can be converted to a string.
463
464 If apm_num = 3.86742E+12 : 6 will be returned.
465 = -96108.27608 : 10 will be returned.
466
467 -----------------------------------------------------------------------------
468
469 Prototype: int m_apm_is_integer(M_APM);
470
471 Example: M_APM apm_num;
472 int integer_flag;
473 integer_flag = m_apm_is_integer(apm_num);
474
475 This function will return 1 (TRUE) if apm_num is an
476 integer value, 0 (FALSE) if not.
477
478 -----------------------------------------------------------------------------
479
480 Prototype: int m_apm_is_even(M_APM);
481
482 Example: M_APM apm_int;
483 int even_flag;
484 even_flag = m_apm_is_even(apm_int);
485
486 This function will return 1 (TRUE) if apm_int is an
487 even integer value, 0 (FALSE) if not.
488
489 An input value that is not an integer will result in
490 a warning on stderr and the return value is undefined.
491
492 -----------------------------------------------------------------------------
493
494 Prototype: int m_apm_is_odd(M_APM);
495
496 Example: M_APM apm_int;
497 int odd_flag;
498 odd_flag = m_apm_is_odd(apm_int);
499
500 This function will return 1 (TRUE) if apm_int is an
501 odd integer value, 0 (FALSE) if not.
502
503 An input value that is not an integer will result in
504 a warning on stderr and the return value is undefined.
505
506 -----------------------------------------------------------------------------
507
508 Prototype: void m_apm_set_random_seed(char *);
509
510 Example: m_apm_set_random_seed("12345678");
511
512 This function will set the random number generator to a
513 known starting value.
514
515 The char string argument should correspond to any *integer*
516 value between 0 and (1.0E+15 - 1).
517
518 This function can be called at any time, either before or
519 anytime after 'm_apm_get_random'.
520
521 -----------------------------------------------------------------------------
522
523 Prototype: void m_apm_get_random(M_APM);
524
525 Example: M_APM random_number;
526 m_apm_get_random(random_number);
527
528 This function will return a random floating point number
529 between the values 0 and 1. The first time the function is
530 called the generator is initialized with the system time.
531 This generator will not repeat its pattern until 1.0E+15
532 numbers have been generated.
533
534 Note that the MAPM parameter passed may be used for other
535 purposes. The function itself maintains the correct sequence
536 and just returns a copy of the next random number.
537
538 -----------------------------------------------------------------------------
539
540 Prototype: void m_apm_add(M_APM, M_APM, M_APM);
541
542 Example: M_APM apmresult, apm_num1, apm_num2;
543 m_apm_add(apmresult, apm_num1, apm_num2);
544
545 This function will add apm_num1 to apm_num2 and put the result
546 in 'apmresult'. The 'apmresult' parameter cannot be one of
547 the other MAPM parameters.
548
549 -----------------------------------------------------------------------------
550
551 Prototype: void m_apm_subtract(M_APM, M_APM, M_APM);
552
553 Example: M_APM apmresult, apm_num1, apm_num2;
554 m_apm_subtract(apmresult, apm_num1, apm_num2);
555
556 This function will subtract apm_num2 from apm_num1 and put the
557 result in 'apmresult'. (result = num1 - num2) The 'apmresult'
558 parameter cannot be one of the other MAPM parameters.
559
560 -----------------------------------------------------------------------------
561
562 Prototype: void m_apm_multiply(M_APM, M_APM, M_APM);
563
564 Example: M_APM apmresult, apm_num1, apm_num2;
565 m_apm_multiply(apmresult, apm_num1, apm_num2);
566
567 This function will multiply apm_num1 and apm_num2 and put the
568 result in 'apmresult'. The 'apmresult' parameter cannot be
569 one of the other MAPM parameters.
570
571 -----------------------------------------------------------------------------
572
573 Prototype: void m_apm_divide(M_APM, int, M_APM, M_APM);
574
575 Example: M_APM apmresult, apm_num1, apm_num2;
576 int decimal_places;
577 m_apm_divide(apmresult, decimal_places, apm_num1, apm_num2);
578
579 This function will divide apm_num1 by apm_num2 and put the
580 result in 'apmresult'. The 'apmresult' parameter cannot be
581 one of the other MAPM parameters.
582
583 Unlike the other three basic operations, division cannot be
584 counted on to produce non-repeating decimals, so the
585 'decimal_places' variable is used to tell this routine how many
586 digits are to be calculated before stopping.
587
588 Note that the number of decimal places is referenced to the
589 value as if the number was in fixed point notation. m_apm_divide
590 is the only function where decimal places is referenced to
591 fixed point notation, all other functions are referenced to
592 scientific notation. This was an intentional design decision
593 so 'm_apm_integer_divide' and 'm_apm_integer_div_rem' would
594 work as expected.
595
596 Division by zero creates a zero result and a warning on stderr.
597
598 -----------------------------------------------------------------------------
599
600 Prototype: void m_apm_reciprocal(M_APM, int, M_APM);
601
602 Example: M_APM apmresult, apm_num;
603 int decimal_places;
604 m_apm_reciprocal(apmresult, decimal_places, apm_num);
605
606 This function will compute the reciprocal of 'apm_num' and it
607 will put the result in 'apmresult' (compute 1.0 / apm_num). The
608 result will be accurate to the number of decimal places specified.
609
610 The 'apmresult' parameter cannot be the other MAPM parameter.
611
612 An input of zero creates a zero result and a warning on stderr.
613
614 -----------------------------------------------------------------------------
615
616 Prototype: void m_apm_integer_divide(M_APM, M_APM, M_APM);
617
618 Example: M_APM apmresult, apm_num1, apm_num2;
619 m_apm_integer_divide(apmresult, apm_num1, apm_num2);
620
621 This function will divide apm_num1 by apm_num2, truncating the
622 result to an integer and put the result in 'apmresult'. The
623 'apmresult' parameter cannot be one of the other MAPM parameters.
624
625 Division by zero creates a zero result and a warning on stderr.
626
627 -----------------------------------------------------------------------------
628
629 Prototype: void m_apm_integer_div_rem(M_APM, M_APM, M_APM, M_APM);
630
631 Example: M_APM quotient, remainder, num1, num2;
632 m_apm_integer_div_rem(quotient, remainder, num1, num2);
633
634 This function will divide num1 by num2, truncating the
635 result to an integer and put the result in 'quotient' and it
636 will put the remainder in 'remainder'. So, 173 / 26 will yield
637 a quotient of 6 and a remainder of 17.
638
639 Note that the input numbers do not necessarily have to be
640 integers. This function can be used to split up the integer
641 portion and fractional portion of a floating point number
642 by calling the function with num2 set to 'MM_One'. So,
643 32.17042 can be split up into '32' and '0.17042'.
644
645 The 'quotient' and 'remainder' parameters cannot be one of the
646 other MAPM parameters.
647
648 Division by zero creates a zero result and a warning on stderr.
649
650 -----------------------------------------------------------------------------
651
652 Prototype: void m_apm_factorial(M_APM, M_APM);
653
654 Example: M_APM apmresult, apm_num;
655 m_apm_factorial(apmresult, apm_num);
656
657 This function will compute the factorial of 'apm_num' and put
658 the result in 'apmresult'.
659
660 A non-integer input will yield nonsense. Actually, the algorithm
661 simply multiplies : (though 0! and 1! return 1)
662
663 N * (N - 1) * (N - 2) ... until N < 2.
664
665 The 'apmresult' parameter cannot be the other MAPM parameter.
666
667 -----------------------------------------------------------------------------
668
669 Prototype: void m_apm_floor(M_APM, M_APM);
670
671 Example: M_APM apmresult, apm_num;
672 m_apm_floor(apmresult, apm_num);
673
674 This function will round 'apm_num' downwards to the nearest
675 integer and return the result in 'apmresult'. This has the
676 same behavior as the 'C' function of the same name.
677
678 The 'apmresult' parameter cannot be the other MAPM parameter.
679
680 -----------------------------------------------------------------------------
681
682 Prototype: void m_apm_ceil(M_APM, M_APM);
683
684 Example: M_APM apmresult, apm_num;
685 m_apm_ceil(apmresult, apm_num);
686
687 This function will round 'apm_num' upwards to the nearest
688 integer and return the result in 'apmresult'. This has the
689 same behavior as the 'C' function of the same name.
690
691 The 'apmresult' parameter cannot be the other MAPM parameter.
692
693 -----------------------------------------------------------------------------
694
695 Prototype: void m_apm_gcd(M_APM, M_APM, M_APM);
696
697 Example: M_APM apmresult, apm_num1, apm_num2;
698 m_apm_gcd(apmresult, apm_num1, apm_num2);
699
700 This function will compute the GCD (greatest common divisor) of
701 apm_num1 and apm_num2 and put the result in 'apmresult'.
702
703 The 'apmresult' parameter cannot be one of the other MAPM
704 parameters.
705
706 Non-integer inputs will create a zero result and a warning
707 on stderr.
708
709 -----------------------------------------------------------------------------
710
711 Prototype: void m_apm_lcm(M_APM, M_APM, M_APM);
712
713 Example: M_APM apmresult, apm_num1, apm_num2;
714 m_apm_lcm(apmresult, apm_num1, apm_num2);
715
716 This function will compute the LCM (least common multiple) of
717 apm_num1 and apm_num2 and put the result in 'apmresult'.
718
719 The 'apmresult' parameter cannot be one of the other MAPM
720 parameters.
721
722 Non-integer inputs will create a zero result and a warning
723 on stderr.
724
725 -----------------------------------------------------------------------------
726
727 Prototype: void m_apm_sqrt(M_APM, int, M_APM);
728
729 Example: M_APM apmresult, apm_num;
730 int decimal_places;
731 m_apm_sqrt(apmresult, decimal_places, apm_num);
732
733 This function will take the square root of 'apm_num' and it
734 will put the result in 'apmresult'. The result will be accurate
735 to the number of decimal places specified.
736
737 The 'apmresult' parameter cannot be the other MAPM parameter.
738
739 An input < zero creates a zero result and a warning on stderr.
740
741 -----------------------------------------------------------------------------
742
743 Prototype: void m_apm_cbrt(M_APM, int, M_APM);
744
745 Example: M_APM apmresult, apm_num;
746 int decimal_places;
747 m_apm_cbrt(apmresult, decimal_places, apm_num);
748
749 This function will take the cube root of 'apm_num' and it
750 will put the result in 'apmresult'. The result will be accurate
751 to the number of decimal places specified.
752
753 The 'apmresult' parameter cannot be the other MAPM parameter.
754
755 -----------------------------------------------------------------------------
756
757 Prototype: void m_apm_log(M_APM, int, M_APM);
758
759 Example: M_APM apmresult, apm_num;
760 int decimal_places;
761 m_apm_log(apmresult, decimal_places, apm_num);
762
763 This function will take the natural log (base 2.718 ...) of
764 'apm_num' and it will put the result in 'apmresult'. The result
765 will be accurate to the number of decimal places specified.
766
767 The 'apmresult' parameter cannot be the other MAPM parameter.
768
769 An input <= zero creates a zero result and a warning on stderr.
770
771 -----------------------------------------------------------------------------
772
773 Prototype: void m_apm_log10(M_APM, int, M_APM);
774
775 Example: M_APM apmresult, apm_num;
776 int decimal_places;
777 m_apm_log10(apmresult, decimal_places, apm_num);
778
779 This function will take the common log (base 10) of 'apm_num'
780 and it will put the result in 'apmresult'. The result will be
781 accurate to the number of decimal places specified.
782
783 The 'apmresult' parameter cannot be the other MAPM parameter.
784
785 An input <= zero creates a zero result and a warning on stderr.
786
787 -----------------------------------------------------------------------------
788
789 Prototype: void m_apm_exp(M_APM, int, M_APM);
790
791 Example: M_APM apmresult, apm_num;
792 int decimal_places;
793 m_apm_exp(apmresult, decimal_places, apm_num);
794
795 This function will perform E ^ apm_num where 'E' is 2.718...
796 (the exponential function) and it will put the result in
797 'apmresult'. The result will be accurate to the number of
798 decimal places specified.
799
800 If the input to this function is too large, there will be a
801 warning on stderr and the result will be zero.
802
803 The 'apmresult' parameter cannot be the other MAPM parameter.
804
805 -----------------------------------------------------------------------------
806
807 Prototype: void m_apm_pow(M_APM, int, M_APM, M_APM);
808
809 Example: M_APM apmresult, apm_x, apm_y;
810 int decimal_places;
811 m_apm_pow(apmresult, decimal_places, apm_x, apm_y);
812
813 This function will raise 'apm_x' to the 'apm_y' power and it
814 will put the result in 'apmresult'. The result will be accurate
815 to the number of decimal places specified.
816
817 If 'apm_y' is an integer value, m_apm_integer_pow will be
818 called automatically. (see the next function description).
819
820 The 'apmresult' parameter cannot be one of the other MAPM
821 parameters.
822
823 'apm_x' must be >= zero.
824 -----------------------------------------------------------------------------
825
826 Prototype: void m_apm_integer_pow(M_APM, int, M_APM, int);
827
828 Example: M_APM apmresult, apm_x;
829 int decimal_places, ipower;
830 m_apm_integer_pow(apmresult, decimal_places, apm_x, ipower);
831
832 This function will raise 'apm_x' to the 'ipower' power and it
833 will put the result in 'apmresult'. The result will be accurate
834 to the number of decimal places specified.
835
836 If calculating X^Y, this function should be used when 'Y'
837 is an integer. This function is considerably faster than the
838 generic 'm_apm_pow' function (when 'ipower' is not excessively
839 large). 'apm_x' and/or 'ipower' may be negative.
840
841 See the following function for a 'pow' function that does not
842 perform any rounding operation and is more appropriate for
843 integer only applications.
844
845 Note that 'ipower' is an integer and not a MAPM number.
846
847 The 'apmresult' parameter cannot be the other MAPM parameter.
848
849 -----------------------------------------------------------------------------
850
851 Prototype: void m_apm_integer_pow_nr(M_APM, M_APM, int);
852
853 Example: M_APM apmresult, apm_x;
854 int ipower;
855 m_apm_integer_pow_nr(apmresult, apm_x, ipower);
856
857 This function will raise 'apm_x' to the 'ipower' power and it
858 will put the result in 'apmresult'.
859
860 This function is similar to the above function except the
861 result is NOT ROUNDED (_nr). This function would typically be
862 used is an integer only application where the full precision of
863 the result is desired.
864
865 Note that 'ipower' is an integer and not a MAPM number.
866
867 'ipower' must be >= zero. 'ipower' < 0 creates a zero result
868 and a warning on stderr.
869
870 The 'apmresult' parameter cannot be the other MAPM parameter.
871
872 -----------------------------------------------------------------------------
873
874 Prototype: void m_apm_sin(M_APM, int, M_APM);
875
876 Example: M_APM apmresult, apm_num;
877 int decimal_places;
878 m_apm_sin(apmresult, decimal_places, apm_num);
879
880 This function will take the sine of 'apm_num' and it will put
881 the result in 'apmresult'. The input angle is assumed to be in
882 radians. The result will be accurate to the number of decimal
883 places specified.
884
885 The 'apmresult' parameter cannot be the other MAPM parameter.
886
887 -----------------------------------------------------------------------------
888
889 Prototype: void m_apm_cos(M_APM, int, M_APM);
890
891 Example: M_APM apmresult, apm_num;
892 int decimal_places;
893 m_apm_cos(apmresult, decimal_places, apm_num);
894
895 This function will take the cosine of 'apm_num' and it will put
896 the result in 'apmresult'. The input angle is assumed to be in
897 radians. The result will be accurate to the number of decimal
898 places specified.
899
900 The 'apmresult' parameter cannot be the other MAPM parameter.
901
902 -----------------------------------------------------------------------------
903
904 Prototype: void m_apm_sin_cos(M_APM, M_APM, int, M_APM);
905
906 Example: M_APM sin_val, cos_val, apm_num;
907 int decimal_places;
908 m_apm_sin_cos(sin_val, cos_val, decimal_places, apm_num);
909
910 This function computes the sin and cos of apm_num and it will
911 be more efficient than calling each function separately.
912 The input angle is assumed to be in radians. The results will
913 be accurate to the number of decimal places specified.
914
915 The 'sin_val' and 'cos_val' parameter cannot be the input
916 MAPM parameter.
917
918 -----------------------------------------------------------------------------
919
920 Prototype: void m_apm_tan(M_APM, int, M_APM);
921
922 Example: M_APM apmresult, apm_num;
923 int decimal_places;
924 m_apm_tan(apmresult, decimal_places, apm_num);
925
926 This function will take the tangent of 'apm_num' and it will put
927 the result in 'apmresult'. The input angle is assumed to be in
928 radians. The result will be accurate to the number of decimal
929 places specified.
930
931 The 'apmresult' parameter cannot be the other MAPM parameter.
932
933 -----------------------------------------------------------------------------
934
935 Prototype: void m_apm_arcsin(M_APM, int, M_APM);
936
937 Example: M_APM apmresult, apm_num;
938 int decimal_places;
939 m_apm_arcsin(apmresult, decimal_places, apm_num);
940
941 This function will take the arc sine of 'apm_num' and it will put
942 the result in 'apmresult'. The angle returned is in the range
943 -PI / 2 to +PI / 2. The result will be accurate to the number of
944 decimal places specified.
945
946 The 'apmresult' parameter cannot be the other MAPM parameter.
947
948 |Input| > 1 creates a zero result and a warning on stderr.
949
950 Note: 'm_apm_asin' may also be used for this function name.
951
952 -----------------------------------------------------------------------------
953
954 Prototype: void m_apm_arccos(M_APM, int, M_APM);
955
956 Example: M_APM apmresult, apm_num;
957 int decimal_places;
958 m_apm_arccos(apmresult, decimal_places, apm_num);
959
960 This function will take the arc cosine of 'apm_num' and it will
961 put the result in 'apmresult'. The angle returned is in the range
962 0 to +PI. The result will be accurate to the number of decimal
963 places specified.
964
965 The 'apmresult' parameter cannot be the other MAPM parameter.
966
967 |Input| > 1 creates a zero result and a warning on stderr.
968
969 Note: 'm_apm_acos' may also be used for this function name.
970
971 -----------------------------------------------------------------------------
972
973 Prototype: void m_apm_arctan(M_APM, int, M_APM);
974
975 Example: M_APM apmresult, apm_num;
976 int decimal_places;
977 m_apm_arctan(apmresult, decimal_places, apm_num);
978
979 This function will take the arc tangent of 'apm_num' and it will
980 put the result in 'apmresult'. The angle returned is in the range
981 -PI / 2 to +PI / 2. The result will be accurate to the number of
982 decimal places specified.
983
984 The 'apmresult' parameter cannot be the other MAPM parameter.
985
986 Note: 'm_apm_atan' may also be used for this function name.
987
988 -----------------------------------------------------------------------------
989
990 Prototype: void m_apm_arctan2(M_APM, int, M_APM, M_APM);
991
992 Example: M_APM apmresult, apm_x, apm_y;
993 int decimal_places;
994 m_apm_arctan2(apmresult, decimal_places, apm_y, apm_x);
995
996 This function will perform the 4 quadrant arc tangent of 'apm_y'
997 and 'apm_x' and it will put the result in 'apmresult'. The angle
998 returned is in the range -PI to +PI. The function will determine
999 the quadrant based on the signs of the 2 inputs. The result will
1000 be accurate to the number of decimal places specified.
1001
1002 The 'apmresult' parameter cannot be one of the other MAPM
1003 parameters.
1004
1005 x, y both = zero yields a zero result and a warning on stderr.
1006
1007 Note: 'm_apm_atan2' may also be used for this function name.
1008
1009 -----------------------------------------------------------------------------
1010
1011 Prototype: void m_apm_sinh(M_APM, int, M_APM);
1012
1013 Example: M_APM apmresult, apm_num;
1014 int decimal_places;
1015 m_apm_sinh(apmresult, decimal_places, apm_num);
1016
1017 This function will take the hyperbolic sine of 'apm_num' and
1018 it will put the result in 'apmresult'. The result will be
1019 accurate to the number of decimal places specified.
1020
1021 The 'apmresult' parameter cannot be the other MAPM parameter.
1022
1023 -----------------------------------------------------------------------------
1024
1025 Prototype: void m_apm_cosh(M_APM, int, M_APM);
1026
1027 Example: M_APM apmresult, apm_num;
1028 int decimal_places;
1029 m_apm_cosh(apmresult, decimal_places, apm_num);
1030
1031 This function will take the hyperbolic cosine of 'apm_num' and
1032 it will put the result in 'apmresult'. The result will be
1033 accurate to the number of decimal places specified.
1034
1035 The 'apmresult' parameter cannot be the other MAPM parameter.
1036
1037 -----------------------------------------------------------------------------
1038
1039 Prototype: void m_apm_tanh(M_APM, int, M_APM);
1040
1041 Example: M_APM apmresult, apm_num;
1042 int decimal_places;
1043 m_apm_tanh(apmresult, decimal_places, apm_num);
1044
1045 This function will take the hyperbolic tangent of 'apm_num' and
1046 it will put the result in 'apmresult'. The result will be
1047 accurate to the number of decimal places specified.
1048
1049 The 'apmresult' parameter cannot be the other MAPM parameter.
1050
1051 -----------------------------------------------------------------------------
1052
1053 Prototype: void m_apm_arcsinh(M_APM, int, M_APM);
1054
1055 Example: M_APM apmresult, apm_num;
1056 int decimal_places;
1057 m_apm_arcsinh(apmresult, decimal_places, apm_num);
1058
1059 This function will take the hyperbolic arc-sin of 'apm_num' and
1060 it will put the result in 'apmresult'. The result will be
1061 accurate to the number of decimal places specified.
1062
1063 The 'apmresult' parameter cannot be the other MAPM parameter.
1064
1065 Note: 'm_apm_asinh' may also be used for this function name.
1066
1067 -----------------------------------------------------------------------------
1068
1069 Prototype: void m_apm_arccosh(M_APM, int, M_APM);
1070
1071 Example: M_APM apmresult, apm_num;
1072 int decimal_places;
1073 m_apm_arccosh(apmresult, decimal_places, apm_num);
1074
1075 This function will take the hyperbolic arc-cos of 'apm_num' and
1076 it will put the result in 'apmresult'. The result will be
1077 accurate to the number of decimal places specified.
1078
1079 The 'apmresult' parameter cannot be the other MAPM parameter.
1080
1081 Input < 1 creates a zero result and a warning on stderr.
1082
1083 Note: 'm_apm_acosh' may also be used for this function name.
1084
1085 -----------------------------------------------------------------------------
1086
1087 Prototype: void m_apm_arctanh(M_APM, int, M_APM);
1088
1089 Example: M_APM apmresult, apm_num;
1090 int decimal_places;
1091 m_apm_arctanh(apmresult, decimal_places, apm_num);
1092
1093 This function will take the hyperbolic arc-tan of 'apm_num' and
1094 it will put the result in 'apmresult'. The result will be
1095 accurate to the number of decimal places specified.
1096
1097 The 'apmresult' parameter cannot be the other MAPM parameter.
1098
1099 |Input| >= 1 creates a zero result and a warning on stderr.
1100
1101 Note: 'm_apm_atanh' may also be used for this function name.
1102
1103 -----------------------------------------------------------------------------
1104