1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
|
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gmp.info
@include version.texi
@settitle GNU MP @value{VERSION}
@synindex tp fn
@iftex
@afourpaper
@end iftex
@comment %**end of header
@dircategory GNU libraries
@direntry
* gmp: (gmp). GNU Multiple Precision Arithmetic Library.
@end direntry
@c smallbook
@iftex
@finalout
@end iftex
@c Texinfo version 4 or up will be needed to process this into .info files.
@c
@c The edition number is in three places and the month/year in one, all
@c taken from version.texi. version.texi is created when you configure with
@c --enable-maintainer-mode, and is included in a distribution made with
@c "make dist".
@ifnottex
This file documents GNU MP, a library for arbitrary-precision arithmetic.
Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifnottex
@setchapternewpage on
@titlepage
@c use the new format for titles
@title GNU MP
@subtitle The GNU Multiple Precision Arithmetic Library
@subtitle Edition @value{EDITION}
@subtitle @value{UPDATED}
@author by Torbj@"orn Granlund, Swox AB
@email{tege@@swox.com}
@c Include the Distribution inside the titlepage so
@c that headings are turned off.
@tex
\global\parindent=0pt
\global\parskip=8pt
\global\baselineskip=13pt
@end tex
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330 @*
Boston, MA 02111-1307, USA @*
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage
@headings double
@ifnottex
@node Top, Copying, (dir), (dir)
@top GNU MP
This manual documents how to install and use the GNU multiple precision
arithmetic library, version @value{VERSION}.
@end ifnottex
@menu
* Copying:: GMP Copying Conditions (LGPL).
* Introduction to GMP:: Brief introduction to GNU MP.
* Installing GMP:: How to configure and compile the GMP library.
* GMP Basics:: What every GMP user should now.
* Reporting Bugs:: How to usefully report bugs.
* Integer Functions:: Functions for arithmetic on signed integers.
* Rational Number Functions:: Functions for arithmetic on rational numbers.
* Floating-point Functions:: Functions for arithmetic on floats.
* Low-level Functions:: Fast functions for natural numbers.
* Random Number Functions:: Functions for generating random numbers.
* BSD Compatible Functions:: All functions found in BSD MP.
* Custom Allocation:: How to customize the internal allocation.
* Contributors:: Who brings your this library?
* References:: Some useful papers and books to read.
* Concept Index::
* Function Index::
@end menu
@node Copying, Introduction to GMP, Top, Top
@comment node-name, next, previous, up
@unnumbered GNU MP Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying GNU MP
This library is @dfn{free}; this means that everyone is free to use it and
free to redistribute it on a free basis. The library is not in the public
domain; it is copyrighted and there are restrictions on its distribution, but
these restrictions are designed to permit everything that a good cooperating
citizen would want to do. What is not allowed is to try to prevent others
from further sharing any version of this library that they might get from
you.@refill
Specifically, we want to make sure that you have the right to give away copies
of the library, that you receive source code or else can get it if you want
it, that you can change this library or use pieces of it in new free programs,
and that you know you can do these things.@refill
To make sure that everyone has such rights, we have to forbid you to deprive
anyone else of these rights. For example, if you distribute copies of the GNU
MP library, you must give the recipients all the rights that you have. You
must make sure that they, too, receive or can get the source code. And you
must tell them their rights.@refill
Also, for our own protection, we must make certain that everyone finds out
that there is no warranty for the GNU MP library. If it is modified by
someone else and passed on, we want their recipients to know that what they
have is not what we distributed, so that any problems introduced by others
will not reflect on our reputation.@refill
The precise conditions of the license for the GNU MP library are found in the
Library General Public License that accompany the source code.@refill
@node Introduction to GMP, Installing GMP, Copying, Top
@comment node-name, next, previous, up
@chapter Introduction to GNU MP
@cindex Introduction
GNU MP is a portable library written in C for arbitrary precision arithmetic
on integers, rational numbers, and floating-point numbers. It aims to provide
the fastest possible arithmetic for all applications that need higher
precision than is directly supported by the basic C types.
Many applications use just a few hundred bits of precision; but some
applications may need thousands or even millions of bits. GMP is designed to
give good performance for both, by choosing algorithms based on the sizes of
the operands, and by carefully keeping the overhead at a minimum.
The speed of GMP is achieved by using fullwords as the basic arithmetic type,
by using sophisticated algorithms, by including carefully optimized assembly
code for the most common inner loops for many different CPUs, and by a general
emphasis on speed (as opposed to simplicity or elegance).
There is carefully optimized assembly code for these CPUs:
@cindex CPUs supported
ARM,
DEC Alpha 21064, 21164, and 21264,
AMD 29000,
AMD K6 and Athlon,
Hitachi SuperH and SH-2,
HPPA 1.0, 1.1 and 2.0,
Intel Pentium, Pentium Pro/Pentium II, generic x86,
Intel i960,
Motorola MC68000, MC68020, MC88100, and MC88110,
Motorola/IBM PowerPC 32 and 64,
National NS32000,
IBM POWER,
MIPS R3000, R4000,
SPARCv7, SuperSPARC, generic SPARCv8, UltraSPARC,
DEC VAX,
and Zilog Z8000.
Some optimizations also for Clipper, IBM ROMP (RT), and Pyramid AP/XP.
@cindex Mailing list
There is a mailing list for GMP users. To join it, send a mail to
@email{gmp-request@@swox.com} with the word @samp{subscribe} in the message
@strong{body} (not in the subject line).
@cindex Home page
@cindex Web page
For up-to-date information on GMP, please see the GMP Home Pages at
@uref{http://www.swox.com/gmp/}.
@section How to use this Manual
@cindex About this manual
Everyone should read @ref{GMP Basics}. If you need to install the library
yourself, you need to read @ref{Installing GMP}, too.
The rest of the manual can be used for later reference, although it is
probably a good idea to glance through it.
@node Installing GMP, GMP Basics, Introduction to GMP, Top
@comment node-name, next, previous, up
@chapter Installing GMP
@cindex Installing GMP
@cindex Configuring GMP
@noindent
GMP has an autoconf/automake/libtool based configuration system. On a
Unix-like system a basic build can be done with
@example
./configure
make
@end example
@noindent
Some self-tests can be run with
@example
make check
@end example
@noindent
And you can install (under @file{/usr/local} by default) with
@example
make install
@end example
@noindent
If you experience problems, please report them to @email{bug-gmp@@gnu.org}.
(@xref{Reporting Bugs}, for information on what to include in useful bug
reports.)
@menu
* Build Options::
* ABI and ISA::
* Notes for Package Builds::
* Notes for Particular Systems::
* Known Build Problems::
@end menu
@node Build Options, ABI and ISA, Installing GMP, Installing GMP
@section Build Options
@cindex Build options
@noindent
All the usual autoconf configure options are available, run @samp{./configure
--help} for a summary.
@table @asis
@item Non-Unix Systems
@samp{configure} needs various Unix-like tools installed. On an MS-DOS system
cygwin or djgpp should work. It might be possible to build without the help
of @samp{configure}, certainly all the code is there, but unfortunately you'll
be on your own.
@item Object Directory
To compile in a separate object directory, @command{cd} to that directory, and
prefix the configure command with the path to the GMP source directory. For
example @samp{../src/gmp/configure}. Not all @samp{make} programs have the
necessary features (@code{VPATH}) to support this. In particular, SunOS and
Slowaris @command{make} have bugs that make them unable to build from a
separate object directory. Use GNU @command{make} instead.
@item @option{--disable-shared}, @option{--disable-static}
By default both shared and static libraries are built (where possible), but
one or other can be disabled. Shared libraries are very slightly slower,
having a small cost on each function call, but result in smaller executables
and permit code sharing between separate running processes.
@item @option{--target=CPU-VENDOR-OS}
The build target can be specified in the usual way, for either native or cross
compilation.
If @option{--target} isn't given, @samp{./configure} builds for the host
system as determined by @samp{./config.guess}. On some systems this can't
distinguish between different CPUs in a family, and you should check the
guess. Running @samp{./config.guess} on the target system will also show the
relevant @samp{VENDOR-OS}, if you don't already know what it should be.
In general, if you want a library that runs as fast as possible, you should
configure GMP for the exact CPU type your system uses. However, this may mean
the binaries won't run on older members of the family, and might run slower on
other members, older or newer. The best idea is always to build GMP for the
exact machine type you intend to run it on.
The following CPU targets have specific assembly code support. See
@file{configure.in} for which @file{mpn} subdirectories get used by each.
@itemize @bullet
@c Keep this formatting, it's easy to read and it can be grepped to
@c automatically test that targets listed get through ./config.sub
@item
Alpha:
@samp{alpha},
@samp{alphaev5},
@samp{alphaev6}
@item
Hitachi:
@samp{sh},
@samp{sh2}
@item
HPPA:
@samp{hppa1.0},
@samp{hppa1.1},
@samp{hppa2.0},
@samp{hppa2.0w}
@item
MIPS:
@samp{mips},
@samp{mips3},
@item
Motorola:
@samp{m68000},
@samp{m68k},
@samp{m88k},
@samp{m88110}
@item
POWER:
@samp{power1},
@samp{power2},
@samp{power2sc},
@samp{powerpc},
@samp{powerpc64}
@item
SPARC:
@samp{sparc},
@samp{sparcv8},
@samp{microsparc},
@samp{supersparc},
@samp{sparcv9},
@samp{ultrasparc},
@samp{sparc64}
@item
80x86 family:
@samp{i386},
@samp{i486},
@samp{i586},
@samp{pentium},
@samp{pentiummmx},
@samp{pentiumpro},
@samp{pentium2},
@samp{pentium3},
@samp{k6},
@samp{k62},
@samp{k63},
@samp{athlon}
@item
Other:
@samp{a29k},
@samp{arm},
@samp{clipper},
@samp{i960},
@samp{ns32k},
@samp{pyramid},
@samp{vax},
@samp{z8k}
@end itemize
CPUs not listed use generic C code. If some of the assembly code causes
problems, the generic C code can be selected with CPU @samp{none}.
@item @option{CC}, @option{CFLAGS}
The C compiler used is chosen from among some likely candidates, with GCC
normally preferred if it's present. The usual @samp{CC=whatever} can be
passed to @samp{./configure} to choose something different.
For some configurations specific compiler flags are set based on the target
CPU and compiler, for others @samp{CFLAGS="-whatever"} can be used to
set the best flags.
If @samp{CC} is set then @samp{CFLAGS} must also be set. This applies even if
@samp{CC} is merely one of the choices GMP would make itself. This may change
in a future release.
@item @option{--disable-alloca}
@cindex Stack overflow segfaults
@cindex @code{alloca}
By default, GMP allocates temporary workspace using @code{alloca} if that
function is available, or @code{malloc} if not. If you're working with large
numbers and @code{alloca} overflows the available stack space, you can build
with @option{--disable-alloca} to use @code{malloc} instead. @code{malloc}
will probably be slightly slower than @code{alloca}.
When not using @code{alloca}, it's actually the allocation function
selected with @code{mp_set_memory_functions} that's used, this being
@code{malloc} by default. @xref{Custom Allocation}.
Depending on your system, the only indication of stack overflow might be a
segmentation violation. It might be possible to increase available stack
space with @command{limit}, @command{ulimit} or @code{setrlimit}, or under
DJGPP with @command{stubedit} or @code{_stklen}.
@item @option{--enable-fft}
By default multiplications are done using Karatsuba and 3-way Toom-Cook
algorithms, but a Fermat FFT can be enabled, for use on large to very large
operands. Currently the FFT is recommended only for knowledgeable users who
check the algorithm thresholds for their CPU.
@item @option{--enable-mpbsd}
The Berkeley MP compatibility library (@file{libmp.a}) and header file
(@file{mp.h}) are built and installed only if @option{--enable-mpbsd} is used.
@xref{BSD Compatible Functions}.
@item @option{MPN_PATH}
Various assembler versions of mpn subroutines are provided, and, for a given
CPU target, a search is made though a path to choose a version of each. For
example @samp{sparcv8} has path @samp{"sparc32/v8 sparc32 generic"}, which
means it looks first for v8 code, falls back on plain sparc32, and finally
falls back on generic C. Knowledgeable users with special requirements can
specify a path with @samp{MPN_PATH="dir list"}. This will normally be
unnecessary because all sensible paths should be available under one or other
CPU target.
@item Demonstration Programs
@cindex Demonstration programs
@cindex Example programs
The @file{demos} subdirectory has some sample programs using GMP. These
aren't built or installed, but there's a @file{Makefile} with rules for them.
For instance, @samp{make pexpr} and then @samp{./pexpr 68^975+10}.
@item Documentation
The document you're now reading is @file{gmp.texi}. The usual automake
targets are available to make @file{gmp.ps} and/or @file{gmp.dvi}. Some
supplementary notes can be found in the @file{doc} subdirectory.
@end table
@need 2000
@node ABI and ISA, Notes for Package Builds, Build Options, Installing GMP
@section ABI and ISA
@cindex ABI
@cindex ISA
ABI (Application Binary Interface) refers to the calling conventions between
functions, meaning what registers are used and what sizes the various C data
types are. ISA (Instruction Set Architecture) refers to the instructions and
registers a CPU has available.
Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI defined, the
latter for compatibility with older CPUs in the family. GMP chooses the best
ABI available for a given target system, and this generally gives
significantly greater speed.
The burden is on application programs and cooperating libraries to ensure they
match the ABI chosen by GMP. Fortunately this presents a difficulty only on a
few systems, and if you have one of them then the performance gains are enough
to make it worth the trouble.
Some of what's described in this section may change in future releases of GMP.
@table @asis
@need 1000
@item HPPA 2.0
CPU target @samp{hppa2.0} uses the hppa2.0n 32-bit ABI, but either a 32-bit or
64-bit limb.
A 64-bit limb is available on HP-UX 10 or up when using @command{c89}. No
@command{gcc} support is planned for 64-bit operations in this ABI.
Applications must be compiled with the same options as GMP, which means
@example
c89 +DA2.0 +e -D_LONG_LONG_LIMB
@end example
A 32-bit limb is used in other cases, and no special compiler options are
needed.
CPU target @samp{hppa2.0w} uses the hppa2.0w 64-bit ABI, which is available on
HP-UX 11 or up when using @command{c89}. @command{gcc} support for this is in
progress. Applications must be compiled for the same ABI, which means
@example
c89 +DD64
@end example
@need 1000
@item MIPS 3 and 4 under IRIX 6
Targets @samp{mips*-*-irix6*} use the n32 ABI and a 64-bit limb. Applications
must be compiled for the same ABI, which means either
@example
gcc -mabi=n32
cc -n32
@end example
@need 1000
@item PowerPC 64
CPU target @samp{powerpc64} uses either the 32-bit ABI or the AIX 64-bit ABI.
The latter is used on targets @samp{powerpc64-*-aix*} and applications must be
compiled using either
@example
gcc -maix64
xlc -q64
@end example
On other systems the 32-bit ABI is used, but with 64-bit limbs provided by
@code{long long} in @command{gcc}. Applications must be compiled using
@example
gcc -D_LONG_LONG_LIMB
@end example
@need 1000
@item Sparc V9
On a sparc v9 CPU, either the v8plus 32-bit ABI or v9 64-bit ABI is used.
Targets @samp{ultrasparc*-*-solaris2.[7-9]}, @samp{sparcv9-*-solaris2.[7-9]}
and @samp{sparc64-*-linux*} use the v9 ABI, if the compiler supports it.
Other targets use the v8plus ABI (but with as much of the v9 ISA as possible
in the circumstances). Note that Solaris prior to 2.7 doesn't save all
registers properly, and hence uses the v8plus ABI.
For the v8plus ABI, applications can be compiled with either
@example
gcc -mv8plus
cc -xarch=v8plus
@end example
For the v9 ABI, applications must be compiled with either
@example
gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9
cc -xarch=v9
@end example
Don't be confused by the names of these options, they're called @samp{arch}
but they effectively control the ABI.
@end table
@need 2000
@node Notes for Package Builds, Notes for Particular Systems, ABI and ISA, Installing GMP
@section Notes for Package Builds
@cindex Build notes for binary packaging
@cindex Packaged builds
GMP should present no great difficulties for packaging in a binary
distribution.
@cindex Libtool versioning
Libtool is used to build the library and @samp{-version-info} is set
appropriately, having started from @samp{3:0:0} in GMP 3.0. The GMP 3 series
will be upwardly binary compatible in each release, but may be adding
additional function interfaces. On systems where libtool versioning is not
fully checked by the loader, an auxiliary mechanism may be needed to express
that a dynamic linked application depends on a new enough minor version of
GMP.
When building a package for a CPU family, care should be taken to use
@samp{--target} to choose the least common denominator among the CPUs which
might use the package. For example this might necessitate @samp{i386} for
x86s, or plain @samp{sparc} (meaning V7) for SPARCs.
Users who care about speed will want GMP built for their exact CPU type, to
make use of the available optimizations. Providing a way to suitably rebuild
a package may be useful. This could be as simple as making it possible for a
user to omit @samp{--target} in a build so @samp{./config.guess} will detect
the CPU. But a way to manually specify a @samp{--target} will be wanted for
systems where @samp{./config.guess} is inexact.
@need 2000
@node Notes for Particular Systems, Known Build Problems, Notes for Package Builds, Installing GMP
@section Notes for Particular Systems
@cindex Build notes for particular systems
@table @asis
@c This section is more or less meant for notes about performance or about
@c build problems that have been worked around but might leave a user
@c scratching their head. Fun with different ABIs on a system belongs in the
@c above section.
@item AIX 4.3
Targets @samp{*-*-aix4.[3-9]*} have shared libraries disabled since they seem
to fail on AIX 4.3.
@item OpenBSD 2.6
@command{m4} in this release of OpenBSD has a bug in @code{eval} that makes it
unsuitable for @file{.asm} file processing. @samp{./configure} will detect
the problem and either abort or choose another m4 in the @env{PATH}. The bug
is fixed in OpenBSD 2.7, so either upgrade or use GNU m4.
@item Sparc V8
Using CPU target @samp{sparcv8} or @samp{supersparc} on relevant systems will
give a significant performance increase over the V7 code.
@item SunOS 4
@command{/usr/bin/m4} lacks various features needed to process @file{.asm}
files, and instead @samp{./configure} will automatically use
@command{/usr/5bin/m4}, which we believe is always available (if not then use
GNU m4).
@item x86 Pentium and PentiumPro
The Intel Pentium P5 code is good for its intended P5, but quite slow when run
on Intel P6 class chips (PPro, P-II, P-III)@. @samp{i386} is a better choice
if you're making binaries that must run on both.
@item x86 MMX and old GAS
Old versions of GAS don't support MMX instructions, in particular version
1.92.3 that comes with FreeBSD 2.2.8 doesn't (and unfortunately there's no
newer assembler for that system).
If the target CPU has MMX code but the assembler doesn't support it, a warning
is given and non-MMX code is used instead. This will be an inferior build,
since the MMX code that's present is there because it's faster than the
corresponding plain integer code.
@item x86 GCC 2.95.2 @samp{-march=pentiumpro}
GCC 2.95.2 miscompiles @file{mpz/powm.c} when @samp{-march=pentiumpro} is
used, so that option is omitted from the @env{CFLAGS} chosen for relevant
CPUs. The problem is believed to be fixed in GCC 2.96.
@end table
@need 2000
@node Known Build Problems, , Notes for Particular Systems, Installing GMP
@section Known Build Problems
@cindex Build problems known
@c This section is more or less meant for known build problems that are not
@c otherwise worked around and require some sort of manual intervention.
You might find more up-to-date information at @uref{http://www.swox.com/gmp/}.
@table @asis
@item Generic C on a 64-bit system
When making a generic C build using @samp{--target=none} on a 64-bit system
(meaning where @code{unsigned long} is 64 bits), @code{BITS_PER_MP_LIMB},
@code{BITS_PER_LONGINT} and @code{BYTES_PER_MP_LIMB} in
@file{mpn/generic/gmp-mparam.h} need to be changed to 64 and 8. This will
hopefully be automated in a future version of GMP.
@item NeXT prior to 3.3
The system compiler on old versions of NeXT was a massacred and old GCC, even
if it called itself @file{cc}. This compiler cannot be used to build GMP, you
need to get a real GCC, and install that before you compile GMP. (NeXT may
have fixed this in release 3.3 of their system.)
@item POWER and PowerPC
Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP on POWER or
PowerPC. If you want to use GCC for these machines, get GCC 2.7.2.1 (or
later).
@item Sequent Symmetry
Use the GNU assembler instead of the system assembler, since the latter has
serious bugs.
@item Stripped Libraries
@cindex Stripped libraries
GNU binutils @samp{strip} should not be used on the static libraries
@file{libgmp.a} and @file{libmp.a}, neither directly nor via @samp{make
install-strip}. It can be used on the shared libraries @file{libgmp.so} and
@file{libmp.so} though.
Currently (binutils 2.10.0), @samp{strip} extracts archives into a single
directory, but GMP contains multiple object files of the same name (eg. three
versions of @file{init.o}), and they overwrite each other, leaving only the
one that happens to be last.
If stripped static libraries are wanted, the suggested workaround is to build
normally, strip the separate object files, and do another @samp{make all} to
rebuild. Alternately @samp{CFLAGS} with @samp{-g} omitted can always be used
if it's just debugging which is unwanted.
@item SunOS 4 Native Tools
The setting for @code{GSYM_PREFIX} in @file{config.m4} may be incorrectly
determined when using the native @command{grep}, leading at link-time to
undefined symbols like @code{___gmpn_add_n}. To fix this, after running
@samp{./configure}, change the relevant line in @file{config.m4} to
@samp{define(<GSYM_PREFIX>, <_>)}.
The @command{ranlib} command will need to be run manually when building a
static library with the native @command{ar}. After @samp{make}, run
@samp{ranlib .libs/libgmp.a}, and when using @option{--enable-mpbsd} run
@samp{ranlib .libs/libmp.a} too.
@item VAX running Ultrix
You need to build and install the GNU assembler before you compile GMP. The VAX
assembly in GMP uses an instruction (@code{jsobgtr}) that cannot be assembled by
the Ultrix assembler.
@end table
@node GMP Basics, Reporting Bugs, Installing GMP, Top
@comment node-name, next, previous, up
@chapter GMP Basics
@cindex Basics
@cindex @file{gmp.h}
All declarations needed to use GMP are collected in the include file
@file{gmp.h}. It is designed to work with both C and C++ compilers.
@strong{Using functions, macros, data types, etc.@: not documented in this
manual is strongly discouraged. If you do so your application is guaranteed
to be incompatible with future versions of GMP.}
@menu
* Nomenclature and Types:: Which data types are there?
* Function Classes:: How the functions are organized.
* GMP Variable Conventions:: Some rules and hints about variables.
* GMP and Reentrancy:: What about reentrancy?
* Useful Macros and Constants:: Convenient helpers.
* Compatibility with older versions:: Compatibility issues.
* Getting the Latest Version of GMP:: How to get the software.
@end menu
@node Nomenclature and Types, Function Classes, GMP Basics, GMP Basics
@section Nomenclature and Types
@cindex Nomenclature
@cindex Types
@cindex Integer
@tindex @code{mpz_t}
@noindent
In this manual, @dfn{integer} usually means a multiple precision integer, as
defined by the GMP library. The C data type for such integers is @code{mpz_t}.
Here are some examples of how to declare such integers:
@example
mpz_t sum;
struct foo @{ mpz_t x, y; @};
mpz_t vec[20];
@end example
@cindex Rational number
@tindex @code{mpq_t}
@noindent
@dfn{Rational number} means a multiple precision fraction. The C data type
for these fractions is @code{mpq_t}. For example:
@example
mpq_t quotient;
@end example
@cindex Floating-point number
@tindex @code{mpf_t}
@noindent
@dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision
mantissa with a limited precision exponent. The C data type for such objects
is @code{mpf_t}.
@cindex Limb
@tindex @code{mp_limb_t}
@noindent
A @dfn{limb} means the part of a multi-precision number that fits in a single
word. (We chose this word because a limb of the human body is analogous to a
digit, only larger, and containing several digits.) Normally a limb contains
32 or 64 bits. The C data type for a limb is @code{mp_limb_t}.
@node Function Classes, GMP Variable Conventions, Nomenclature and Types, GMP Basics
@section Function Classes
@cindex Function classes
There are six classes of functions in the GMP library:
@enumerate
@item
Functions for signed integer arithmetic, with names beginning with
@code{mpz_}. The associated type is @code{mpz_t}. There are about 100
functions in this class.
@item
Functions for rational number arithmetic, with names beginning with
@code{mpq_}. The associated type is @code{mpq_t}. There are about 20
functions in this class, but the functions in the previous class can be used
for performing arithmetic on the numerator and denominator separately.
@item
Functions for floating-point arithmetic, with names beginning with
@code{mpf_}. The associated type is @code{mpf_t}. There are about 50
functions is this class.
@item
Functions compatible with Berkeley GMP, such as @code{itom}, @code{madd}, and
@code{mult}. The associated type is @code{MINT}.
@item
Fast low-level functions that operate on natural numbers. These are used by
the functions in the preceding groups, and you can also call them directly
from very time-critical user programs. These functions' names begin with
@code{mpn_}. There are about 30 (hard-to-use) functions in this class.
The associated type is array of @code{mp_limb_t}.
@item
Miscellaneous functions. Functions for setting up custom allocation and
functions for generating random numbers.
@end enumerate
@node GMP Variable Conventions, GMP and Reentrancy, Function Classes, GMP Basics
@section GMP Variable Conventions
@cindex Variable conventions
@cindex Parameter conventions
@cindex Conventions for variables
As a general rule, all GMP functions expect output arguments before input
arguments. This notation is based on an analogy with the assignment operator.
(The BSD MP compatibility functions disobey this rule, having the output
argument(s) last.)
GMP lets you use the same variable for both input and output in one call. For
example, the main function for integer multiplication, @code{mpz_mul}, can be
used to square @code{x} and put the result back in @code{x} with
@example
mpz_mul (x, x, x);
@end example
Before you can assign to a GMP variable, you need to initialize it by calling
one of the special initialization functions. When you're done with a
variable, you need to clear it out, using one of the functions for that
purpose. Which function to use depends on the type of variable. See the
chapters on integer functions, rational number functions, and floating-point
functions for details.
A variable should only be initialized once, or at least cleared out between
each initialization. After a variable has been initialized, it may be
assigned to any number of times.
For efficiency reasons, avoid initializing and clearing out a GMP variable in
a loop. Instead, initialize it before entering the loop, and clear it out
after the loop has exited.
GMP variables are small, containing only a couple of sizes, and pointers to
allocated data. Once you have initialized a GMP variable, you don't need to
worry about space allocation. All functions in GMP automatically allocate
additional space when a variable does not already have enough. They do not,
however, reduce the space when a smaller value is stored. Most of the time
this policy is best, since it avoids frequent re-allocation.
When a variable of type @code{mpz_t} is used as a function parameter, it's
effectively a call-by-reference, meaning anything the function does to it will
be be done to the original in the caller. When a function is going to return
an @code{mpz_t} result, it should provide a separate parameter or parameters
that it sets, like the GMP library functions do. A @code{return} of an
@code{mpz_t} doesn't return the object, only a pointer to it, and this is
almost certainly not what you want. All this applies to @code{mpq_t} and
@code{mpf_t} too.
Here's an example function accepting an @code{mpz_t} parameter, doing a
certain calculation, and returning a result.
@example
void
myfunction (mpz_t result, mpz_t param, unsigned long n)
@{
unsigned long i;
mpz_mul_ui (result, param, n);
for (i = 1; i < n; i++)
mpz_add_ui (result, result, i*7);
@}
int
main (void)
@{
mpz_t r, n;
mpz_init (r);
mpz_init_set_str (n, "123456", 0);
myfunction (r, n, 20L);
mpz_out_str (stdout, 10, r); printf ("\n");
return 0;
@}
@end example
This example will work if @code{result} and @code{param} are the same
variable, just like the library functions. But sometimes this is tricky to
arrange, and an application might not want to bother for its own subroutines.
@code{mpz_t} is actually implemented as a one-element array of a certain
structure type. This is why using it to declare a variable gives an object
with the fields GMP needs, but then using it as a parameter passes a pointer
to the object. Note that the actual contents of an @code{mpz_t} are for
internal use only and you should not access them directly if you want your
code to be compatible with future GMP releases.
@node GMP and Reentrancy, Useful Macros and Constants, GMP Variable Conventions, GMP Basics
@section GMP and Reentrancy
@cindex Reentrancy
@cindex Thread safety
@cindex Multi-threading
The GMP code is reentrant and thread-safe, with some exceptions:
@itemize @bullet
@item
The function @code{mpf_set_default_prec} saves the selected precision in
a global variable.
@item
The function @code{mp_set_memory_functions} uses several global
variables for storing the selected memory allocation functions.
@item
If the memory allocation functions set by a call to
@code{mp_set_memory_functions} (or @code{malloc} and friends by default) are
not reentrant, GMP will not be reentrant either.
@item
The old random number functions (@code{mpz_random}, etc) use a random number
generator from the C library, usually @code{mrand48} or @code{random}. These
routines are not reentrant, since they rely on global state.
(However the newer random number functions that accept a
@code{gmp_randstate_t} parameter are reentrant.)
@end itemize
@need 2000
@node Useful Macros and Constants, Compatibility with older versions, GMP and Reentrancy, GMP Basics
@section Useful Macros and Constants
@cindex Useful macros and constants
@cindex Constants
@deftypevr {Global Constant} {const int} mp_bits_per_limb
@cindex Bits per limb
@cindex Limb size
The number of bits per limb.
@end deftypevr
@defmac __GNU_MP_VERSION
@defmacx __GNU_MP_VERSION_MINOR
@defmacx __GNU_MP_VERSION_PATCHLEVEL
@cindex Version number
@cindex GMP version number
The major and minor GMP version, and patch level, respectively, as integers.
For GMP i.j, these numbers will be i, j, and 0, respectively.
For GMP i.j.k, these numbers will be i, j, and k, respectively.
@end defmac
@node Compatibility with older versions, Getting the Latest Version of GMP, Useful Macros and Constants, GMP Basics
@section Compatibility with older versions
@cindex Compatibility with older versions
@cindex Upward compatibility
This version of GMP is upwardly binary compatible with versions 3.0 and 3.0.1,
and upwardly compatible at the source level with versions 2.0, 2.0.1, and
2.0.2, with the following exceptions.
@itemize @bullet
@item
@code{mpn_gcd} had its source arguments swapped as of GMP 3.0 for consistency
with other @code{mpn} functions.
@item
@code{mpf_get_prec} counted precision slightly differently in GMP 3.0 and
3.0.1, but in 3.1 has reverted to the 2.0.x style.
@end itemize
There are a number of compatibility issues between GMP 1 and GMP 2 that of
course also apply when porting applications from GMP 1 to GMP 3. Please
see the GMP 2 manual for details.
@c @enumerate
@c @item Integer division functions round the result differently. The obsolete
@c functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv},
@c @code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the
@c quotient towards
@c @ifinfo
@c @minus{}infinity).
@c @end ifinfo
@c @iftex
@c @tex
@c $-\infty$).
@c @end tex
@c @end iftex
@c There are a lot of functions for integer division, giving the user better
@c control over the rounding.
@c @item The function @code{mpz_mod} now compute the true @strong{mod} function.
@c @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use
@c @strong{mod} for reduction.
@c @item The assignment functions for rational numbers do no longer canonicalize
@c their results. In the case a non-canonical result could arise from an
@c assignment, the user need to insert an explicit call to
@c @code{mpq_canonicalize}. This change was made for efficiency.
@c @item Output generated by @code{mpz_out_raw} in this release cannot be read
@c by @code{mpz_inp_raw} in previous releases. This change was made for making
@c the file format truly portable between machines with different word sizes.
@c @item Several @code{mpn} functions have changed. But they were intentionally
@c undocumented in previous releases.
@c @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui}
@c are now implemented as macros, and thereby sometimes evaluate their
@c arguments multiple times.
@c @item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1
@c for 0^0. (In version 1, they yielded 0.)
@c @end enumerate
@node Getting the Latest Version of GMP, , Compatibility with older versions, GMP Basics
@section Getting the Latest Version of GMP
@cindex Latest version of GMP
@cindex Anonymous FTP of latest version
@cindex FTP of latest version
The latest version of the GMP library is available at
@uref{ftp://ftp.gnu.org/pub/gnu/gmp}. Many sites around the world mirror
@samp{ftp.gnu.org}; please use a mirror site near you, see
@uref{http://www.gnu.org/order/ftp.html}.
@node Reporting Bugs, Integer Functions, GMP Basics, Top
@comment node-name, next, previous, up
@chapter Reporting Bugs
@cindex Reporting bugs
@cindex Bug reporting
If you think you have found a bug in the GMP library, please investigate it
and report it. We have made this library available to you, and it is not too
much to ask you to report the bugs you find. Before you report a bug, you may
want to check @uref{http://www.swox.com/gmp/} for patches for this release.
Please include the following in any report,
@itemize @bullet
@item
The GMP version number, and if pre-packaged or patched then say so.
@item
A test program that makes it possible for us to reproduce the bug. Include
instructions on how to run the program.
@item
A description of what is wrong. If the results are incorrect, in what way.
If you get a crash, say so.
@item
If you get a crash, include a stack backtrace from the debugger if it's
informative (@samp{where} in @command{gdb}, or @samp{$C} in @command{adb}).
@item
@strong{Please do not send core dumps, executables or @command{strace}s.}
@item
The configuration options you used when building GMP, if any.
@item
The name of the compiler and its version. For @command{gcc}, get the version
with @samp{gcc -v}, otherwise perhaps @samp{what `which cc`}, or similar.
@item
The output from running @samp{uname -a}.
@item
The output from running @samp{./config.guess}.
@item
If the bug is related to @samp{configure}, then the contents of
@file{config.log}.
@item
If the bug is related to an @file{asm} file not assembling, then the contents
of @file{config.m4}.
@end itemize
It is not uncommon that an observed problem is actually due to a bug in the
compiler; the GMP code tends to explore interesting corners in compilers.
If your bug report is good, we will do our best to help you get a corrected
version of the library; if the bug report is poor, we won't do anything about
it (except maybe ask you to send a better report).
Send your report to: @email{bug-gmp@@gnu.org}.
If you think something in this manual is unclear, or downright incorrect, or if
the language needs to be improved, please send a note to the same address.
@node Integer Functions, Rational Number Functions, Reporting Bugs, Top
@comment node-name, next, previous, up
@chapter Integer Functions
@cindex Integer functions
This chapter describes the GMP functions for performing integer arithmetic.
These functions start with the prefix @code{mpz_}.
GMP integers are stored in objects of type @code{mpz_t}.
@menu
* Initializing Integers::
* Assigning Integers::
* Simultaneous Integer Init & Assign::
* Converting Integers::
* Integer Arithmetic::
* Integer Division::
* Integer Exponentiation::
* Integer Roots::
* Number Theoretic Functions::
* Integer Comparisons::
* Integer Logic and Bit Fiddling::
* I/O of Integers::
* Integer Random Numbers::
* Miscellaneous Integer Functions::
@end menu
@node Initializing Integers, Assigning Integers, Integer Functions, Integer Functions
@comment node-name, next, previous, up
@section Initialization Functions
@cindex Integer initialization functions
@cindex Initialization functions
The functions for integer arithmetic assume that all integer objects are
initialized. You do that by calling the function @code{mpz_init}.
@deftypefun void mpz_init (mpz_t @var{integer})
Initialize @var{integer} with limb space and set the initial numeric value to
0. Each variable should normally only be initialized once, or at least cleared
out (using @code{mpz_clear}) between each initialization.
@end deftypefun
Here is an example of using @code{mpz_init}:
@example
@{
mpz_t integ;
mpz_init (integ);
@dots{}
mpz_add (integ, @dots{});
@dots{}
mpz_sub (integ, @dots{});
/* Unless the program is about to exit, do ... */
mpz_clear (integ);
@}
@end example
@noindent
As you can see, you can store new values any number of times, once an
object is initialized.
@deftypefun void mpz_clear (mpz_t @var{integer})
Free the limb space occupied by @var{integer}. Make sure to call this
function for all @code{mpz_t} variables when you are done with them.
@end deftypefun
@deftypefun {void *} _mpz_realloc (mpz_t @var{integer}, mp_size_t @var{new_alloc})
Change the limb space allocation to @var{new_alloc} limbs. This function is
not normally called from user code, but it can be used to give memory back to
the heap, or to increase the space of a variable to avoid repeated automatic
re-allocation.
@end deftypefun
@deftypefun void mpz_array_init (mpz_t @var{integer_array}[], size_t @var{array_size}, mp_size_t @var{fixed_num_bits})
Allocate @strong{fixed} limb space for all @var{array_size} integers in
@var{integer_array}. The fixed allocation for each integer in the array is
enough to store @var{fixed_num_bits}. If the fixed space will be insufficient
for storing the result of a subsequent calculation, the result is
unpredictable.
This function is useful for decreasing the working set for some algorithms
that use large integer arrays.
There is no way to de-allocate the storage allocated by this function.
Don't call @code{mpz_clear}!
@end deftypefun
@node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions
@comment node-name, next, previous, up
@section Assignment Functions
@cindex Integer assignment functions
@cindex Assignment functions
These functions assign new values to already initialized integers
(@pxref{Initializing Integers}).
@deftypefun void mpz_set (mpz_t @var{rop}, mpz_t @var{op})
@deftypefunx void mpz_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
@deftypefunx void mpz_set_si (mpz_t @var{rop}, signed long int @var{op})
@deftypefunx void mpz_set_d (mpz_t @var{rop}, double @var{op})
@deftypefunx void mpz_set_q (mpz_t @var{rop}, mpq_t @var{op})
@deftypefunx void mpz_set_f (mpz_t @var{rop}, mpf_t @var{op})
Set the value of @var{rop} from @var{op}.
@end deftypefun
@deftypefun int mpz_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
Set the value of @var{rop} from @var{str}, a '\0'-terminated C string in base
@var{base}. White space is allowed in the string, and is simply ignored. The
base may vary from 2 to 36. If @var{base} is 0, the actual base is determined
from the leading characters: if the first two characters are `0x' or `0X',
hexadecimal is assumed, otherwise if the first character is `0', octal is
assumed, otherwise decimal is assumed.
This function returns 0 if the entire string up to the '\0' is a valid
number in base @var{base}. Otherwise it returns @minus{}1.
@end deftypefun
[It turns out that it is not entirely true that this function ignores
white-space. It does ignore it between digits, but not after a minus sign or
within within or after "0x". We are considering changing the definition of
this function, making it fail when there is any white-space in the input,
since that makes a lot of sense. Please tell us your opinion about this
change. Do you really want it to accept "3 14" as meaning 314 as it does
now?]
@deftypefun void mpz_swap (mpz_t @var{rop1}, mpz_t @var{rop2})
Swap the values @var{rop1} and @var{rop2} efficiently.
@end deftypefun
@node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions
@comment node-name, next, previous, up
@section Combined Initialization and Assignment Functions
@cindex Initialization and assignment functions
@cindex Integer init and assign
For convenience, GMP provides a parallel series of initialize-and-set functions
which initialize the output and then store the value there. These functions'
names have the form @code{mpz_init_set@dots{}}
Here is an example of using one:
@example
@{
mpz_t pie;
mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
@dots{}
mpz_sub (pie, @dots{});
@dots{}
mpz_clear (pie);
@}
@end example
@noindent
Once the integer has been initialized by any of the @code{mpz_init_set@dots{}}
functions, it can be used as the source or destination operand for the ordinary
integer functions. Don't use an initialize-and-set function on a variable
already initialized!
@deftypefun void mpz_init_set (mpz_t @var{rop}, mpz_t @var{op})
@deftypefunx void mpz_init_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
@deftypefunx void mpz_init_set_si (mpz_t @var{rop}, signed long int @var{op})
@deftypefunx void mpz_init_set_d (mpz_t @var{rop}, double @var{op})
Initialize @var{rop} with limb space and set the initial numeric value from
@var{op}.
@end deftypefun
@deftypefun int mpz_init_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
Initialize @var{rop} and set its value like @code{mpz_set_str} (see its
documentation above for details).
If the string is a correct base @var{base} number, the function returns 0;
if an error occurs it returns @minus{}1. @var{rop} is initialized even if
an error occurs. (I.e., you have to call @code{mpz_clear} for it.)
@end deftypefun
@node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions
@comment node-name, next, previous, up
@section Conversion Functions
@cindex Integer conversion functions
@cindex Conversion functions
This section describes functions for converting GMP integers to standard C
types. Functions for converting @emph{to} GMP integers are described in
@ref{Assigning Integers} and @ref{I/O of Integers}.
@deftypefun mp_limb_t mpz_getlimbn (mpz_t @var{op}, mp_size_t @var{n})
Return limb #@var{n} from @var{op}. This function allows for very efficient
decomposition of a number in its limbs.
The function @code{mpz_size} can be used to determine the useful range for
@var{n}.
@end deftypefun
@deftypefun {unsigned long int} mpz_get_ui (mpz_t @var{op})
Return the least significant part from @var{op}. This function combined with
@* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned long
int))} can be used to decompose an integer into unsigned longs.
@end deftypefun
@deftypefun {signed long int} mpz_get_si (mpz_t @var{op})
If @var{op} fits into a @code{signed long int} return the value of @var{op}.
Otherwise return the least significant part of @var{op}, with the same sign
as @var{op}.
If @var{op} is too large to fit in a @code{signed long int}, the returned
result is probably not very useful. To find out if the value will fit, use
the function @code{mpz_fits_slong_p}.
@end deftypefun
@deftypefun double mpz_get_d (mpz_t @var{op})
Convert @var{op} to a double.
@end deftypefun
@deftypefun {char *} mpz_get_str (char *@var{str}, int @var{base}, mpz_t @var{op})
Convert @var{op} to a string of digits in base @var{base}. The base may vary
from 2 to 36.
If @var{str} is @code{NULL}, space for the result string is allocated using the
default allocation function.
If @var{str} is not @code{NULL}, it should point to a block of storage enough large
for the result. To find out the right amount of space to provide for
@var{str}, use @code{mpz_sizeinbase (@var{op}, @var{base}) + 2}. The two
extra bytes are for a possible minus sign, and for the terminating null
character.
A pointer to the result string is returned. This pointer will will either
equal @var{str}, or if that is @code{NULL}, will point to the allocated storage.
@end deftypefun
@need 2000
@node Integer Arithmetic, Integer Division, Converting Integers, Integer Functions
@comment node-name, next, previous, up
@section Arithmetic Functions
@cindex Integer arithmetic functions
@cindex Arithmetic functions
@deftypefun void mpz_add (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx void mpz_add_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} + @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} + @var{op2}$.
@end tex
@end deftypefun
@deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx void mpz_sub_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
Set @var{rop} to @var{op1} @minus{} @var{op2}.
@end deftypefun
@deftypefun void mpz_mul (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx void mpz_mul_si (mpz_t @var{rop}, mpz_t @var{op1}, long int @var{op2})
@deftypefunx void mpz_mul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} times @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} \times @var{op2}$.
@end tex
@end deftypefun
@deftypefun void mpz_addmul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Add @var{op1} times @var{op2} to @var{rop}.
@end ifnottex
@tex
Set @var{rop} to $@var{rop} + @var{op1} \times @var{op2}$.
@end tex
@end deftypefun
@deftypefun void mpz_mul_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
@cindex Bit shift left
@ifnottex
Set @var{rop} to @var{op1} times 2 raised to @var{op2}. This operation can
also be defined as a left shift, @var{op2} steps.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} \times 2^{op2}$. This operation can also be
defined as a left shift, @var{op2} steps.
@end tex
@end deftypefun
@deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op})
Set @var{rop} to @minus{}@var{op}.
@end deftypefun
@deftypefun void mpz_abs (mpz_t @var{rop}, mpz_t @var{op})
Set @var{rop} to the absolute value of @var{op}.
@end deftypefun
@need 2000
@node Integer Division, Integer Exponentiation, Integer Arithmetic, Integer Functions
@section Division Functions
@cindex Integer division functions
@cindex Division functions
Division is undefined if the divisor is zero, and passing a zero divisor to the
divide or modulo functions, as well passing a zero mod argument to the
@code{mpz_powm} and @code{mpz_powm_ui} functions, will make these functions
intentionally divide by zero. This lets the user handle arithmetic exceptions
in these functions in the same manner as other arithmetic exceptions.
There are three main groups of division functions:
@itemize @bullet
@item
Functions that truncate the quotient towards 0. The names of these functions
start with @code{mpz_tdiv}. The @samp{t} in the name is short for
@samp{truncate}.
@item
Functions that round the quotient towards
@ifnottex
@minus{}infinity).
@end ifnottex
@tex
$-\infty$
@end tex
The names of these routines start with @code{mpz_fdiv}. The @samp{f} in the
name is short for @samp{floor}.
@item
Functions that round the quotient towards
@ifnottex
+infinity.
@end ifnottex
@tex
$+\infty$
@end tex
The names of these routines start with @code{mpz_cdiv}. The @samp{c} in the
name is short for @samp{ceil}.
@end itemize
For each rounding mode, there are a couple of variants. Here @samp{q} means
that the quotient is computed, while @samp{r} means that the remainder is
computed. Functions that compute both the quotient and remainder have
@samp{qr} in the name.
@deftypefun void mpz_tdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_tdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d})
Set @var{q} to [@var{n}/@var{d}], truncated towards 0.
The function @code{mpz_tdiv_q_ui} returns the absolute value of the true
remainder.
@end deftypefun
@deftypefun void mpz_tdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_tdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{r} to (@var{n} - [@var{n}/@var{d}] * @var{d}), where the quotient is
truncated towards 0. Unless @var{r} becomes zero, it will get the same sign as
@var{n}.
@end ifnottex
@tex
Set @var{r} to $(@var{n} - [@var{n}/@var{d}] \times @var{d})$, where the
quotient is truncated towards 0. Unless @var{r} becomes zero, it will get the
same sign as @var{n}.
@end tex
The function @code{mpz_tdiv_r_ui} returns the absolute value of the remainder.
@end deftypefun
@deftypefun void mpz_tdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_tdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to (@var{n}
- [@var{n}/@var{d}] * @var{d}). Unless @var{r} becomes zero, it will get the
same sign as @var{n}. If @var{q} and @var{r} are the same variable, the
results are undefined.
@end ifnottex
@tex
Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to $(@var{n}
- [@var{n}/@var{d}] \times @var{d})$. Unless @var{r} becomes zero, it will get the
same sign as @var{n}. If @var{q} and @var{r} are the same variable, the
results are undefined.
@end tex
The function @code{mpz_tdiv_qr_ui} returns the absolute value of the remainder.
@end deftypefun
@deftypefun {unsigned long int} mpz_tdiv_ui (mpz_t @var{n}, unsigned long int @var{d})
Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its
absolute value is just returned.
@end deftypefun
@deftypefun void mpz_fdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_fdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to @var{n}/@var{d}, rounded towards @minus{}infinity.
@end ifnottex
@tex
Set @var{q} to $\lfloor@var{n}/@var{d}\rfloor$.
@end tex
The function @code{mpz_fdiv_q_ui} returns the remainder.
@end deftypefun
@deftypefun void mpz_fdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{r} to (@var{n} - @var{n}/@var{d} * @var{d}), where the quotient is
rounded towards @minus{}infinity. Unless @var{r} becomes zero, it will get the
same sign as @var{d}.
@end ifnottex
@tex
Set @var{r} to $(@var{n} - \lfloor@var{n}/@var{d}\rfloor \times @var{d})$.
Unless @var{r} becomes zero, it will get the same sign as @var{d}.
@end tex
The function @code{mpz_fdiv_r_ui} returns the remainder.
@end deftypefun
@deftypefun void mpz_fdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_fdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to @var{n}/@var{d}, rounded towards @minus{}infinity. Set @var{r}
to (@var{n} - @var{n}/@var{d} * @var{d}). Unless @var{r} becomes zero, it
will get the same sign as @var{d}. If @var{q} and @var{r} are the same
variable, the results are undefined.
@end ifnottex
@tex
Set @var{q} to $\lfloor@var{n}/@var{d}\rfloor$. Set @var{r} to $(@var{n} -
\lfloor@var{n}/@var{d}\rfloor \times @var{d})$. Unless @var{r} becomes zero,
it will get the same sign as @var{d}. If @var{q} and @var{r} are the same
variable, the results are undefined.
@end tex
The function @code{mpz_fdiv_qr_ui} returns the remainder.
@end deftypefun
@deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{n}, unsigned long int @var{d})
Like @code{mpz_fdiv_r_ui}, but the remainder is not stored anywhere; it is just
returned.
@end deftypefun
@deftypefun void mpz_cdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_cdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to @var{n}/@var{d}, rounded towards +infinity.
@end ifnottex
@tex
Set @var{q} to $\lceil@var{n}/@var{d}\rceil$.
@end tex
The function @code{mpz_cdiv_q_ui} returns the negated remainder.
@end deftypefun
@deftypefun void mpz_cdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{r} to (@var{n} - @var{n}/@var{d} * @var{d}), where the quotient is
rounded towards +infinity. Unless @var{r} becomes zero, it will get the
opposite sign as @var{d}.
@end ifnottex
@tex
Set @var{r} to $(@var{n} - \lceil@var{n}/@var{d}\rceil \times @var{d})$. Unless
@var{r} becomes zero, it will get the opposite sign as @var{d}.
@end tex
The function @code{mpz_cdiv_r_ui} returns the negated remainder.
@end deftypefun
@deftypefun void mpz_cdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_cdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to @var{n}/@var{d}, rounded towards +infinity. Set @var{r}
to (@var{n} - @var{n}/@var{d} * @var{d}). Unless @var{r} becomes zero, it
will get the opposite sign as @var{d}. If @var{q} and @var{r} are the same
variable, the results are undefined.
@end ifnottex
@tex
Set @var{q} to $\lceil@var{n}/@var{d}\rceil$. Set @var{r} to $(@var{n} -
\lceil@var{n}/@var{d}\rceil \times @var{d})$. Unless @var{r} becomes zero, it will
get the opposite sign as @var{d}. If @var{q} and @var{r} are the same
variable, the results are undefined.
@end tex
The function @code{mpz_cdiv_qr_ui} returns the negated remainder.
@end deftypefun
@deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{n}, unsigned long int @var{d})
Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its
negated value is just returned.
@end deftypefun
@deftypefun void mpz_mod (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d})
@deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
Set @var{r} to @var{n} @code{mod} @var{d}. The sign of the divisor is ignored;
the result is always non-negative.
The function @code{mpz_mod_ui} returns the remainder.
@end deftypefun
@deftypefun void mpz_divexact (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d})
@cindex Exact division functions
Set @var{q} to @var{n}/@var{d}. This function produces correct results only
when it is known in advance that @var{d} divides @var{n}.
Since mpz_divexact is much faster than any of the other routines that produce
the quotient (@pxref{References} Jebelean), it is the best choice for instances
in which exact division is known to occur, such as reducing a rational to
lowest terms.
@end deftypefun
@deftypefun void mpz_tdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d})
@cindex Bit shift right
@ifnottex
Set @var{q} to @var{n} divided by 2 raised to @var{d}. The quotient is truncated
towards 0.
@end ifnottex
@tex
Set @var{q} to $[{n}/2^{d}]$, truncated towards 0.
@end tex
@end deftypefun
@deftypefun void mpz_tdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards 0, and
put the remainder in @var{r}.
@end ifnottex
@tex
Set @var{r} to $n - [n / 2^{d}] \times 2^{d}$, where [ ] indicates rounding towards
0.
@end tex
Unless it is zero, @var{r} will have the same sign as @var{n}.
@end deftypefun
@deftypefun void mpz_fdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Set @var{q} to @var{n} divided by 2 raised to @var{d}, rounded towards
@minus{}infinity.
@end ifnottex
@tex
Set @var{q} to $\lfloor{n}/2^{d}\rfloor$.
@end tex
This operation can also be defined as arithmetic right shift @var{d} bit
positions.
@end deftypefun
@deftypefun void mpz_fdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d})
@ifnottex
Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards
@minus{}infinity, and put the remainder in @var{r}.
@end ifnottex
@tex
Set @var{r} to $n - \lfloor{n}/2^{d}\rfloor \times 2^{d}$.
@end tex
The sign of @var{r} will always be positive.
This operation can also be defined as masking of the @var{d} least significant
bits.
@end deftypefun
@need 2000
@node Integer Exponentiation, Integer Roots, Integer Division, Integer Functions
@section Exponentiation Functions
@cindex Integer exponentiation functions
@cindex Exponentiation functions
@deftypefun void mpz_powm (mpz_t @var{rop}, mpz_t @var{base}, mpz_t @var{exp}, mpz_t @var{mod})
@deftypefunx void mpz_powm_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}, mpz_t @var{mod})
@ifnottex
Set @var{rop} to (@var{base} raised to @var{exp}) @code{mod} @var{mod}. If
@var{exp} is negative, the result is undefined.
@end ifnottex
@tex
Set @var{rop} to $base^{exp} \bmod mod$. If
@var{exp} is negative, the result is undefined.
@end tex
@end deftypefun
@deftypefun void mpz_pow_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp})
@deftypefunx void mpz_ui_pow_ui (mpz_t @var{rop}, unsigned long int @var{base}, unsigned long int @var{exp})
@ifnottex
Set @var{rop} to @var{base} raised to @var{exp}. The case of 0^0 yields 1.
@end ifnottex
@tex
Set @var{rop} to $base^{exp}$. The case of $0^0$ yields 1.
@end tex
@end deftypefun
@need 2000
@node Integer Roots, Number Theoretic Functions, Integer Exponentiation, Integer Functions
@section Root Extraction Functions
@cindex Integer root functions
@cindex Root extraction functions
@deftypefun int mpz_root (mpz_t @var{rop}, mpz_t @var{op}, unsigned long int @var{n})
@ifnottex
Set @var{rop} to the truncated integer part of the @var{n}th root of @var{op}.
@end ifnottex
@tex
Set @var{rop} to $\lfloor\root n \of {op}\rfloor$, the truncated integer
part of the @var{n}th root of @var{op}.
@end tex
Return non-zero if the computation was exact, i.e., if @var{op} is
@var{rop} to the @var{n}th power.
@end deftypefun
@deftypefun void mpz_sqrt (mpz_t @var{rop}, mpz_t @var{op})
@ifnottex
Set @var{rop} to the truncated integer part of the square root of @var{op}.
@end ifnottex
@tex
Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer part of
the square root of @var{op}.
@end tex
@end deftypefun
@deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op})
@ifnottex
Set @var{rop1} to the truncated integer part of the square root of @var{op},
like @code{mpz_sqrt}. Set @var{rop2} to
@var{op}@minus{}@var{rop1}*@var{rop1},
@end ifnottex
@tex
Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}.
Set @var{rop2} to $(@var{op} - @var{rop1}^2)$,
@end tex
(i.e., zero if @var{op} is a perfect square).
If @var{rop1} and @var{rop2} are the same variable, the results are
undefined.
@end deftypefun
@deftypefun int mpz_perfect_power_p (mpz_t @var{op})
@ifnottex
Return non-zero if @var{op} is a perfect power, i.e., if there exist integers
@var{a} and @var{b}, with @var{b} > 1, such that @var{op} equals a raised to
b. Return zero otherwise.
@end ifnottex
@tex
Return non-zero if @var{op} is a perfect power, i.e., if there exist integers
$a$ and $b$, with $b>1$, such that $@var{op}=a^b$. Return zero otherwise.
@end tex
@end deftypefun
@deftypefun int mpz_perfect_square_p (mpz_t @var{op})
Return non-zero if @var{op} is a perfect square, i.e., if the square root of
@var{op} is an integer. Return zero otherwise.
@end deftypefun
@need 2000
@node Number Theoretic Functions, Integer Comparisons, Integer Roots, Integer Functions
@section Number Theoretic Functions
@cindex Number theoretic functions
@deftypefun int mpz_probab_prime_p (mpz_t @var{n}, int @var{reps})
@cindex Prime testing functions
If this function returns 0, @var{n} is definitely not prime. If it
returns 1, then @var{n} is `probably' prime. If it returns 2, then
@var{n} is surely prime. Reasonable values of reps vary from 5 to 10; a
higher value lowers the probability for a non-prime to pass as a
`probable' prime.
The function uses Miller-Rabin's probabilistic test.
@end deftypefun
@deftypefun int mpz_nextprime (mpz_t @var{rop}, mpz_t @var{op})
Set @var{rop} to the next prime greater than @var{op}.
This function uses a probabilistic algorithm to identify primes, but for for
practical purposes it's adequate, since the chance of a composite passing will
be extremely small.
@end deftypefun
@c mpz_prime_p not implemented as of gmp 3.0.
@c @deftypefun int mpz_prime_p (mpz_t @var{n})
@c Return non-zero if @var{n} is prime and zero if @var{n} is a non-prime.
@c This function is far slower than @code{mpz_probab_prime_p}, but then it
@c never returns non-zero for composite numbers.
@c (For practical purposes, using @code{mpz_probab_prime_p} is adequate.
@c The likelihood of a programming error or hardware malfunction is orders
@c of magnitudes greater than the likelihood for a composite to pass as a
@c prime, if the @var{reps} argument is in the suggested range.)
@c @end deftypefun
@deftypefun void mpz_gcd (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@cindex Greatest common divisor functions
Set @var{rop} to the greatest common divisor of @var{op1} and @var{op2}.
The result is always positive even if either of or both input operands
are negative.
@end deftypefun
@deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
Compute the greatest common divisor of @var{op1} and @var{op2}. If
@var{rop} is not @code{NULL}, store the result there.
If the result is small enough to fit in an @code{unsigned long int}, it is
returned. If the result does not fit, 0 is returned, and the result is equal
to the argument @var{op1}. Note that the result will always fit if @var{op2}
is non-zero.
@end deftypefun
@deftypefun void mpz_gcdext (mpz_t @var{g}, mpz_t @var{s}, mpz_t @var{t}, mpz_t @var{a}, mpz_t @var{b})
@cindex Extended GCD
Compute @var{g}, @var{s}, and @var{t}, such that @var{a}@var{s} +
@var{b}@var{t} = @var{g} = @code{gcd}(@var{a}, @var{b}). If @var{t} is
@code{NULL}, that argument is not computed.
@end deftypefun
@deftypefun void mpz_lcm (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@cindex Least common multiple functions
Set @var{rop} to the least common multiple of @var{op1} and @var{op2}.
@end deftypefun
@deftypefun int mpz_invert (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@cindex Modular inverse functions
Compute the inverse of @var{op1} modulo @var{op2} and put the result in
@var{rop}. Return non-zero if an inverse exists, zero otherwise. When the
function returns zero, @var{rop} is undefined.
@end deftypefun
@deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpz_legendre (mpz_t @var{op1}, mpz_t @var{op2})
@cindex Jabobi symbol functions
Compute the Jacobi and Legendre symbols, respectively. @var{op2} should be
odd and must be positive.
@end deftypefun
@deftypefun int mpz_si_kronecker (long @var{a}, mpz_t @var{b});
@deftypefunx int mpz_ui_kronecker (unsigned long @var{a}, mpz_t @var{b});
@deftypefunx int mpz_kronecker_si (mpz_t @var{a}, long @var{b});
@deftypefunx int mpz_kronecker_ui (mpz_t @var{a}, unsigned long @var{b});
@cindex Kronecker symbol functions
@tex
Calculate the value of the Kronecker/Jacobi symbol $\left(a \over b\right)$,
with the Kronecker extension $\left(a \over 2\right) = \left(2 \over a\right)$
when $a$ odd, or $\left(a \over 2\right) = 0$ when $a$ even.
@end tex
@ifnottex
Calculate the value of the Kronecker/Jacobi symbol (@var{a}/@var{b}), with the
Kronecker extension (a/2)=(2/a) when a odd, or (a/2)=0 when a even.
@end ifnottex
All values of @var{a} and @var{b} give a well-defined result. See Henri
Cohen, section 1.4.2, for more information (@pxref{References}). See also the
example program @file{demos/qcn.c} which uses @code{mpz_kronecker_ui}.
@end deftypefun
@deftypefun {unsigned long int} mpz_remove (mpz_t @var{rop}, mpz_t @var{op}, mpz_t @var{f})
Remove all occurrences of the factor @var{f} from @var{op} and store the
result in @var{rop}. Return the multiplicity of @var{f} in @var{op}.
@end deftypefun
@deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{op})
@cindex Factorial functions
Set @var{rop} to @var{op}!, the factorial of @var{op}.
@end deftypefun
@deftypefun void mpz_bin_ui (mpz_t @var{rop}, mpz_t @var{n}, unsigned long int @var{k})
@deftypefunx void mpz_bin_uiui (mpz_t @var{rop}, unsigned long int @var{n}, @w{unsigned long int @var{k}})
@cindex Binomial coefficient functions
Compute the binomial coefficient
@ifnottex
@var{n} over @var{k}
@end ifnottex
@tex
$\left({n}\atop{k}\right)$
@end tex
and store the result in @var{rop}. Negative values of @var{n} are supported
by @code{mpz_bin_ui}, using the identity
@ifnottex
bin(-n,k) = (-1)^k * bin(n+k-1,k)
@end ifnottex
@tex
$\left({-n}\atop{k}\right) = (-1)^k \left({n+k-1}\atop{k}\right)$
@end tex
(see Knuth volume 1 section 1.2.6 part G).
@end deftypefun
@deftypefun void mpz_fib_ui (mpz_t @var{rop}, unsigned long int @var{n})
@cindex Fibonacci sequence functions
Compute the @var{n}th Fibonacci number and store the result in @var{rop}.
@end deftypefun
@node Integer Comparisons, Integer Logic and Bit Fiddling, Number Theoretic Functions, Integer Functions
@comment node-name, next, previous, up
@section Comparison Functions
@cindex Integer comparison functions
@cindex Comparison functions
@deftypefun int mpz_cmp (mpz_t @var{op1}, mpz_t @var{op2})
@ifnottex
Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
@var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
@var{op2}.
@end ifnottex
@tex
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
@var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
< @var{op2}$.
@end tex
@end deftypefun
@deftypefn Macro int mpz_cmp_ui (mpz_t @var{op1}, unsigned long int @var{op2})
@deftypefnx Macro int mpz_cmp_si (mpz_t @var{op1}, signed long int @var{op2})
@ifnottex
Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
@var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
@var{op2}.
@end ifnottex
@tex
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
@var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
< @var{op2}$.
@end tex
These functions are actually implemented as macros. They evaluate their
arguments multiple times.
@end deftypefn
@deftypefun int mpz_cmpabs (mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpz_cmpabs_ui (mpz_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Compare the absolute values of @var{op1} and @var{op2}. Return a positive
value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative
value if @var{op1} < @var{op2}.
@end ifnottex
@tex
Compare the absolute values of @var{op1} and @var{op2}. Return a positive
value if $|@var{op1}| > |@var{op2}|$, zero if $|@var{op1}| = |@var{op2}|$, and a
negative value if $|@var{op1}| < |@var{op2}|$.
@end tex
@end deftypefun
@deftypefn Macro int mpz_sgn (mpz_t @var{op})
@ifnottex
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
@end ifnottex
@tex
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
@end tex
This function is actually implemented as a macro. It evaluates its
arguments multiple times.
@end deftypefn
@node Integer Logic and Bit Fiddling, I/O of Integers, Integer Comparisons, Integer Functions
@comment node-name, next, previous, up
@section Logical and Bit Manipulation Functions
@cindex Logical functions
@cindex Bit manipulation functions
@cindex Integer bit manipulation functions
These functions behave as if two's complement arithmetic were used (although
sign-magnitude is used by the actual implementation).
@deftypefun void mpz_and (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
Set @var{rop} to @var{op1} logical-and @var{op2}.
@end deftypefun
@deftypefun void mpz_ior (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
Set @var{rop} to @var{op1} inclusive-or @var{op2}.
@end deftypefun
@deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
Set @var{rop} to @var{op1} exclusive-or @var{op2}.
@end deftypefun
@deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op})
Set @var{rop} to the one's complement of @var{op}.
@end deftypefun
@deftypefun {unsigned long int} mpz_popcount (mpz_t @var{op})
For non-negative numbers, return the population count of @var{op}. For
negative numbers, return the largest possible value (@var{MAX_ULONG}).
@end deftypefun
@deftypefun {unsigned long int} mpz_hamdist (mpz_t @var{op1}, mpz_t @var{op2})
If @var{op1} and @var{op2} are both non-negative, return the hamming distance
between the two operands. Otherwise, return the largest possible value
(@var{MAX_ULONG}).
It is possible to extend this function to return a useful value when the
operands are both negative, but the current implementation returns
@var{MAX_ULONG} in this case. @strong{Do not depend on this behavior, since
it will change in a future release.}
@end deftypefun
@deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit})
Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
bits, until the first clear bit is found. Return the index of the found bit.
@end deftypefun
@deftypefun {unsigned long int} mpz_scan1 (mpz_t @var{op}, unsigned long int @var{starting_bit})
Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
bits, until the first set bit is found. Return the index of the found bit.
@end deftypefun
@deftypefun void mpz_setbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
Set bit @var{bit_index} in @var{rop}.
@end deftypefun
@deftypefun void mpz_clrbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
Clear bit @var{bit_index} in @var{rop}.
@end deftypefun
@deftypefun int mpz_tstbit (mpz_t @var{op}, unsigned long int @var{bit_index})
Check bit @var{bit_index} in @var{op} and return 0 or 1 accordingly.
@end deftypefun
@node I/O of Integers, Integer Random Numbers, Integer Logic and Bit Fiddling, Integer Functions
@comment node-name, next, previous, up
@section Input and Output Functions
@cindex Integer input and output functions
@cindex Input functions
@cindex Output functions
@cindex I/O functions
Functions that perform input from a stdio stream, and functions that output to
a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to any of
these functions will make them read from @code{stdin} and write to
@code{stdout}, respectively.
When using any of these functions, it is a good idea to include @file{stdio.h}
before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
for these functions.
@deftypefun size_t mpz_out_str (FILE *@var{stream}, int @var{base}, mpz_t @var{op})
Output @var{op} on stdio stream @var{stream}, as a string of digits in base
@var{base}. The base may vary from 2 to 36.
Return the number of bytes written, or if an error occurred, return 0.
@end deftypefun
@deftypefun size_t mpz_inp_str (mpz_t @var{rop}, FILE *@var{stream}, int @var{base})
Input a possibly white-space preceded string in base @var{base} from stdio
stream @var{stream}, and put the read integer in @var{rop}. The base may vary
from 2 to 36. If @var{base} is 0, the actual base is determined from the
leading characters: if the first two characters are `0x' or `0X', hexadecimal
is assumed, otherwise if the first character is `0', octal is assumed,
otherwise decimal is assumed.
Return the number of bytes read, or if an error occurred, return 0.
@end deftypefun
@deftypefun size_t mpz_out_raw (FILE *@var{stream}, mpz_t @var{op})
Output @var{op} on stdio stream @var{stream}, in raw binary format. The
integer is written in a portable format, with 4 bytes of size information, and
that many bytes of limbs. Both the size and the limbs are written in
decreasing significance order (i.e., in big-endian).
The output can be read with @code{mpz_inp_raw}.
Return the number of bytes written, or if an error occurred, return 0.
The output of this can not be read by @code{mpz_inp_raw} from GMP 1, because
of changes necessary for compatibility between 32-bit and 64-bit machines.
@end deftypefun
@deftypefun size_t mpz_inp_raw (mpz_t @var{rop}, FILE *@var{stream})
Input from stdio stream @var{stream} in the format written by
@code{mpz_out_raw}, and put the result in @var{rop}. Return the number of
bytes read, or if an error occurred, return 0.
This routine can read the output from @code{mpz_out_raw} also from GMP 1, in
spite of changes necessary for compatibility between 32-bit and 64-bit
machines.
@end deftypefun
@need 2000
@node Integer Random Numbers, Miscellaneous Integer Functions, I/O of Integers, Integer Functions
@comment node-name, next, previous, up
@section Random Number Functions
@cindex Integer random number functions
@cindex Random number functions
The random number functions of GMP come in two groups; older function
that rely on a global state, and newer functions that accept a state
parameter that is read and modified. Please see the @ref{Random Number
Functions} for more information on how to use and not to use random
number functions.
@deftypefun void mpz_urandomb (mpz_t @var{rop}, gmp_randstate_t @var{state},
unsigned long int @var{n})
Generate a uniform random integer in the range
@ifnottex
0 to 2^@var{n} @minus{} 1,
@end ifnottex
@tex
0 to $2^n-1$,
@end tex
inclusive.
The variable @var{state} must be initialized by calling one of the
@code{gmp_randinit} functions (@ref{Random State Initialization}) before
invoking this function.
@end deftypefun
@deftypefun void mpz_urandomm (mpz_t @var{rop}, gmp_randstate_t @var{state},
mpz_t @var{n})
Generate a uniform random integer in the range 0 to
@ifnottex
@var{n} @minus{} 1, inclusive.
@end ifnottex
@tex
$n-1$, inclusive.
@end tex
The variable @var{state} must be initialized by calling one of the
@code{gmp_randinit} functions (@ref{Random State Initialization})
before invoking this function.
@end deftypefun
@deftypefun void mpz_rrandomb (mpz_t @var{rop}, gmp_randstate_t @var{state}, unsigned long int @var{n})
Generate a random integer with long strings of zeros and ones in the
binary representation. Useful for testing functions and algorithms,
since this kind of random numbers have proven to be more likely to
trigger corner-case bugs. The random number will be in the range
@ifnottex
0 to 2^@var{n} @minus{} 1,
@end ifnottex
@tex
0 to $2^n-1$,
@end tex
inclusive.
The variable @var{state} must be initialized by calling one of the
@code{gmp_randinit} functions (@ref{Random State Initialization})
before invoking this function.
@end deftypefun
@deftypefun void mpz_random (mpz_t @var{rop}, mp_size_t @var{max_size})
Generate a random integer of at most @var{max_size} limbs. The generated
random number doesn't satisfy any particular requirements of randomness.
Negative random numbers are generated when @var{max_size} is negative.
This function is obsolete. Use @code{mpz_urandomb} or
@code{mpz_urandomm} instead.
@end deftypefun
@deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size})
Generate a random integer of at most @var{max_size} limbs, with long strings
of zeros and ones in the binary representation. Useful for testing functions
and algorithms, since this kind of random numbers have proven to be more
likely to trigger corner-case bugs. Negative random numbers are generated
when @var{max_size} is negative.
This function is obsolete. Use @code{mpz_rrandomb} instead.
@end deftypefun
@need 2000
@node Miscellaneous Integer Functions, , Integer Random Numbers, Integer Functions
@comment node-name, next, previous, up
@section Miscellaneous Functions
@cindex Miscellaneous integer functions
@cindex Integer miscellaneous functions
@deftypefun int mpz_fits_ulong_p (mpz_t @var{op})
@deftypefunx int mpz_fits_slong_p (mpz_t @var{op})
@deftypefunx int mpz_fits_uint_p (mpz_t @var{op})
@deftypefunx int mpz_fits_sint_p (mpz_t @var{op})
@deftypefunx int mpz_fits_ushort_p (mpz_t @var{op})
@deftypefunx int mpz_fits_sshort_p (mpz_t @var{op})
Return non-zero iff the value of @var{op} fits in an @code{unsigned long int},
@code{signed long int}, @code{unsigned int}, @code{signed int}, @code{unsigned
short int}, or @code{signed short int}, respectively. Otherwise, return zero.
@end deftypefun
@deftypefn Macro int mpz_odd_p (mpz_t @var{op})
@deftypefnx Macro int mpz_even_p (mpz_t @var{op})
Determine whether @var{op} is odd or even, respectively. Return non-zero if
yes, zero if no. These macros evaluate their arguments more than once.
@end deftypefn
@deftypefun size_t mpz_size (mpz_t @var{op})
Return the size of @var{op} measured in number of limbs. If @var{op} is zero,
the returned value will be zero.
@c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.)
@end deftypefun
@deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base})
Return the size of @var{op} measured in number of digits in base @var{base}.
The base may vary from 2 to 36. The returned value will be exact or 1 too
big. If @var{base} is a power of 2, the returned value will always be exact.
This function is useful in order to allocate the right amount of space before
converting @var{op} to a string. The right amount of allocation is normally
two more than the value returned by @code{mpz_sizeinbase} (one extra for a
minus sign and one for the terminating '\0').
@end deftypefun
@node Rational Number Functions, Floating-point Functions, Integer Functions, Top
@comment node-name, next, previous, up
@chapter Rational Number Functions
@cindex Rational number functions
This chapter describes the GMP functions for performing arithmetic on rational
numbers. These functions start with the prefix @code{mpq_}.
Rational numbers are stored in objects of type @code{mpq_t}.
All rational arithmetic functions assume operands have a canonical form, and
canonicalize their result. The canonical from means that the denominator and
the numerator have no common factors, and that the denominator is positive.
Zero has the unique representation 0/1.
Pure assignment functions do not canonicalize the assigned variable. It is
the responsibility of the user to canonicalize the assigned variable before
any arithmetic operations are performed on that variable. @strong{Note that
this is an incompatible change from version 1 of the library.}
@deftypefun void mpq_canonicalize (mpq_t @var{op})
Remove any factors that are common to the numerator and denominator of
@var{op}, and make the denominator positive.
@end deftypefun
@menu
* Initializing Rationals::
* Rational Arithmetic::
* Comparing Rationals::
* Applying Integer Functions::
* I/O of Rationals::
* Miscellaneous Rational Functions::
@end menu
@node Initializing Rationals, Rational Arithmetic, Rational Number Functions, Rational Number Functions
@comment node-name, next, previous, up
@section Initialization and Assignment Functions
@cindex Initialization and assignment functions
@cindex Rational init and assign
@deftypefun void mpq_init (mpq_t @var{dest_rational})
Initialize @var{dest_rational} and set it to 0/1. Each variable should
normally only be initialized once, or at least cleared out (using the function
@code{mpq_clear}) between each initialization.
@end deftypefun
@deftypefun void mpq_clear (mpq_t @var{rational_number})
Free the space occupied by @var{rational_number}. Make sure to call this
function for all @code{mpq_t} variables when you are done with them.
@end deftypefun
@deftypefun void mpq_set (mpq_t @var{rop}, mpq_t @var{op})
@deftypefunx void mpq_set_z (mpq_t @var{rop}, mpz_t @var{op})
Assign @var{rop} from @var{op}.
@end deftypefun
@deftypefun void mpq_set_ui (mpq_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2})
@deftypefunx void mpq_set_si (mpq_t @var{rop}, signed long int @var{op1}, unsigned long int @var{op2})
Set the value of @var{rop} to @var{op1}/@var{op2}. Note that if @var{op1} and
@var{op2} have common factors, @var{rop} has to be passed to
@code{mpq_canonicalize} before any operations are performed on @var{rop}.
@end deftypefun
@deftypefun void mpq_swap (mpq_t @var{rop1}, mpq_t @var{rop2})
Swap the values @var{rop1} and @var{rop2} efficiently.
@end deftypefun
@node Rational Arithmetic, Comparing Rationals, Initializing Rationals, Rational Number Functions
@comment node-name, next, previous, up
@section Arithmetic Functions
@cindex Rational arithmetic functions
@cindex Arithmetic functions
@deftypefun void mpq_add (mpq_t @var{sum}, mpq_t @var{addend1}, mpq_t @var{addend2})
Set @var{sum} to @var{addend1} + @var{addend2}.
@end deftypefun
@deftypefun void mpq_sub (mpq_t @var{difference}, mpq_t @var{minuend}, mpq_t @var{subtrahend})
Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}.
@end deftypefun
@deftypefun void mpq_mul (mpq_t @var{product}, mpq_t @var{multiplier}, mpq_t @var{multiplicand})
@ifnottex
Set @var{product} to @var{multiplier} times @var{multiplicand}.
@end ifnottex
@tex
Set @var{product} to $@var{multiplier} \times @var{multiplicand}$.
@end tex
@end deftypefun
@deftypefun void mpq_div (mpq_t @var{quotient}, mpq_t @var{dividend}, mpq_t @var{divisor})
@cindex Division functions
Set @var{quotient} to @var{dividend}/@var{divisor}.
@end deftypefun
@deftypefun void mpq_neg (mpq_t @var{negated_operand}, mpq_t @var{operand})
Set @var{negated_operand} to @minus{}@var{operand}.
@end deftypefun
@deftypefun void mpq_inv (mpq_t @var{inverted_number}, mpq_t @var{number})
Set @var{inverted_number} to 1/@var{number}. If the new denominator is
zero, this routine will divide by zero.
@end deftypefun
@node Comparing Rationals, Applying Integer Functions, Rational Arithmetic, Rational Number Functions
@comment node-name, next, previous, up
@section Comparison Functions
@cindex Rational comparison functions
@cindex Comparison functions
@deftypefun int mpq_cmp (mpq_t @var{op1}, mpq_t @var{op2})
@ifnottex
Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
@var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
@var{op2}.
@end ifnottex
@tex
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
@var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
< @var{op2}$.
@end tex
To determine if two rationals are equal, @code{mpq_equal} is faster than
@code{mpq_cmp}.
@end deftypefun
@deftypefn Macro int mpq_cmp_ui (mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2})
@ifnottex
Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if
@var{op1} > @var{num2}/@var{den2}, zero if @var{op1} = @var{num2}/@var{den2},
and a negative value if @var{op1} < @var{num2}/@var{den2}.
@end ifnottex
@tex
Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if
$@var{op1} > @var{num2}/@var{den2}$, zero if $@var{op1} =
@var{num2}/@var{den2}$, and a negative value if $@var{op1} <
@var{num2}/@var{den2}$.
@end tex
This routine allows that @var{num2} and @var{den2} have common factors.
This function is actually implemented as a macro. It evaluates its
arguments multiple times.
@end deftypefn
@deftypefn Macro int mpq_sgn (mpq_t @var{op})
@ifnottex
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
@end ifnottex
@tex
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
@end tex
This function is actually implemented as a macro. It evaluates its
arguments multiple times.
@end deftypefn
@deftypefun int mpq_equal (mpq_t @var{op1}, mpq_t @var{op2})
Return non-zero if @var{op1} and @var{op2} are equal, zero if they are
non-equal. Although @code{mpq_cmp} can be used for the same purpose, this
function is much faster.
@end deftypefun
@node Applying Integer Functions, I/O of Rationals, Comparing Rationals, Rational Number Functions
@comment node-name, next, previous, up
@section Applying Integer Functions to Rationals
@cindex Rational numerator and denominator
@cindex Numerator and denominator
The set of @code{mpq} functions is quite small. In particular, there are few
functions for either input or output. But there are two macros that allow us
to apply any @code{mpz} function on the numerator or denominator of a rational
number. If these macros are used to assign to the rational number,
@code{mpq_canonicalize} normally need to be called afterwards.
@deftypefn Macro mpz_t mpq_numref (mpq_t @var{op})
@deftypefnx Macro mpz_t mpq_denref (mpq_t @var{op})
Return a reference to the numerator and denominator of @var{op}, respectively.
The @code{mpz} functions can be used on the result of these macros.
@end deftypefn
@need 2000
@node I/O of Rationals, Miscellaneous Rational Functions, Applying Integer Functions, Rational Number Functions
@comment node-name, next, previous, up
@section Input and Output Functions
@cindex Rational input and output functions
@cindex Input functions
@cindex Output functions
@cindex I/O functions
Functions that perform input from a stdio stream, and functions that output to
a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to
any of these functions will make them read from @code{stdin} and write to
@code{stdout}, respectively.
When using any of these functions, it is a good idea to include @file{stdio.h}
before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
for these functions.
@deftypefun size_t mpq_out_str (FILE *@var{stream}, int @var{base}, mpq_t @var{op})
Output @var{op} on stdio stream @var{stream}, as a string of digits in base
@var{base}. The base may vary from 2 to 36. Output is in the form
@samp{num/den} or if the denominator is 1 then just @samp{num}.
Return the number of bytes written, or if an error occurred, return 0.
@end deftypefun
@need 2000
@node Miscellaneous Rational Functions, , I/O of Rationals, Rational Number Functions
@comment node-name, next, previous, up
@section Miscellaneous Functions
@cindex Rational miscellaneous functions
@cindex Miscellaneous rational functions
@deftypefun double mpq_get_d (mpq_t @var{op})
Convert @var{op} to a double.
@end deftypefun
@deftypefun double mpq_set_d (mpq_t @var{rop}, double @var{d})
Set @var{rop} to the value of d, without rounding.
@end deftypefun
These functions assign between either the numerator or denominator of a
rational, and an integer. Instead of using these functions, it is preferable
to use the more general mechanisms @code{mpq_numref} and @code{mpq_denref},
together with @code{mpz_set}.
@deftypefun void mpq_set_num (mpq_t @var{rational}, mpz_t @var{numerator})
Copy @var{numerator} to the numerator of @var{rational}. When this risks to
make the numerator and denominator of @var{rational} have common factors, you
have to pass @var{rational} to @code{mpq_canonicalize} before any operations
are performed on @var{rational}.
This function is equivalent to
@code{mpz_set (mpq_numref (@var{rational}), @var{numerator})}.
@end deftypefun
@deftypefun void mpq_set_den (mpq_t @var{rational}, mpz_t @var{denominator})
Copy @var{denominator} to the denominator of @var{rational}. When this risks
to make the numerator and denominator of @var{rational} have common factors,
or if the denominator might be negative, you have to pass @var{rational} to
@code{mpq_canonicalize} before any operations are performed on @var{rational}.
@strong{In version 1 of the library, negative denominators were handled by
copying the sign to the numerator. That is no longer done.}
This function is equivalent to
@code{mpz_set (mpq_denref (@var{rational}), @var{denominators})}.
@end deftypefun
@deftypefun void mpq_get_num (mpz_t @var{numerator}, mpq_t @var{rational})
Copy the numerator of @var{rational} to the integer @var{numerator}, to
prepare for integer operations on the numerator.
This function is equivalent to
@code{mpz_set (@var{numerator}, mpq_numref (@var{rational}))}.
@end deftypefun
@deftypefun void mpq_get_den (mpz_t @var{denominator}, mpq_t @var{rational})
Copy the denominator of @var{rational} to the integer @var{denominator}, to
prepare for integer operations on the denominator.
This function is equivalent to
@code{mpz_set (@var{denominator}, mpq_denref (@var{rational}))}.
@end deftypefun
@node Floating-point Functions, Low-level Functions, Rational Number Functions, Top
@comment node-name, next, previous, up
@chapter Floating-point Functions
@cindex Floating-point functions
@cindex Float functions
This chapter describes the GMP functions for performing floating point
arithmetic. These functions start with the prefix @code{mpf_}.
GMP floating point numbers are stored in objects of type @code{mpf_t}.
The GMP floating-point functions have an interface that is similar to the GMP
integer functions. The function prefix for floating-point operations is
@code{mpf_}.
There is one significant characteristic of floating-point numbers that has
motivated a difference between this function class and other GMP function
classes: the inherent inexactness of floating point arithmetic. The user has
to specify the precision of each variable. A computation that assigns a
variable will take place with the precision of the assigned variable; the
precision of variables used as input is ignored.
@cindex User-defined precision
@cindex Precision of floats
The precision of a calculation is defined as follows: Compute the requested
operation exactly (with ``infinite precision''), and truncate the result to
the destination variable precision. Even if the user has asked for a very
high precision, GMP will not calculate with superfluous digits. For example,
if two low-precision numbers of nearly equal magnitude are added, the
precision of the result will be limited to what is required to represent the
result accurately.
The GMP floating-point functions are @emph{not} intended as a smooth extension
to the IEEE P754 arithmetic. Specifically, the results obtained on one
computer often differs from the results obtained on a computer with a
different word size.
@menu
* Initializing Floats::
* Assigning Floats::
* Simultaneous Float Init & Assign::
* Converting Floats::
* Float Arithmetic::
* Float Comparison::
* I/O of Floats::
* Miscellaneous Float Functions::
@end menu
@node Initializing Floats, Assigning Floats, Floating-point Functions, Floating-point Functions
@comment node-name, next, previous, up
@section Initialization Functions
@cindex Float initialization functions
@cindex Initialization functions
@deftypefun void mpf_set_default_prec (unsigned long int @var{prec})
Set the default precision to be @strong{at least} @var{prec} bits. All
subsequent calls to @code{mpf_init} will use this precision, but previously
initialized variables are unaffected.
@end deftypefun
An @code{mpf_t} object must be initialized before storing the first value in
it. The functions @code{mpf_init} and @code{mpf_init2} are used for that
purpose.
@deftypefun void mpf_init (mpf_t @var{x})
Initialize @var{x} to 0. Normally, a variable should be initialized once only
or at least be cleared, using @code{mpf_clear}, between initializations. The
precision of @var{x} is undefined unless a default precision has already been
established by a call to @code{mpf_set_default_prec}.
@end deftypefun
@deftypefun void mpf_init2 (mpf_t @var{x}, unsigned long int @var{prec})
Initialize @var{x} to 0 and set its precision to be @strong{at least}
@var{prec} bits. Normally, a variable should be initialized once only or at
least be cleared, using @code{mpf_clear}, between initializations.
@end deftypefun
@deftypefun void mpf_clear (mpf_t @var{x})
Free the space occupied by @var{x}. Make sure to call this function for all
@code{mpf_t} variables when you are done with them.
@end deftypefun
@need 2000
Here is an example on how to initialize floating-point variables:
@example
@{
mpf_t x, y;
mpf_init (x); /* use default precision */
mpf_init2 (y, 256); /* precision @emph{at least} 256 bits */
@dots{}
/* Unless the program is about to exit, do ... */
mpf_clear (x);
mpf_clear (y);
@}
@end example
The following three functions are useful for changing the precision during a
calculation. A typical use would be for adjusting the precision gradually in
iterative algorithms like Newton-Raphson, making the computation precision
closely match the actual accurate part of the numbers.
@deftypefun void mpf_set_prec (mpf_t @var{rop}, unsigned long int @var{prec})
Set the precision of @var{rop} to be @strong{at least} @var{prec} bits.
Since changing the precision involves calls to @code{realloc}, this routine
should not be called in a tight loop.
@end deftypefun
@deftypefun {unsigned long int} mpf_get_prec (mpf_t @var{op})
Return the precision actually used for assignments of @var{op}.
@end deftypefun
@deftypefun void mpf_set_prec_raw (mpf_t @var{rop}, unsigned long int @var{prec})
Set the precision of @var{rop} to be @strong{at least} @var{prec} bits. This
is a low-level function that does not change the allocation. The @var{prec}
argument must not be larger that the precision previously returned by
@code{mpf_get_prec}. It is crucial that the precision of @var{rop} is
ultimately reset to exactly the value returned by @code{mpf_get_prec} before
the first call to @code{mpf_set_prec_raw}.
@end deftypefun
@need 2000
@node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions
@comment node-name, next, previous, up
@section Assignment Functions
@cindex Float assignment functions
@cindex Assignment functions
These functions assign new values to already initialized floats
(@pxref{Initializing Floats}).
@deftypefun void mpf_set (mpf_t @var{rop}, mpf_t @var{op})
@deftypefunx void mpf_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
@deftypefunx void mpf_set_si (mpf_t @var{rop}, signed long int @var{op})
@deftypefunx void mpf_set_d (mpf_t @var{rop}, double @var{op})
@deftypefunx void mpf_set_z (mpf_t @var{rop}, mpz_t @var{op})
@deftypefunx void mpf_set_q (mpf_t @var{rop}, mpq_t @var{op})
Set the value of @var{rop} from @var{op}.
@end deftypefun
@deftypefun int mpf_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
Set the value of @var{rop} from the string in @var{str}. The string is of the
form @samp{M@@N} or, if the base is 10 or less, alternatively @samp{MeN}.
@samp{M} is the mantissa and @samp{N} is the exponent. The mantissa is always
in the specified base. The exponent is either in the specified base or, if
@var{base} is negative, in decimal.
The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
@minus{}2. Negative values are used to specify that the exponent is in
decimal.
Unlike the corresponding @code{mpz} function, the base will not be determined
from the leading characters of the string if @var{base} is 0. This is so that
numbers like @samp{0.23} are not interpreted as octal.
White space is allowed in the string, and is simply ignored. [This is not
really true; white-space is ignored in the beginning of the string and within
the mantissa, but not in other places, such as after a minus sign or in the
exponent. We are considering changing the definition of this function, making
it fail when there is any white-space in the input, since that makes a lot of
sense. Please tell us your opinion about this change. Do you really want it
to accept "3 14" as meaning 314 as it does now?]
This function returns 0 if the entire string up to the '\0' is a valid number
in base @var{base}. Otherwise it returns @minus{}1.
@end deftypefun
@deftypefun void mpf_swap (mpf_t @var{rop1}, mpf_t @var{rop2})
Swap the values @var{rop1} and @var{rop2} efficiently.
@end deftypefun
@node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions
@comment node-name, next, previous, up
@section Combined Initialization and Assignment Functions
@cindex Initialization and assignment functions
@cindex Float init and assign functions
For convenience, GMP provides a parallel series of initialize-and-set functions
which initialize the output and then store the value there. These functions'
names have the form @code{mpf_init_set@dots{}}
Once the float has been initialized by any of the @code{mpf_init_set@dots{}}
functions, it can be used as the source or destination operand for the ordinary
float functions. Don't use an initialize-and-set function on a variable
already initialized!
@deftypefun void mpf_init_set (mpf_t @var{rop}, mpf_t @var{op})
@deftypefunx void mpf_init_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
@deftypefunx void mpf_init_set_si (mpf_t @var{rop}, signed long int @var{op})
@deftypefunx void mpf_init_set_d (mpf_t @var{rop}, double @var{op})
Initialize @var{rop} and set its value from @var{op}.
The precision of @var{rop} will be taken from the active default precision, as
set by @code{mpf_set_default_prec}.
@end deftypefun
@deftypefun int mpf_init_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
Initialize @var{rop} and set its value from the string in @var{str}. See
@code{mpf_set_str} above for details on the assignment operation.
Note that @var{rop} is initialized even if an error occurs. (I.e., you have to
call @code{mpf_clear} for it.)
The precision of @var{rop} will be taken from the active default precision, as
set by @code{mpf_set_default_prec}.
@end deftypefun
@node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions
@comment node-name, next, previous, up
@section Conversion Functions
@cindex Float conversion functions
@cindex Conversion functions
@deftypefun double mpf_get_d (mpf_t @var{op})
Convert @var{op} to a double.
@end deftypefun
@deftypefun {char *} mpf_get_str (char *@var{str}, mp_exp_t *@var{expptr}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
Convert @var{op} to a string of digits in base @var{base}. The base may vary
from 2 to 36. Generate at most @var{n_digits} significant digits, or if
@var{n_digits} is 0, the maximum number of digits accurately representable by
@var{op}.
If @var{str} is @code{NULL}, space for the mantissa is allocated using the default
allocation function.
If @var{str} is not @code{NULL}, it should point to a block of storage enough large
for the mantissa, i.e., @var{n_digits} + 2. The two extra bytes are for a
possible minus sign, and for the terminating null character.
The exponent is written through the pointer @var{expptr}.
If @var{n_digits} is 0, the maximum number of digits meaningfully achievable
from the precision of @var{op} will be generated. Note that the space
requirements for @var{str} in this case will be impossible for the user to
predetermine. Therefore, you need to pass @code{NULL} for the string argument
whenever @var{n_digits} is 0.
The generated string is a fraction, with an implicit radix point immediately
to the left of the first digit. For example, the number 3.1416 would be
returned as "31416" in the string and 1 written at @var{expptr}.
A pointer to the result string is returned. This pointer will will either
equal @var{str}, or if that is @code{NULL}, will point to the allocated storage.
@end deftypefun
@node Float Arithmetic, Float Comparison, Converting Floats, Floating-point Functions
@comment node-name, next, previous, up
@section Arithmetic Functions
@cindex Float arithmetic functions
@cindex Arithmetic functions
@deftypefun void mpf_add (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_add_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} + @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} + @var{op2}$.
@end tex
@end deftypefun
@deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_ui_sub (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_sub_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
Set @var{rop} to @var{op1} @minus{} @var{op2}.
@end deftypefun
@deftypefun void mpf_mul (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_mul_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} times @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} \times @var{op2}$.
@end tex
@end deftypefun
Division is undefined if the divisor is zero, and passing a zero divisor to
the divide functions will make these functions intentionally divide by zero.
This lets the user handle arithmetic exceptions in these functions in the same
manner as other arithmetic exceptions.
@deftypefun void mpf_div (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_ui_div (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
@deftypefunx void mpf_div_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@cindex Division functions
Set @var{rop} to @var{op1}/@var{op2}.
@end deftypefun
@deftypefun void mpf_sqrt (mpf_t @var{rop}, mpf_t @var{op})
@deftypefunx void mpf_sqrt_ui (mpf_t @var{rop}, unsigned long int @var{op})
@cindex Root extraction functions
@ifnottex
Set @var{rop} to the square root of @var{op}.
@end ifnottex
@tex
Set @var{rop} to $\sqrt{@var{op}}$.
@end tex
@end deftypefun
@deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@cindex Exponentiation functions
@ifnottex
Set @var{rop} to @var{op1} raised to the power @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1}^{op2}$.
@end tex
@end deftypefun
@deftypefun void mpf_neg (mpf_t @var{rop}, mpf_t @var{op})
Set @var{rop} to @minus{}@var{op}.
@end deftypefun
@deftypefun void mpf_abs (mpf_t @var{rop}, mpf_t @var{op})
Set @var{rop} to the absolute value of @var{op}.
@end deftypefun
@deftypefun void mpf_mul_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} times 2 raised to @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1} \times 2^{op2}$.
@end tex
@end deftypefun
@deftypefun void mpf_div_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
@ifnottex
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}.
@end ifnottex
@tex
Set @var{rop} to $@var{op1}/2^{op2}$.
@end tex
@end deftypefun
@node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions
@comment node-name, next, previous, up
@section Comparison Functions
@cindex Float comparison functions
@cindex Comparison functions
@deftypefun int mpf_cmp (mpf_t @var{op1}, mpf_t @var{op2})
@deftypefunx int mpf_cmp_ui (mpf_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpf_cmp_si (mpf_t @var{op1}, signed long int @var{op2})
@ifnottex
Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
@var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
@var{op2}.
@end ifnottex
@tex
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
@var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
< @var{op2}$.
@end tex
@end deftypefun
@deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3)
Return non-zero if the first @var{op3} bits of @var{op1} and @var{op2} are
equal, zero otherwise. I.e., test of @var{op1} and @var{op2} are
approximately equal.
@end deftypefun
@deftypefun void mpf_reldiff (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
Compute the relative difference between @var{op1} and @var{op2} and store the
result in @var{rop}.
@end deftypefun
@deftypefn Macro int mpf_sgn (mpf_t @var{op})
@ifnottex
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
@end ifnottex
@tex
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
@end tex
This function is actually implemented as a macro. It evaluates its
arguments multiple times.
@end deftypefn
@node I/O of Floats, Miscellaneous Float Functions, Float Comparison, Floating-point Functions
@comment node-name, next, previous, up
@section Input and Output Functions
@cindex Float input and output functions
@cindex Input functions
@cindex Output functions
@cindex I/O functions
Functions that perform input from a stdio stream, and functions that output to
a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to any of
these functions will make them read from @code{stdin} and write to
@code{stdout}, respectively.
When using any of these functions, it is a good idea to include @file{stdio.h}
before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
for these functions.
@deftypefun size_t mpf_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
Output @var{op} on stdio stream @var{stream}, as a string of digits in
base @var{base}. The base may vary from 2 to 36. Print at most
@var{n_digits} significant digits, or if @var{n_digits} is 0, the maximum
number of digits accurately representable by @var{op}.
In addition to the significant digits, a leading @samp{0.} and a
trailing exponent, in the form @samp{eNNN}, are printed. If @var{base}
is greater than 10, @samp{@@} will be used instead of @samp{e} as
exponent delimiter.
Return the number of bytes written, or if an error occurred, return 0.
@end deftypefun
@deftypefun size_t mpf_inp_str (mpf_t @var{rop}, FILE *@var{stream}, int @var{base})
Input a string in base @var{base} from stdio stream @var{stream}, and put the
read float in @var{rop}. The string is of the form @samp{M@@N} or, if the
base is 10 or less, alternatively @samp{MeN}. @samp{M} is the mantissa and
@samp{N} is the exponent. The mantissa is always in the specified base. The
exponent is either in the specified base or, if @var{base} is negative, in
decimal.
The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
@minus{}2. Negative values are used to specify that the exponent is in
decimal.
Unlike the corresponding @code{mpz} function, the base will not be determined
from the leading characters of the string if @var{base} is 0. This is so that
numbers like @samp{0.23} are not interpreted as octal.
Return the number of bytes read, or if an error occurred, return 0.
@end deftypefun
@c @deftypefun void mpf_out_raw (FILE *@var{stream}, mpf_t @var{float})
@c Output @var{float} on stdio stream @var{stream}, in raw binary
@c format. The float is written in a portable format, with 4 bytes of
@c size information, and that many bytes of limbs. Both the size and the
@c limbs are written in decreasing significance order.
@c @end deftypefun
@c @deftypefun void mpf_inp_raw (mpf_t @var{float}, FILE *@var{stream})
@c Input from stdio stream @var{stream} in the format written by
@c @code{mpf_out_raw}, and put the result in @var{float}.
@c @end deftypefun
@node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions
@comment node-name, next, previous, up
@section Miscellaneous Functions
@cindex Miscellaneous float functions
@cindex Float miscellaneous functions
@deftypefun void mpf_ceil (mpf_t @var{rop}, mpf_t @var{op})
@deftypefunx void mpf_floor (mpf_t @var{rop}, mpf_t @var{op})
@deftypefunx void mpf_trunc (mpf_t @var{rop}, mpf_t @var{op})
Set @var{rop} to @var{op} rounded to an integer. @code{mpf_ceil} rounds to
the next higher integer, @code{mpf_floor} to the next lower, and
@code{mpf_trunc} to the integer towards zero.
@end deftypefun
@deftypefun void mpf_urandomb (mpf_t @var{rop}, gmp_randstate_t @var{state}, unsigned long int @var{nbits})
Generate a universally distributed random float in the interval 0 <= X < 1 of
size NBITS.
The variable @var{state} must be initialized by calling one of the
@code{gmp_randinit} functions (@ref{Random State Initialization})
before invoking this function.
@end deftypefun
@deftypefun void mpf_random2 (mpf_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp})
Generate a random float of at most @var{max_size} limbs, with long strings of
zeros and ones in the binary representation. The exponent of the number is in
the interval @minus{}@var{exp} to @var{exp}. This function is useful for
testing functions and algorithms, since this kind of random numbers have
proven to be more likely to trigger corner-case bugs. Negative random numbers
are generated when @var{max_size} is negative.
@end deftypefun
@c @deftypefun size_t mpf_size (mpf_t @var{op})
@c Return the size of @var{op} measured in number of limbs. If @var{op} is
@c zero, the returned value will be zero. (@xref{Nomenclature}, for an
@c explanation of the concept @dfn{limb}.)
@c
@c @strong{This function is obsolete. It will disappear from future GMP
@c releases.}
@c @end deftypefun
@node Low-level Functions, Random Number Functions, Floating-point Functions, Top
@comment node-name, next, previous, up
@chapter Low-level Functions
@cindex Low-level functions
This chapter describes low-level GMP functions, used to implement the high-level
GMP functions, but also intended for time-critical user code.
These functions start with the prefix @code{mpn_}.
@c 1. Some of these function clobber input operands.
@c
The @code{mpn} functions are designed to be as fast as possible, @strong{not}
to provide a coherent calling interface. The different functions have somewhat
similar interfaces, but there are variations that make them hard to use. These
functions do as little as possible apart from the real multiple precision
computation, so that no time is spent on things that not all callers need.
A source operand is specified by a pointer to the least significant limb and a
limb count. A destination operand is specified by just a pointer. It is the
responsibility of the caller to ensure that the destination has enough space
for storing the result.
With this way of specifying operands, it is possible to perform computations
on subranges of an argument, and store the result into a subrange of a
destination.
A common requirement for all functions is that each source area needs at
least one limb. No size argument may be zero. Unless otherwise stated,
in-place operations are allowed where source and destination are the
same, but not where they only partly overlap.
The @code{mpn} functions are the base for the implementation of the
@code{mpz_}, @code{mpf_}, and @code{mpq_} functions.
This example adds the number beginning at @var{s1p} and the number
beginning at @var{s2p} and writes the sum at @var{destp}. All areas
have @var{size} limbs.
@example
cy = mpn_add_n (destp, s1p, s2p, size)
@end example
@noindent
In the notation used here, a source operand is identified by the pointer to
the least significant limb, and the limb count in braces. For example,
@{s1p, s1size@}.
@deftypefun mp_limb_t mpn_add_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size})
Add @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}, and
write the @var{size} least significant limbs of the result to @var{rp}.
Return carry, either 0 or 1.
This is the lowest-level function for addition. It is the preferred function
for addition, since it is written in assembly for most targets. For addition
of a variable to itself (i.e., @var{s1p} equals @var{s2p}, use
@code{mpn_lshift} with a count of 1 for optimal speed.
@end deftypefun
@deftypefun mp_limb_t mpn_add_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb})
Add @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the
@var{size} least significant limbs of the result to @var{rp}. Return
carry, either 0 or 1.
@end deftypefun
@deftypefun mp_limb_t mpn_add (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size})
Add @{@var{s1p}, @var{s1size}@} and @{@var{s2p},
@var{s2size}@}, and write the @var{s1size} least significant limbs of
the result to @var{rp}. Return carry, either 0 or 1.
This function requires that @var{s1size} is greater than or equal to
@var{s2size}.
@end deftypefun
@deftypefun mp_limb_t mpn_sub_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size})
Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p},
@var{size}@}, and write the @var{size} least significant limbs of the result
to @var{rp}. Return borrow, either 0 or 1.
This is the lowest-level function for subtraction. It is the preferred
function for subtraction, since it is written in assembly for most targets.
@end deftypefun
@deftypefun mp_limb_t mpn_sub_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb})
Subtract @var{s2limb} from @{@var{s1p}, @var{size}@}, and write the
@var{size} least significant limbs of the result to @var{rp}. Return
borrow, either 0 or 1.
@end deftypefun
@deftypefun mp_limb_t mpn_sub (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size})
Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p},
@var{s1size}@}, and write the @var{s1size} least significant limbs of
the result to @var{rp}. Return borrow, either 0 or 1.
This function requires that @var{s1size} is greater than or equal to
@var{s2size}.
@end deftypefun
@deftypefun void mpn_mul_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size})
Multiply @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@},
and write the @strong{entire} result to @var{rp}.
The destination has to have space for 2*@var{size} limbs, even if the
significant result might be one limb smaller.
@end deftypefun
@deftypefun mp_limb_t mpn_mul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb})
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the
@var{size} least significant limbs of the product to @var{rp}. Return
the most significant limb of the product.
This is a low-level function that is a building block for general
multiplication as well as other operations in GMP. It is written in assembly
for most targets.
Don't call this function if @var{s2limb} is a power of 2; use
@code{mpn_lshift} with a count equal to the logarithm of @var{s2limb}
instead, for optimal speed.
@end deftypefun
@deftypefun mp_limb_t mpn_addmul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb})
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and add the
@var{size} least significant limbs of the product to @{@var{rp},
@var{size}@} and write the result to @var{rp}. Return
the most significant limb of the product, plus carry-out from the addition.
This is a low-level function that is a building block for general
multiplication as well as other operations in GMP. It is written in assembly
for most targets.
@end deftypefun
@deftypefun mp_limb_t mpn_submul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb})
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and subtract the
@var{size} least significant limbs of the product from @{@var{rp},
@var{size}@} and write the result to @var{rp}. Return the most
significant limb of the product, minus borrow-out from the subtraction.
This is a low-level function that is a building block for general
multiplication and division as well as other operations in GMP. It is written
in assembly for most targets.
@end deftypefun
@deftypefun mp_limb_t mpn_mul (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size})
Multiply @{@var{s1p}, @var{s1size}@} and @{@var{s2p},
@var{s2size}@}, and write the result to @var{rp}. Return the most
significant limb of the result.
The destination has to have space for @var{s1size} + @var{s2size}
limbs, even if the result might be one limb smaller.
This function requires that @var{s1size} is greater than or equal to
@var{s2size}. The destination must be distinct from either input operands.
@end deftypefun
@deftypefun mp_limb_t mpn_tdiv_qr (mp_limb_t *@var{qp}, mp_limb_t *@var{rp}, mp_size_t @var{qxn}, const mp_limb_t *@var{np}, mp_size_t @var{nn}, const mp_limb_t *@var{dp}, mp_size_t @var{dn})
Divide @{@var{np}, @var{nn}@} by @{@var{dp}, @var{dn}@}. Write the quotient
at @var{qp} and the remainder at @var{rp}.
The quotient written at @var{qp} will be @var{nn} @minus{} @var{dn} + 1 limbs.
The remainder written at @var{rp} will be @var{dn} limbs.
It is required that @var{nn} is greater than or equal to @var{dn}. The
@var{qxn} operand must be zero.
The quotient is rounded towards 0.
No overlap between arguments is permitted.
@end deftypefun
@deftypefun mp_limb_t mpn_divrem (mp_limb_t *@var{r1p}, mp_size_t @var{xsize}, mp_limb_t *@var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t *@var{s3p}, mp_size_t @var{s3size})
[This function is obsolete. Please call @code{mpn_tdiv_qr} instead for
best performance.]
Divide @{@var{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and write
the quotient at @var{r1p}, with the exception of the most significant limb,
which is returned. The remainder replaces the dividend at @var{rs2p}; it will
be @var{s3size} limbs long (i.e., as many limbs as the divisor).
In addition to an integer quotient, @var{xsize} fraction limbs are developed,
and stored after the integral limbs. For most usages, @var{xsize} will be
zero.
It is required that @var{rs2size} is greater than or equal to @var{s3size}.
It is required that the most significant bit of the divisor is set.
If the quotient is not needed, pass @var{rs2p} + @var{s3size} as @var{r1p}.
Aside from that special case, no overlap between arguments is permitted.
Return the most significant limb of the quotient, either 0 or 1.
The area at @var{r1p} needs to be @var{rs2size} @minus{} @var{s3size} +
@var{xsize} limbs large.
@end deftypefun
@deftypefn Function mp_limb_t mpn_divrem_1 (mp_limb_t *@var{r1p}, mp_size_t @var{xsize}, @w{mp_limb_t *@var{s2p}}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb})
@deftypefnx Macro mp_limb_t mpn_divmod_1 (mp_limb_t *@var{r1p}, mp_limb_t *@var{s2p}, @w{mp_size_t @var{s2size}}, @w{mp_limb_t @var{s3limb}})
Divide @{@var{s2p}, @var{s2size}@} by @var{s3limb}, and write the quotient
at @var{r1p}. Return the remainder.
The integer quotient is written to @{@var{r1p}+@var{xsize}, @var{s2size}@} and
in addition @var{xsize} fraction limbs are developed and written to
@{@var{r1p}, @var{xsize}@}. Either or both @var{s2size} and @var{xsize} can
be zero. For most usages, @var{xsize} will be zero.
@code{mpn_divmod_1} exists for upward source compatibility and is simply a
macro calling @code{mpn_divrem_1} with an @var{xsize} of 0.
The areas at @var{r1p} and @var{s2p} have to be identical or completely
separate, not partially overlapping.
@end deftypefn
@deftypefun mp_limb_t mpn_divmod (mp_limb_t *@var{r1p}, mp_limb_t *@var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t *@var{s3p}, mp_size_t @var{s3size})
@strong{This interface is obsolete. It will disappear from future releases.
Use @code{mpn_divrem} in its stead.}
@end deftypefun
@deftypefn Macro mp_limb_t mpn_divexact_by3 (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{size}})
@deftypefnx Function mp_limb_t mpn_divexact_by3c (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{size}}, mp_limb_t @var{carry})
Divide @{@var{sp}, @var{size}@} by 3, expecting it to divide exactly, and
writing the result to @{@var{rp}, @var{size}@}. If 3 divides exactly, the
return value is zero and the result is the quotient. If not, the return value
is non-zero and the result won't be anything useful.
@code{mpn_divexact_by3c} takes an initial carry parameter, which can be the
return value from a previous call, so a large calculation can be done piece by
piece. @code{mpn_divexact_by3} is simply a macro calling
@code{mpn_divexact_by3c} with a 0 carry parameter.
These routines use a multiply-by-inverse and will be faster than
@code{mpn_divrem_1} on CPUs with fast multiplication but slow division.
The source @math{a}, result @math{q}, size @math{n}, initial carry @math{i},
and return value @math{c} satisfy
@tex
$c b^n + a - i = 3q$,
@end tex
@ifnottex
@math{c*b^n + a-i = 3*q},
@end ifnottex
where @math{b} is the size of a limb
@tex
($2^{32}$ or $2^{64}$).
@end tex
@ifnottex
(@math{2^32} or @math{2^64}).
@end ifnottex
@math{c} is always 0, 1 or 2, and the initial carry must also be 0, 1 or 2
(these are both borrows really). When @math{c=0}, clearly @math{q=(a-i)/3}.
When
@tex
$c \neq 0$,
the remainder $(a-i) \, mod \, 3$
@end tex
@ifnottex
@math{c!=0}, the remainder @math{(a-i) mod 3}
@end ifnottex
is given by @math{3-c}, because
@tex
$b \equiv 1 \, mod \, 3$.
@end tex
@ifnottex
@math{b @equiv{} 1 mod 3}.
@end ifnottex
@end deftypefn
@deftypefun mp_limb_t mpn_mod_1 (mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb})
Divide @{@var{s1p}, @var{s1size}@} by @var{s2limb}, and return the remainder.
@var{s1size} can be zero.
@end deftypefun
@deftypefun mp_limb_t mpn_preinv_mod_1 (mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}, mp_limb_t @var{s3limb})
@strong{This interface is obsolete. It will disappear from future releases.
Use @code{mpn_mod_1} in its stead.}
@end deftypefun
@deftypefun mp_limb_t mpn_bdivmod (mp_limb_t *@var{rp}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size}, unsigned long int @var{d})
The function puts the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
@var{q} =
@{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@}
mod 2^@var{d}
at @var{rp},
and returns the high @var{d} mod @var{BITS_PER_MP_LIMB} bits of @var{q}.
@{@var{s1p}, @var{s1size}@} - @var{q} * @{@var{s2p}, @var{s2size}@}
mod 2^(@var{s1size}*@var{BITS_PER_MP_LIMB})
is placed at @var{s1p}.
Since the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
this difference are zero, it is possible to overwrite the low limbs at
@var{s1p} with this difference,
provided @var{rp} <= @var{s1p}.
This function requires that @var{s1size} * @var{BITS_PER_MP_LIMB} >= @var{D},
and that @{@var{s2p}, @var{s2size}@} is odd.
@strong{This interface is preliminary. It might change incompatibly in
future revisions.}
@end deftypefun
@deftypefun mp_limb_t mpn_lshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the left, and
write the @var{src_size} least significant limbs of the result to
@var{rp}. @var{count} might be in the range 1 to n @minus{} 1, on an
n-bit machine. The bits shifted out to the left are returned.
Overlapping of the destination space and the source space is allowed in this
function, provided @var{rp} >= @var{src_ptr}.
This function is written in assembly for most targets.
@end deftypefun
@deftypefun mp_limp_t mpn_rshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the right, and
write the @var{src_size} most significant limbs of the result to
@var{rp}. @var{count} might be in the range 1 to n @minus{} 1, on an
n-bit machine. The bits shifted out to the right are returned.
Overlapping of the destination space and the source space is allowed in this
function, provided @var{rp} <= @var{src_ptr}.
This function is written in assembly for most targets.
@end deftypefun
@deftypefun int mpn_cmp (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size})
Compare @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@} and
return a positive value if s1 > src2, 0 of they are equal, and a negative
value if s1 < src2.
@end deftypefun
@deftypefun mp_size_t mpn_gcd (mp_limb_t *@var{rp}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t *@var{s2p}, mp_size_t @var{s2size})
Puts at @var{rp} the greatest common divisor of @{@var{s1p},
@var{s1size}@} and @{@var{s2p}, @var{s2size}@}; both source
operands are destroyed by the operation. The size in limbs of the greatest
common divisor is returned.
@{@var{s1p}, @var{s1size}@} must have at least as many bits as
@{@var{s2p}, @var{s2size}@}, and @{@var{s2p}, @var{s2size}@} must be odd.
@end deftypefun
@deftypefun mp_limb_t mpn_gcd_1 (const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb})
Return the greatest common divisor of @{@var{s1p}, @var{s1size}@}
and @var{s2limb}, where @var{s2limb} (as well as @var{s1size})
must be different from 0.
@end deftypefun
@deftypefun mp_size_t mpn_gcdext (mp_limb_t *@var{r1p}, mp_limb_t *@var{r2p}, mp_size_t *@var{r2size}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t *@var{s2p}, mp_size_t @var{s2size})
Compute the greatest common divisor of @{@var{s1p}, @var{s1size}@} and
@{@var{s2p}, @var{s2size}@}. Store the gcd at @var{r1p} and return its size
in limbs. Write the first cofactor at @var{r2p} and store its size in
*@var{r2size}. If the cofactor is negative, *@var{r2size} is negative and
@var{r2p} is the absolute value of the cofactor.
@{@var{s1p}, @var{s1size}@} must be greater than or equal to @{@var{s2p},
@var{s2size}@}. Neither operand may equal 0. Both source operands are
destroyed, plus one limb past the end of each, ie. @{@var{s1p},
@var{s1size}+1@} and @{@var{s2p}, @var{s2size}+1@}.
@end deftypefun
@deftypefun mp_size_t mpn_sqrtrem (mp_limb_t *@var{r1p}, mp_limb_t *@var{r2p}, const mp_limb_t *@var{sp}, mp_size_t @var{size})
Compute the square root of @{@var{sp}, @var{size}@} and put the result at
@var{r1p}. Write the remainder at @var{r2p}, unless @var{r2p} is @code{NULL}.
Return the size of the remainder, whether @var{r2p} was @code{NULL} or non-@code{NULL}.
Iff the operand was a perfect square, the return value will be 0.
The areas at @var{r1p} and @var{sp} have to be distinct. The areas at
@var{r2p} and @var{sp} have to be identical or completely separate, not
partially overlapping.
@ifnottex
The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs.
@end ifnottex
@tex
The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs.
@end tex
The area at @var{r2p} needs to be @var{size} limbs large.
@end deftypefun
@deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size})
Convert @{@var{s1p}, @var{s1size}@} to a raw unsigned char array in base
@var{base}. The string is not in ASCII; to convert it to printable format,
add the ASCII codes for @samp{0} or @samp{A}, depending on the base and
range. There may be leading zeros in the string.
The area at @var{s1p} is clobbered.
Return the number of characters in @var{str}.
The area at @var{str} has to have space for the largest possible number
represented by a @var{s1size} long limb array, plus one extra character.
@end deftypefun
@deftypefun mp_size_t mpn_set_str (mp_limb_t *@var{r1p}, const char *@var{str}, size_t @var{strsize}, int @var{base})
Convert the raw unsigned char array at @var{str} of length @var{strsize} to
a limb array @{@var{s1p}, @var{s1size}@}. The base of @var{str} is
@var{base}.
Return the number of limbs stored in @var{r1p}.
@end deftypefun
@deftypefun {unsigned long int} mpn_scan0 (const mp_limb_t *@var{s1p}, unsigned long int @var{bit})
Scan @var{s1p} from bit position @var{bit} for the next clear bit.
It is required that there be a clear bit within the area at @var{s1p} at or
beyond bit position @var{bit}, so that the function has something to return.
@end deftypefun
@deftypefun {unsigned long int} mpn_scan1 (const mp_limb_t *@var{s1p}, unsigned long int @var{bit})
Scan @var{s1p} from bit position @var{bit} for the next set bit.
It is required that there be a set bit within the area at @var{s1p} at or
beyond bit position @var{bit}, so that the function has something to return.
@end deftypefun
@deftypefun void mpn_random (mp_limb_t *@var{r1p}, mp_size_t @var{r1size})
@deftypefunx void mpn_random2 (mp_limb_t *@var{r1p}, mp_size_t @var{r1size})
Generate a random number of length @var{r1size} and store it at @var{r1p}.
The most significant limb is always non-zero. @code{mpn_random} generates
uniformly distributed limb data, @code{mpn_random2} generates long strings of
zeros and ones in the binary representation.
@code{mpn_random2} is intended for testing the correctness of the @code{mpn}
routines.
@end deftypefun
@deftypefun {unsigned long int} mpn_popcount (const mp_limb_t *@var{s1p}, unsigned long int @var{size})
Count the number of set bits in @{@var{s1p}, @var{size}@}.
@end deftypefun
@deftypefun {unsigned long int} mpn_hamdist (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, unsigned long int @var{size})
Compute the hamming distance between @{@var{s1p}, @var{size}@} and
@{@var{s2p}, @var{size}@}.
@end deftypefun
@deftypefun int mpn_perfect_square_p (const mp_limb_t *@var{s1p}, mp_size_t @var{size})
Return non-zero iff @{@var{s1p}, @var{size}@} is a perfect square.
@end deftypefun
@node Random Number Functions, BSD Compatible Functions, Low-level Functions, Top
@chapter Random Number Functions
@cindex Random number functions
There are two groups of random number functions in GNU MP; older
functions that call C library random number generators, rely on a global
state, and aren't very random; and newer functions that don't have these
problems. The newer functions are self-contained, they accept a random
state parameter that supplants global state, and generate good random
numbers.
The random state parameter is of the type @code{gmp_randstate_t}. It must be
initialized by a call to one of the @code{gmp_randinit} functions (@ref{Random
State Initialization}). The initial seed is set using one of the
@code{gmp_randseed} functions (@ref{Random State Initialization}).
The size of the seed determines the number of different sequences of
random numbers that is possible to generate. The ``quality'' of the
seed is the randomness of a given seed compared to the previous seed
used and affects the randomness of separate number sequences.
The algorithm for assigning seed is critical if the generated random numbers
are to be used for important applications, such as generating cryptographic
keys.
The traditional method is to use the current system time for seeding. One has
to be careful when using the current time though. If the application seeds the
random functions very often, say several times per second, and the resolution
of the system clock is comparatively low, like one second, the same sequence of
numbers will be generated until the system clock ticks. Furthermore, the
current system time is quite easy to guess, so a system depending on any
unpredictability of the random number sequence should absolutely not use that
as its only source for a seed value.
On some systems there is a special device, often called @code{/dev/random},
which provides a source of somewhat random numbers more usable as seed.
The functions actually generating random functions are documented under
``Miscellaneous Functions'' in their respective function class:
@ref{Miscellaneous Integer Functions}, @ref{Miscellaneous Float Functions}.
@menu
* Random State Initialization:: How to initialize a random state.
@end menu
@node Random State Initialization, , Random Number Functions, Random Number Functions
@section Random State Initialization
@cindex Random number state
See @ref{Random Number Functions} for a discussion on how to choose the
initial seed value passed to these functions.
@deftypefun void gmp_randinit (gmp_randstate_t @var{state}, gmp_randalg_t @var{alg}, ...)
Initialize random state variable @var{state}.
@var{alg} denotes what algorithm to use for random number generation.
Use one of
@itemize @minus
@item GMP_RAND_ALG_LC --- Linear congruential.
A fast generator defined by @math{X = (aX + c) mod m}.
A third argument @var{size} of type unsigned long int is required. @var{size}
is the size of the largest good quality random number to be generated,
expressed in number of bits. If the random generation functions are asked for
a bigger random number than indicated by this parameter, two or more numbers
of @var{size} bits will be generated and concatenated, resulting in a ``bad''
random number. This can be used to generate big random numbers relatively
cheap if the quality of randomness isn't of great importance.
a, c, and m are picked from a table where the modulus (m) is a power of 2 and
the multiplier is congruent to 5 (mod 8). The choice is based on the
@var{size} parameter. The maximum @var{size} supported by this algorithm is
128. If you need bigger random numbers, use your own scheme and call one of
the other @code{gmp_randinit} functions.
@ignore
@item GMP_RAND_ALG_BBS --- Blum, Blum, and Shub.
@end ignore
@end itemize
If @var{alg} is 0 or GMP_RAND_ALG_DEFAULT, the default algorithm is used. The
default algorithm is typically a fast algorithm like the linear congruential
and requires a third @var{size} argument (see GMP_RAND_ALG_LC).
When you're done with a @var{state} variable, call @code{gmp_randclear}
to deallocate any memory allocated by this function.
@code{gmp_randinit} may set the following bits in @var{gmp_errno}:
@c FIXME: gmp_errno is printed in uppercase. That's wrong.
@itemize
@item GMP_ERROR_UNSUPPORTED_ARGUMENT --- @var{alg} is unsupported
@item GMP_ERROR_INVALID_ARGUMENT --- @var{size} is too big
@end itemize
@end deftypefun
@ignore
@deftypefun void gmp_randinit_lc (gmp_randstate_t @var{state}, mpz_t @var{a},
unsigned long int @var{c}, mpz_t @var{m})
Initialize random state variable @var{state} with given linear congruential
scheme.
Parameters @var{a}, @var{c}, and @var{m} are the multiplier, adder, and modulus
for the linear congruential scheme to use, respectively.
When you're done with a @var{state} variable, call @code{gmp_randclear}
to deallocate any memory allocated by this function.
@end deftypefun
@end ignore
@deftypefun void gmp_randinit_lc_2exp (gmp_randstate_t @var{state}, mpz_t @var{a},
unsigned long int @var{c}, unsigned long int @var{m2exp})
Initialize random state variable @var{state} with given linear congruential
scheme.
Parameters @var{a}, @var{c}, and @var{m2exp} are the multiplier, adder, and
modulus for the linear congruential scheme to use, respectively. The modulus
is expressed as a power of 2, so that
@ifnottex
@var{m} = 2^@var{m2exp}.
@end ifnottex
@tex
$m = 2^{m2exp}$.
@end tex
The least significant bits of a random number generated by the linear
congruential algorithm where the modulus is a power of two are not very random.
Therefore, the lower half of a random number generated by an LC scheme
initialized with this function is discarded. Thus, the size of a random number
is @var{m2exp} / 2 (rounded upwards) bits when this function has been used for
initializing the random state.
When you're done with a @var{state} variable, call @code{gmp_randclear}
to deallocate any memory allocated by this function.
@end deftypefun
@deftypefun void gmp_randseed (gmp_randstate_t @var{state}, mpz_t @var{seed})
@deftypefunx void gmp_randseed_ui (gmp_randstate_t @var{state}, unsigned long int @var{seed})
Set the initial seed value.
Parameter @var{seed} is the initial random seed. The function
@code{gmp_randseed_ui} takes the @var{seed} as an unsigned long int rather
than as an mpz_t.
@end deftypefun
@deftypefun void gmp_randclear (gmp_randstate_t @var{state})
Free all memory occupied by @var{state}. Make sure to call this
function for all @code{gmp_randstate_t} variables when you are done with
them.
@end deftypefun
@node BSD Compatible Functions, Custom Allocation, Random Number Functions, Top
@comment node-name, next, previous, up
@chapter Berkeley MP Compatible Functions
@cindex Berkeley MP compatible functions
@cindex BSD MP compatible functions
These functions are intended to be fully compatible with the Berkeley MP
library which is available on many BSD derived U*ix systems. The
@samp{--enable-mpbsd} option must be used when building GNU MP to make these
available (@pxref{Installing GMP}).
The original Berkeley MP library has a usage restriction: you cannot use the
same variable as both source and destination in a single function call. The
compatible functions in GNU MP do not share this restriction---inputs and
outputs may overlap.
It is not recommended that new programs are written using these functions.
Apart from the incomplete set of functions, the interface for initializing
@code{MINT} objects is more error prone, and the @code{pow} function collides
with @code{pow} in @file{libm.a}.
@cindex @file{mp.h}
Include the header @file{mp.h} to get the definition of the necessary types
and functions. If you are on a BSD derived system, make sure to include GNU
@file{mp.h} if you are going to link the GNU @file{libmp.a} to your program.
This means that you probably need to give the -I<dir> option to the compiler,
where <dir> is the directory where you have GNU @file{mp.h}.
@deftypefun {MINT *} itom (signed short int @var{initial_value})
Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
Initialize the integer to @var{initial_value}. Return a pointer to the
@code{MINT} object.
@end deftypefun
@deftypefun {MINT *} xtom (char *@var{initial_value})
Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
Initialize the integer from @var{initial_value}, a hexadecimal, '\0'-terminate
C string. Return a pointer to the @code{MINT} object.
@end deftypefun
@deftypefun void move (MINT *@var{src}, MINT *@var{dest})
Set @var{dest} to @var{src} by copying. Both variables must be previously
initialized.
@end deftypefun
@deftypefun void madd (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
Add @var{src_1} and @var{src_2} and put the sum in @var{destination}.
@end deftypefun
@deftypefun void msub (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
Subtract @var{src_2} from @var{src_1} and put the difference in
@var{destination}.
@end deftypefun
@deftypefun void mult (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
Multiply @var{src_1} and @var{src_2} and put the product in
@var{destination}.
@end deftypefun
@deftypefun void mdiv (MINT *@var{dividend}, MINT *@var{divisor}, MINT *@var{quotient}, MINT *@var{remainder})
@deftypefunx void sdiv (MINT *@var{dividend}, signed short int @var{divisor}, MINT *@var{quotient}, signed short int *@var{remainder})
Set @var{quotient} to @var{dividend}/@var{divisor}, and @var{remainder} to
@var{dividend} mod @var{divisor}. The quotient is rounded towards zero; the
remainder has the same sign as the dividend unless it is zero.
Some implementations of these functions work differently---or not at all---for
negative arguments.
@end deftypefun
@deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder})
@ifnottex
Set @var{root} to the truncated integer part of the square root of
@var{operand}. Set @var{remainder} to
@var{operand}@minus{}@var{root}*@var{root},
@end ifnottex
@tex
Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like
@code{mpz_sqrt}. Set @var{remainder} to $(operand - root^2)$,
@end tex
(i.e., zero if @var{operand} is a perfect square).
If @var{root} and @var{remainder} are the same variable, the results are
undefined.
@end deftypefun
@deftypefun void pow (MINT *@var{base}, MINT *@var{exp}, MINT *@var{mod}, MINT *@var{dest})
Set @var{dest} to (@var{base} raised to @var{exp}) modulo @var{mod}.
@end deftypefun
@deftypefun void rpow (MINT *@var{base}, signed short int @var{exp}, MINT *@var{dest})
Set @var{dest} to @var{base} raised to @var{exp}.
@end deftypefun
@deftypefun void gcd (MINT *@var{operand1}, MINT *@var{operand2}, MINT *@var{res})
Set @var{res} to the greatest common divisor of @var{operand1} and
@var{operand2}.
@end deftypefun
@deftypefun int mcmp (MINT *@var{operand1}, MINT *@var{operand2})
Compare @var{operand1} and @var{operand2}. Return a positive value if
@var{operand1} > @var{operand2}, zero if @var{operand1} =
@var{operand2}, and a negative value if @var{operand1} < @var{operand2}.
@end deftypefun
@deftypefun void min (MINT *@var{dest})
Input a decimal string from @code{stdin}, and put the read integer in
@var{dest}. SPC and TAB are allowed in the number string, and are ignored.
@end deftypefun
@deftypefun void mout (MINT *@var{src})
Output @var{src} to @code{stdout}, as a decimal string. Also output a newline.
@end deftypefun
@deftypefun {char *} mtox (MINT *@var{operand})
Convert @var{operand} to a hexadecimal string, and return a pointer to the
string. The returned string is allocated using the default memory allocation
function, @code{malloc} by default.
@end deftypefun
@deftypefun void mfree (MINT *@var{operand})
De-allocate, the space used by @var{operand}. @strong{This function should
only be passed a value returned by @code{itom} or @code{xtom}.}
@end deftypefun
@node Custom Allocation, Contributors, BSD Compatible Functions, Top
@comment node-name, next, previous, up
@chapter Custom Allocation
@cindex Custom allocation
@cindex Memory allocation
@cindex Allocation of memory
By default, GMP uses @code{malloc}, @code{realloc} and @code{free} for memory
allocation. If @code{malloc} or @code{realloc} fails, GMP prints a message to
the standard error output and terminates execution.
Some applications might want to allocate memory in other ways, or might not
want a fatal error when there is no more memory available. To accomplish
this, you can specify alternative memory allocation functions.
This can be done in the Berkeley compatibility library as well as the main GMP
library.
@deftypefun void mp_set_memory_functions (@* void *(*@var{alloc_func_ptr}) (size_t), @* void *(*@var{realloc_func_ptr}) (void *, size_t, size_t), @* void (*@var{free_func_ptr}) (void *, size_t))
Replace the current allocation functions from the arguments. If an argument
is @code{NULL}, the corresponding default function is retained.
@strong{Be sure to call this function only when there are no active GMP
objects allocated using the previous memory functions! Usually, that means
that you have to call this function before any other GMP function.}
@end deftypefun
The functions you supply should fit the following declarations:
@deftypefun {void *} allocate_function (size_t @var{alloc_size})
This function should return a pointer to newly allocated space with at least
@var{alloc_size} storage units.
@end deftypefun
@deftypefun {void *} reallocate_function (void *@var{ptr}, size_t @var{old_size}, size_t @var{new_size})
This function should return a pointer to newly allocated space of at least
@var{new_size} storage units, after copying at least the first @var{old_size}
storage units from @var{ptr}. It should also de-allocate the space at
@var{ptr}.
You can assume that the space at @var{ptr} was formerly returned from
@code{allocate_function} or @code{reallocate_function}, for a request for
@var{old_size} storage units.
@end deftypefun
@deftypefun void deallocate_function (void *@var{ptr}, size_t @var{size})
De-allocate the space pointed to by @var{ptr}.
You can assume that the space at @var{ptr} was formerly returned from
@code{allocate_function} or @code{reallocate_function}, for a request for
@var{size} storage units.
@end deftypefun
(A @dfn{storage unit} is the unit in which the @code{sizeof} operator returns
the size of an object, normally an 8 bit byte.)
@node Contributors, References, Custom Allocation, Top
@comment node-name, next, previous, up
@unnumbered Contributors
@cindex Contributors
Torbjorn Granlund wrote the original GMP library and is still developing and
maintaining it. Several other individuals and organizations have contributed
to GMP in various ways. Here is a list in chronological order:
Gunnar Sjoedin and Hans Riesel helped with mathematical problems in early
versions of the library.
Richard Stallman contributed to the interface design and revised the first
version of this manual.
Brian Beuning and Doug Lea helped with testing of early versions of the
library and made creative suggestions.
John Amanatides of York University in Canada contributed the function
@code{mpz_probab_prime_p}.
Paul Zimmermann of Inria sparked the development of GMP 2, with his
comparisons between bignum packages.
Ken Weber (Kent State University, Universidade Federal do Rio Grande do Sul)
contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and
@code{mpn_bdivmod}, partially supported by CNPq (Brazil) grant 301314194-2.
Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' configure.
He has also made valuable suggestions and tested numerous intermediary
releases.
Joachim Hollman was involved in the design of the @code{mpf} interface, and in
the @code{mpz} design revisions for version 2.
Bennet Yee contributed the functions @code{mpz_jacobi} and @code{mpz_legendre}.
Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and
@file{mpn/m68k/rshift.S}.
The development of floating point functions of GNU MP 2, were supported in part
by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO (POlynomial
System SOlving).
GNU MP 2 was finished and released by SWOX AB (formerly known as TMG
Datakonsult), Swedenborgsgatan 23, SE-118 27 STOCKHOLM, SWEDEN, in
cooperation with the IDA Center for Computing Sciences, USA.
Robert Harley of Inria, France and David Seal of ARM, England, suggested clever
improvements for population count.
Robert Harley also wrote highly optimized Karatsuba and 3-way Toom
multiplication functions for GMP 3. He also contributed the ARM assembly
code.
Torsten Ekedahl of the Mathematical department of Stockholm University provided
significant inspiration during several phases of the GMP development. His
mathematical expertise helped improve several algorithms.
Paul Zimmermann wrote the Burnikel-Ziegler division code, the REDC code, the
REDC-based mpz_powm code, and the FFT multiply code. The ECMNET project Paul
is organizing has been a driving force behind many of the optimization of GMP
3.
Linus Nordberg wrote the new configure system based on autoconf and
implemented the new random functions.
Kent Boortz made the Macintosh port.
Kevin Ryde wrote a lot of very high quality x86 code, optimized for most CPU
variants. He also made countless other valuable contributions.
Steve Root helped write the optimized alpha 21264 assembly code.
GNU MP 3.1 was finished and released by Torbjorn Granlund and Kevin Ryde.
Torbjorn's work was partially funded by the IDA Center for Computing Sciences,
USA.
(This list is chronological, not ordered after significance. If you have
contributed to GMP but are not listed above, please tell @email{tege@@swox.com}
about the omission!)
@node References, Concept Index, Contributors, Top
@comment node-name, next, previous, up
@unnumbered References
@cindex References
@itemize @bullet
@item
Donald E. Knuth, "The Art of Computer Programming", vol 2,
"Seminumerical Algorithms", 3rd edition, Addison-Wesley, 1988.
@item
John D. Lipson, "Elements of Algebra and Algebraic Computing",
The Benjamin Cummings Publishing Company Inc, 1981.
@item
Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, 1999,
available online @uref{http://www.gnu.org/software/gcc/onlinedocs/}, and in
the GCC package @uref{ftp://ftp.gnu.org/pub/gnu/gcc/}.
@item
Peter L. Montgomery, "Modular Multiplication Without Trial Division", in
Mathematics of Computation, volume 44, number 170, April 1985.
@item
Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant
Integers using Multiplication", in Proceedings of the SIGPLAN
PLDI'94 Conference, June 1994. Available online, @*
@uref{ftp://ftp.cwi.nl/pub/pmontgom/divcnst.psa4.gz} (and .psl.gz too).
@item
Tudor Jebelean,
"An algorithm for exact division",
Journal of Symbolic Computation,
v. 15, 1993, pp. 169-180.
Research report version available online @*
@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-35.ps.gz}
@item
Kenneth Weber, "The accelerated integer GCD algorithm",
ACM Transactions on Mathematical Software,
v. 21 (March), 1995, pp. 111-122.
@item
Christoph Burnikel and Joachim Ziegler, "Fast Recursive Division",
Max-Planck-Institut fuer Informatik Research Report MPI-I-98-1-022, @*
@uref{http://www.mpi-sb.mpg.de/~ziegler/TechRep.ps.gz}.
@item
Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, "Handbook of
Applied Cryptography", @uref{http://cacr.math.uwaterloo.ca/hac/}.
@item
Henri Cohen, "A Course in Computational Algebraic Number Theory", Graduate
Texts in Mathematics number 138, Springer-Verlag, 1993. Errata available
online @* @uref{http://www.math.u-bordeaux.fr/~cohen}
@end itemize
@node Concept Index, Function Index, References, Top
@comment node-name, next, previous, up
@unnumbered Concept Index
@printindex cp
@node Function Index, , Concept Index, Top
@comment node-name, next, previous, up
@unnumbered Function and Type Index
@printindex fn
@contents
@bye
@c Local variables:
@c fill-column: 78
@c End:
|