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
|
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@page
@node SRFI Support
@section SRFI Support Modules
@cindex SRFI
SRFI is an acronym for Scheme Request For Implementation. The SRFI
documents define a lot of syntactic and procedure extensions to standard
Scheme as defined in R5RS.
Guile has support for a number of SRFIs. This chapter gives an overview
over the available SRFIs and some usage hints. For complete
documentation, design rationales and further examples, we advise you to
get the relevant SRFI documents from the SRFI home page
@url{http://srfi.schemers.org}.
@menu
* About SRFI Usage:: What to know about Guile's SRFI support.
* SRFI-0:: cond-expand
* SRFI-1:: List library.
* SRFI-2:: and-let*.
* SRFI-4:: Homogeneous numeric vector datatypes.
* SRFI-6:: Basic String Ports.
* SRFI-8:: receive.
* SRFI-9:: define-record-type.
* SRFI-10:: Hash-Comma Reader Extension.
* SRFI-11:: let-values and let-values*.
* SRFI-13:: String library.
* SRFI-14:: Character-set library.
* SRFI-16:: case-lambda
* SRFI-17:: Generalized set!
* SRFI-19:: Time/Date library.
* SRFI-26:: Specializing parameters
* SRFI-31:: A special form `rec' for recursive evaluation
* SRFI-39:: Parameter objects
@end menu
@node About SRFI Usage
@subsection About SRFI Usage
@c FIXME::martin: Review me!
SRFI support in Guile is currently implemented partly in the core
library, and partly as add-on modules. That means that some SRFIs are
automatically available when the interpreter is started, whereas the
other SRFIs require you to use the appropriate support module
explicitly.
There are several reasons for this inconsistency. First, the feature
checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
available immediately, because it must be there when the user wants to
check for the Scheme implementation, that is, before she can know that
it is safe to use @code{use-modules} to load SRFI support modules. The
second reason is that some features defined in SRFIs had been
implemented in Guile before the developers started to add SRFI
implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
the future, it is possible that SRFIs in the core library might be
factored out into separate modules, requiring explicit module loading
when they are needed. So you should be prepared to have to use
@code{use-modules} someday in the future to access SRFI-6 bindings. If
you want, you can do that already. We have included the module
@code{(srfi srfi-6)} in the distribution, which currently does nothing,
but ensures that you can write future-safe code.
Generally, support for a specific SRFI is made available by using
modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
number of the SRFI needed. Another possibility is to use the command
line option @code{--use-srfi}, which will load the necessary modules
automatically (@pxref{Invoking Guile}).
@node SRFI-0
@subsection SRFI-0 - cond-expand
@cindex SRFI-0
This SRFI lets a portable Scheme program test for the presence of
certain features, and adapt itself by using different blocks of code,
or fail if the necessary features are not available. There's no
module to load, this is in the Guile core.
A program designed only for Guile will generally not need this
mechanism, such a program can of course directly use the various
documented parts of Guile.
@deffn syntax cond-expand (feature body@dots{}) @dots{}
Expand to the @var{body} of the first clause whose @var{feature}
specification is satisfied. It is an error if no @var{feature} is
satisfied.
Features are symbols such as @code{srfi-1}, and a feature
specification can use @code{and}, @code{or} and @code{not} forms to
test combinations. The last clause can be an @code{else}, to be used
if no other passes.
For example, define a private version of @code{alist-cons} if SRFI-1
is not available.
@example
(cond-expand (srfi-1
)
(else
(define (alist-cons key val alist)
(cons (cons key val) alist))))
@end example
Or demand a certain set of SRFIs (list operations, string ports,
@code{receive} and string operations), failing if they're not
available.
@example
(cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
))
@end example
@end deffn
@noindent
The Guile core has the following features,
@example
guile
r5rs
srfi-0
srfi-4
srfi-6
srfi-13
srfi-14
@end example
Other SRFI feature symbols are defined once their code has been loaded
with @code{use-modules}, since only then are their bindings available.
The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
a good way to load SRFIs to satisfy @code{cond-expand} when running a
portable program.
Testing the @code{guile} feature allows a program to adapt itself to
the Guile module system, but still run on other Scheme systems. For
example the following demands SRFI-8 (@code{receive}), but also knows
how to load it with the Guile mechanism.
@example
(cond-expand (srfi-8
)
(guile
(use-modules (srfi srfi-8))))
@end example
It should be noted that @code{cond-expand} is separate from the
@code{*features*} mechanism (@pxref{Feature Tracking}), feature
symbols in one are unrelated to those in the other.
@node SRFI-1
@subsection SRFI-1 - List library
@cindex SRFI-1
@cindex list
@c FIXME::martin: Review me!
The list library defined in SRFI-1 contains a lot of useful list
processing procedures for construction, examining, destructuring and
manipulating lists and pairs.
Since SRFI-1 also defines some procedures which are already contained
in R5RS and thus are supported by the Guile core library, some list
and pair procedures which appear in the SRFI-1 document may not appear
in this section. So when looking for a particular list/pair
processing procedure, you should also have a look at the sections
@ref{Lists} and @ref{Pairs}.
@menu
* SRFI-1 Constructors:: Constructing new lists.
* SRFI-1 Predicates:: Testing list for specific properties.
* SRFI-1 Selectors:: Selecting elements from lists.
* SRFI-1 Length Append etc:: Length calculation and list appending.
* SRFI-1 Fold and Map:: Higher-order list processing.
* SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
* SRFI-1 Searching:: Search for elements.
* SRFI-1 Deleting:: Delete elements from lists.
* SRFI-1 Association Lists:: Handle association lists.
* SRFI-1 Set Operations:: Use lists for representing sets.
@end menu
@node SRFI-1 Constructors
@subsubsection Constructors
@cindex list constructor
@c FIXME::martin: Review me!
New lists can be constructed by calling one of the following
procedures.
@deffn {Scheme Procedure} xcons d a
Like @code{cons}, but with interchanged arguments. Useful mostly when
passed to higher-order procedures.
@end deffn
@deffn {Scheme Procedure} list-tabulate n init-proc
Return an @var{n}-element list, where each list element is produced by
applying the procedure @var{init-proc} to the corresponding list
index. The order in which @var{init-proc} is applied to the indices
is not specified.
@end deffn
@deffn {Scheme Procedure} list-copy lst
Return a new list containing the elements of the list @var{lst}.
This function differs from the core @code{list-copy} (@pxref{List
Constructors}) in accepting improper lists too. And if @var{lst} is
not a pair at all then it's treated as the final tail of an improper
list and simply returned.
@end deffn
@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
Return a circular list containing the given arguments @var{elt1}
@var{elt2} @dots{}.
@end deffn
@deffn {Scheme Procedure} iota count [start step]
Return a list containing @var{count} numbers, starting from
@var{start} and adding @var{step} each time. The default @var{start}
is 0, the default @var{step} is 1. For example,
@example
(iota 6) @result{} (0 1 2 3 4 5)
(iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
@end example
This function takes its name from the corresponding primitive in the
APL language.
@end deffn
@node SRFI-1 Predicates
@subsubsection Predicates
@cindex list predicate
@c FIXME::martin: Review me!
The procedures in this section test specific properties of lists.
@deffn {Scheme Procedure} proper-list? obj
Return @code{#t} if @var{obj} is a proper list, or @code{#f}
otherwise. This is the same as the core @code{list?} (@pxref{List
Predicates}).
A proper list is a list which ends with the empty list @code{()} in
the usual way. The empty list @code{()} itself is a proper list too.
@example
(proper-list? '(1 2 3)) @result{} #t
(proper-list? '()) @result{} #t
@end example
@end deffn
@deffn {Scheme Procedure} circular-list? obj
Return @code{#t} if @var{obj} is a circular list, or @code{#f}
otherwise.
A circular list is a list where at some point the @code{cdr} refers
back to a previous pair in the list (either the start or some later
point), so that following the @code{cdr}s takes you around in a
circle, with no end.
@example
(define x (list 1 2 3 4))
(set-cdr! (last-pair x) (cddr x))
x @result{} (1 2 3 4 3 4 3 4 ...)
(circular-list? x) @result{} #t
@end example
@end deffn
@deffn {Scheme Procedure} dotted-list? obj
Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
otherwise.
A dotted list is a list where the @code{cdr} of the last pair is not
the empty list @code{()}. Any non-pair @var{obj} is also considered a
dotted list, with length zero.
@example
(dotted-list? '(1 2 . 3)) @result{} #t
(dotted-list? 99) @result{} #t
@end example
@end deffn
It will be noted that any Scheme object passes exactly one of the
above three tests @code{proper-list?}, @code{circular-list?} and
@code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
are either @code{proper-list?} or @code{dotted-list?}, and infinite
lists are @code{circular-list?}.
@sp 1
@deffn {Scheme Procedure} null-list? lst
Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
otherwise. If something else than a proper or circular list is passed
as @var{lst}, an error is signalled. This procedure is recommended
for checking for the end of a list in contexts where dotted lists are
not allowed.
@end deffn
@deffn {Scheme Procedure} not-pair? obj
Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
This is shorthand notation @code{(not (pair? @var{obj}))} and is
supposed to be used for end-of-list checking in contexts where dotted
lists are allowed.
@end deffn
@deffn {Scheme Procedure} list= elt= list1 @dots{}
Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
List equality is determined by testing whether all lists have the same
length and the corresponding elements are equal in the sense of the
equality predicate @var{elt=}. If no or only one list is given,
@code{#t} is returned.
@end deffn
@node SRFI-1 Selectors
@subsubsection Selectors
@cindex list selector
@c FIXME::martin: Review me!
@deffn {Scheme Procedure} first pair
@deffnx {Scheme Procedure} second pair
@deffnx {Scheme Procedure} third pair
@deffnx {Scheme Procedure} fourth pair
@deffnx {Scheme Procedure} fifth pair
@deffnx {Scheme Procedure} sixth pair
@deffnx {Scheme Procedure} seventh pair
@deffnx {Scheme Procedure} eighth pair
@deffnx {Scheme Procedure} ninth pair
@deffnx {Scheme Procedure} tenth pair
These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
@end deffn
@deffn {Scheme Procedure} car+cdr pair
Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
@end deffn
@deffn {Scheme Procedure} take lst i
@deffnx {Scheme Procedure} take! lst i
Return a list containing the first @var{i} elements of @var{lst}.
@code{take!} may modify the structure of the argument list @var{lst}
in order to produce the result.
@end deffn
@deffn {Scheme Procedure} drop lst i
Return a list containing all but the first @var{i} elements of
@var{lst}.
@end deffn
@deffn {Scheme Procedure} take-right lst i
Return the a list containing the @var{i} last elements of @var{lst}.
@end deffn
@deffn {Scheme Procedure} drop-right lst i
@deffnx {Scheme Procedure} drop-right! lst i
Return the a list containing all but the @var{i} last elements of
@var{lst}.
@code{drop-right!} may modify the structure of the argument list
@var{lst} in order to produce the result.
@end deffn
@deffn {Scheme Procedure} split-at lst i
@deffnx {Scheme Procedure} split-at! lst i
Return two values, a list containing the first @var{i} elements of the
list @var{lst} and a list containing the remaining elements.
@code{split-at!} may modify the structure of the argument list
@var{lst} in order to produce the result.
@end deffn
@deffn {Scheme Procedure} last lst
Return the last element of the non-empty, finite list @var{lst}.
@end deffn
@node SRFI-1 Length Append etc
@subsubsection Length, Append, Concatenate, etc.
@c FIXME::martin: Review me!
@deffn {Scheme Procedure} length+ lst
Return the length of the argument list @var{lst}. When @var{lst} is a
circular list, @code{#f} is returned.
@end deffn
@deffn {Scheme Procedure} concatenate list-of-lists
@deffnx {Scheme Procedure} concatenate! list-of-lists
Construct a list by appending all lists in @var{list-of-lists}.
@code{concatenate!} may modify the structure of the given lists in
order to produce the result.
@code{concatenate} is the same as @code{(apply append
@var{list-of-lists})}. It exists because some Scheme implementations
have a limit on the number of arguments a function takes, which the
@code{apply} might exceed. In Guile there is no such limit.
@end deffn
@deffn {Scheme Procedure} append-reverse rev-head tail
@deffnx {Scheme Procedure} append-reverse! rev-head tail
Reverse @var{rev-head}, append @var{tail} and return the result. This
is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
but more efficient.
@code{append-reverse!} may modify @var{rev-head} in order to produce
the result.
@end deffn
@deffn {Scheme Procedure} zip lst1 lst2 @dots{}
Return a list as long as the shortest of the argument lists, where
each element is a list. The first list contains the first elements of
the argument lists, the second list contains the second elements, and
so on.
@end deffn
@deffn {Scheme Procedure} unzip1 lst
@deffnx {Scheme Procedure} unzip2 lst
@deffnx {Scheme Procedure} unzip3 lst
@deffnx {Scheme Procedure} unzip4 lst
@deffnx {Scheme Procedure} unzip5 lst
@code{unzip1} takes a list of lists, and returns a list containing the
first elements of each list, @code{unzip2} returns two lists, the
first containing the first elements of each lists and the second
containing the second elements of each lists, and so on.
@end deffn
@deffn {Scheme Procedure} count pred lst1 @dots{} lstN
Return a count of the number of times @var{pred} returns true when
called on elements from the given lists.
@var{pred} is called with @var{N} parameters @code{(@var{pred}
@var{elem1} @dots{} @var{elemN})}, each element being from the
corresponding @var{lst1} @dots{} @var{lstN}. The first call is with
the first element of each list, the second with the second element
from each, and so on.
Counting stops when the end of the shortest list is reached. At least
one list must be non-circular.
@end deffn
@node SRFI-1 Fold and Map
@subsubsection Fold, Unfold & Map
@cindex list fold
@cindex list map
@c FIXME::martin: Review me!
@deffn {Scheme Procedure} fold proc init lst1 @dots{} lstN
@deffnx {Scheme Procedure} fold-right proc init lst1 @dots{} lstN
Apply @var{proc} to the elements of @var{lst1} @dots{} @var{lstN} to
build a result, and return that result.
Each @var{proc} call is @code{(@var{proc} @var{elem1} @dots{}
@var{elemN} @var{previous})}, where @var{elem1} is from @var{lst1},
through @var{elemN} from @var{lstN}. @var{previous} is the return
from the previous call to @var{proc}, or the given @var{init} for the
first call. If any list is empty, just @var{init} is returned.
@code{fold} works through the list elements from first to last. The
following shows a list reversal and the calls it makes,
@example
(fold cons '() '(1 2 3))
(cons 1 '())
(cons 2 '(1))
(cons 3 '(2 1)
@result{} (3 2 1)
@end example
@code{fold-right} works through the list elements from last to first,
ie.@: from the right. So for example the following finds the longest
string, and the last among equal longest,
@example
(fold-right (lambda (str prev)
(if (> (string-length str) (string-length prev))
str
prev))
""
'("x" "abc" "xyz" "jk"))
@result{} "xyz"
@end example
If @var{lst1} through @var{lstN} have different lengths, @code{fold}
stops when the end of the shortest is reached; @code{fold-right}
commences at the last element of the shortest. Ie.@: elements past
the length of the shortest are ignored in the other @var{lst}s. At
least one @var{lst} must be non-circular.
@code{fold} should be preferred over @code{fold-right} if the order of
processing doesn't matter, or can be arranged either way, since
@code{fold} is a little more efficient.
The way @code{fold} builds a result from iterating is quite general,
it can do more than other iterations like say @code{map} or
@code{filter}. The following for example removes adjacent duplicate
elements from a list,
@example
(define (delete-adjacent-duplicates lst)
(fold-right (lambda (elem ret)
(if (equal? elem (first ret))
ret
(cons elem ret)))
(list (last lst))
lst))
(delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
@result{} (1 2 3 4 5)
@end example
Clearly the same sort of thing can be done with a @code{for-each} and
a variable in which to build the result, but a self-contained
@var{proc} can be re-used in multiple contexts, where a
@code{for-each} would have to be written out each time.
@end deffn
@deffn {Scheme Procedure} pair-fold proc init lst1 @dots{} lstN
@deffnx {Scheme Procedure} pair-fold-right proc init lst1 @dots{} lstN
The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
the pairs of the lists instead of the list elements.
@end deffn
@deffn {Scheme Procedure} reduce proc default lst
@deffnx {Scheme Procedure} reduce-right proc default lst
@code{reduce} is a variant of @code{fold}, where the first call to
@var{proc} is on two elements from @var{lst}, rather than one element
and a given initial value.
If @var{lst} is empty, @code{reduce} returns @var{default} (this is
the only use for @var{default}). If @var{lst} has just one element
then that's the return value. Otherwise @var{proc} is called on the
elements of @var{lst}.
Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
where @var{elem} is from @var{lst} (the second and subsequent elements
of @var{lst}), and @var{previous} is the return from the previous call
to @var{proc}. The first element of @var{lst} is the @var{previous}
for the first call to @var{proc}.
For example, the following adds a list of numbers, the calls made to
@code{+} are shown. (Of course @code{+} accepts multiple arguments
and can add a list directly, with @code{apply}.)
@example
(reduce + 0 '(5 6 7)) @result{} 18
(+ 6 5) @result{} 11
(+ 7 11) @result{} 18
@end example
@code{reduce} can be used instead of @code{fold} where the @var{init}
value is an ``identity'', meaning a value which under @var{proc}
doesn't change the result, in this case 0 is an identity since
@code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
@code{reduce-right} is a similar variation on @code{fold-right},
working from the end (ie.@: the right) of @var{lst}. The last element
of @var{lst} is the @var{previous} for the first call to @var{proc},
and the @var{elem} values go from the second last.
@code{reduce} should be preferred over @code{reduce-right} if the
order of processing doesn't matter, or can be arranged either way,
since @code{reduce} is a little more efficient.
@end deffn
@deffn {Scheme Procedure} unfold p f g seed [tail-gen]
@code{unfold} is defined as follows:
@lisp
(unfold p f g seed) =
(if (p seed) (tail-gen seed)
(cons (f seed)
(unfold p f g (g seed))))
@end lisp
@table @var
@item p
Determines when to stop unfolding.
@item f
Maps each seed value to the corresponding list element.
@item g
Maps each seed value to next seed valu.
@item seed
The state value for the unfold.
@item tail-gen
Creates the tail of the list; defaults to @code{(lambda (x) '())}.
@end table
@var{g} produces a series of seed values, which are mapped to list
elements by @var{f}. These elements are put into a list in
left-to-right order, and @var{p} tells when to stop unfolding.
@end deffn
@deffn {Scheme Procedure} unfold-right p f g seed [tail]
Construct a list with the following loop.
@lisp
(let lp ((seed seed) (lis tail))
(if (p seed) lis
(lp (g seed)
(cons (f seed) lis))))
@end lisp
@table @var
@item p
Determines when to stop unfolding.
@item f
Maps each seed value to the corresponding list element.
@item g
Maps each seed value to next seed valu.
@item seed
The state value for the unfold.
@item tail-gen
Creates the tail of the list; defaults to @code{(lambda (x) '())}.
@end table
@end deffn
@deffn {Scheme Procedure} map f lst1 lst2 @dots{}
Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
return a list containing the results of the procedure applications.
This procedure is extended with respect to R5RS, because the argument
lists may have different lengths. The result list will have the same
length as the shortest argument lists. The order in which @var{f}
will be applied to the list element(s) is not specified.
@end deffn
@deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
Apply the procedure @var{f} to each pair of corresponding elements of
the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
specified. This procedure is extended with respect to R5RS, because
the argument lists may have different lengths. The shortest argument
list determines the number of times @var{f} is called. @var{f} will
be applied to the list elements in left-to-right order.
@end deffn
@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
Equivalent to
@lisp
(apply append (map f clist1 clist2 ...))
@end lisp
and
@lisp
(apply append! (map f clist1 clist2 ...))
@end lisp
Map @var{f} over the elements of the lists, just as in the @code{map}
function. However, the results of the applications are appended
together to make the final result. @code{append-map} uses
@code{append} to append the results together; @code{append-map!} uses
@code{append!}.
The dynamic order in which the various applications of @var{f} are
made is not specified.
@end deffn
@deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
Linear-update variant of @code{map} -- @code{map!} is allowed, but not
required, to alter the cons cells of @var{lst1} to construct the
result list.
The dynamic order in which the various applications of @var{f} are
made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
@dots{} must have at least as many elements as @var{lst1}.
@end deffn
@deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
Like @code{for-each}, but applies the procedure @var{f} to the pairs
from which the argument lists are constructed, instead of the list
elements. The return value is not specified.
@end deffn
@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
Like @code{map}, but only results from the applications of @var{f}
which are true are saved in the result list.
@end deffn
@node SRFI-1 Filtering and Partitioning
@subsubsection Filtering and Partitioning
@cindex list filter
@cindex list partition
@c FIXME::martin: Review me!
Filtering means to collect all elements from a list which satisfy a
specific condition. Partitioning a list means to make two groups of
list elements, one which contains the elements satisfying a condition,
and the other for the elements which don't.
The @code{filter} and @code{filter!} functions are implemented in the
Guile core, @xref{List Modification}.
@deffn {Scheme Procedure} partition pred lst
@deffnx {Scheme Procedure} partition! pred lst
Split @var{lst} into those elements which do and don't satisfy the
predicate @var{pred}.
The return is two values (@pxref{Multiple Values}), the first being a
list of all elements from @var{lst} which satisfy @var{pred}, the
second a list of those which do not.
The elements in the result lists are in the same order as in @var{lst}
but the order in which the calls @code{(@var{pred} elem)} are made on
the list elements is unspecified.
@code{partition} does not change @var{lst}, but one of the returned
lists may share a tail with it. @code{partition!} may modify
@var{lst} to construct its return.
@end deffn
@deffn {Scheme Procedure} remove pred lst
@deffnx {Scheme Procedure} remove! pred lst
Return a list containing all elements from @var{lst} which do not
satisfy the predicate @var{pred}. The elements in the result list
have the same order as in @var{lst}. The order in which @var{pred} is
applied to the list elements is not specified.
@code{remove!} is allowed, but not required to modify the structure of
the input list.
@end deffn
@node SRFI-1 Searching
@subsubsection Searching
@cindex list search
@c FIXME::martin: Review me!
The procedures for searching elements in lists either accept a
predicate or a comparison object for determining which elements are to
be searched.
@deffn {Scheme Procedure} find pred lst
Return the first element of @var{lst} which satisfies the predicate
@var{pred} and @code{#f} if no such element is found.
@end deffn
@deffn {Scheme Procedure} find-tail pred lst
Return the first pair of @var{lst} whose @sc{car} satisfies the
predicate @var{pred} and @code{#f} if no such element is found.
@end deffn
@deffn {Scheme Procedure} take-while pred lst
@deffnx {Scheme Procedure} take-while! pred lst
Return the longest initial prefix of @var{lst} whose elements all
satisfy the predicate @var{pred}.
@code{take-while!} is allowed, but not required to modify the input
list while producing the result.
@end deffn
@deffn {Scheme Procedure} drop-while pred lst
Drop the longest initial prefix of @var{lst} whose elements all
satisfy the predicate @var{pred}.
@end deffn
@deffn {Scheme Procedure} span pred lst
@deffnx {Scheme Procedure} span! pred lst
@deffnx {Scheme Procedure} break pred lst
@deffnx {Scheme Procedure} break! pred lst
@code{span} splits the list @var{lst} into the longest initial prefix
whose elements all satisfy the predicate @var{pred}, and the remaining
tail. @code{break} inverts the sense of the predicate.
@code{span!} and @code{break!} are allowed, but not required to modify
the structure of the input list @var{lst} in order to produce the
result.
Note that the name @code{break} conflicts with the @code{break}
binding established by @code{while} (@pxref{while do}). Applications
wanting to use @code{break} from within a @code{while} loop will need
to make a new define under a different name.
@end deffn
@deffn {Scheme Procedure} any pred lst1 lst2 @dots{} lstN
Test whether any set of elements from @var{lst1} @dots{} lstN
satisfies @var{pred}. If so the return value is the return from the
successful @var{pred} call, or if not the return is @code{#f}.
Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
@var{elemN})} taking an element from each @var{lst}. The calls are
made successively for the first, second, etc elements of the lists,
stopping when @var{pred} returns non-@code{#f}, or when the end of the
shortest list is reached.
The @var{pred} call on the last set of elements (ie.@: when the end of
the shortest list has been reached), if that point is reached, is a
tail call.
@end deffn
@deffn {Scheme Procedure} every pred lst1 lst2 @dots{} lstN
Test whether every set of elements from @var{lst1} @dots{} lstN
satisfies @var{pred}. If so the return value is the return from the
final @var{pred} call, or if not the return is @code{#f}.
Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
@var{elemN})} taking an element from each @var{lst}. The calls are
made successively for the first, second, etc elements of the lists,
stopping if @var{pred} returns @code{#f}, or when the end of any of
the lists is reached.
The @var{pred} call on the last set of elements (ie.@: when the end of
the shortest list has been reached) is a tail call.
If one of @var{lst1} @dots{} @var{lstN} is empty then no calls to
@var{pred} are made, and the return is @code{#t}.
@end deffn
@deffn {Scheme Procedure} list-index pred lst1 @dots{} lstN
Return the index of the first set of elements, one from each of
@var{lst1}@dots{}@var{lstN}, which satisfies @var{pred}.
@var{pred} is called as @code{(@var{pred} elem1 @dots{} elemN)}.
Searching stops when the end of the shortest @var{lst} is reached.
The return index starts from 0 for the first set of elements. If no
set of elements pass then the return is @code{#f}.
@example
(list-index odd? '(2 4 6 9)) @result{} 3
(list-index = '(1 2 3) '(3 1 2)) @result{} #f
@end example
@end deffn
@deffn {Scheme Procedure} member x lst [=]
Return the first sublist of @var{lst} whose @sc{car} is equal to
@var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
Equality is determined by @code{equal?}, or by the equality predicate
@var{=} if given. @var{=} is called @code{(= @var{x} elem)},
ie.@: with the given @var{x} first, so for example to find the first
element greater than 5,
@example
(member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
@end example
This version of @code{member} extends the core @code{member}
(@pxref{List Searching}) by accepting an equality predicate.
@end deffn
@node SRFI-1 Deleting
@subsubsection Deleting
@cindex list delete
@c FIXME::martin: Review me!
@deffn {Scheme Procedure} delete x lst [=]
@deffnx {Scheme Procedure} delete! x lst [=]
Return a list containing the elements of @var{lst} but with those
equal to @var{x} deleted. The returned elements will be in the same
order as they were in @var{lst}.
Equality is determined by the @var{=} predicate, or @code{equal?} if
not given. An equality call is made just once for each element, but
the order in which the calls are made on the elements is unspecified.
The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
is first. This means for instance elements greater than 5 can be
deleted with @code{(delete 5 lst <)}.
@code{delete} does not modify @var{lst}, but the return might share a
common tail with @var{lst}. @code{delete!} may modify the structure
of @var{lst} to construct its return.
These functions extend the core @code{delete} and @code{delete!} in
accepting an equality predicate. (@pxref{List Modification})
@end deffn
@deffn {Scheme Procedure} delete-duplicates lst [=]
@deffnx {Scheme Procedure} delete-duplicates! lst [=]
Return a list containing the elements of @var{lst} but without
duplicates.
When elements are equal, only the first in @var{lst} is retained.
Equal elements can be anywhere in @var{lst}, they don't have to be
adjacent. The returned list will have the retained elements in the
same order as they were in @var{lst}.
Equality is determined by the @var{=} predicate, or @code{equal?} if
not given. Calls @code{(= x y)} are made with element @var{x} being
before @var{y} in @var{lst}. A call is made at most once for each
combination, but the sequence of the calls across the elements is
unspecified.
@code{delete-duplicates} does not modify @var{lst}, but the return
might share a common tail with @var{lst}. @code{delete-duplicates!}
may modify the structure of @var{lst} to construct its return.
In the worst case, this is an @math{O(N^2)} algorithm because it must
check each element against all those preceding it. For long lists it
is more efficient to sort and then compare only adjacent elements.
@end deffn
@node SRFI-1 Association Lists
@subsubsection Association Lists
@cindex association list
@cindex alist
@c FIXME::martin: Review me!
Association lists are described in detail in section @ref{Association
Lists}. The present section only documents the additional procedures
for dealing with association lists defined by SRFI-1.
@deffn {Scheme Procedure} assoc key alist [=]
Return the pair from @var{alist} which matches @var{key}. Equality is
determined by @var{=}, which defaults to @code{equal?} if not given.
@var{alist} must be an association lists---a list of pairs.
This function extends the core @code{assoc} by accepting an equality
predicate. (@pxref{Association Lists})
@end deffn
@deffn {Scheme Procedure} alist-cons key datum alist
Equivalent to
@lisp
(cons (cons @var{key} @var{datum}) @var{alist})
@end lisp
This procedure is used to coons a new pair onto an existing
association list.
@end deffn
@deffn {Scheme Procedure} alist-copy alist
Return a newly allocated copy of @var{alist}, that means that the
spine of the list as well as the pairs are copied.
@end deffn
@deffn {Scheme Procedure} alist-delete key alist [=]
@deffnx {Scheme Procedure} alist-delete! key alist [=]
Return a list containing the elements of @var{alist} but with those
elements whose keys are equal to @var{key} deleted. The returned
elements will be in the same order as they were in @var{alist}.
Equality is determined by the @var{=} predicate, or @code{equal?} if
not given. The order in which elements are tested is unspecified, but
each equality call is made @code{(= key alistkey)}, ie. the given
@var{key} parameter is first and the key from @var{alist} second.
This means for instance all associations with a key greater than 5 can
be removed with @code{(alist-delete 5 alist <)}.
@code{alist-delete} does not modify @var{alist}, but the return might
share a common tail with @var{alist}. @code{alist-delete!} may modify
the list structure of @var{alist} to construct its return.
@end deffn
@node SRFI-1 Set Operations
@subsubsection Set Operations on Lists
@cindex list set operation
@c FIXME::martin: Review me!
Lists can be used for representing sets of objects. The procedures
documented in this section can be used for such set representations.
Man combining several sets or adding elements, they make sure that no
object is contained more than once in a given list. Please note that
lists are not a too efficient implementation method for sets, so if
you need high performance, you should think about implementing a
custom data structure for representing sets, such as trees, bitsets,
hash tables or something similar.
All these procedures accept an equality predicate as the first
argument. This predicate is used for testing the objects in the list
sets for sameness.
@deffn {Scheme Procedure} lset<= = list1 @dots{}
Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
otherwise return @code{#f}. Returns @code{#t} if called with less
than two arguments. @var{=} is used for testing element equality.
@end deffn
@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
Return @code{#t} if all argument lists are equal. @var{=} is used for
testing element equality.
@end deffn
@deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{}
Add all @var{elts} to the list @var{list}, suppressing duplicates and
return the resulting list. @var{=} is used for testing
element equality.
@end deffn
@deffn {Scheme Procedure} lset-union = list1 @dots{}
@deffnx {Scheme Procedure} lset-union! = list1 @dots{}
Return the union of all argument list sets. The union is the set of
all elements which appear in any of the argument sets.
@code{lset-union!} is allowed, but not required to modify its first
argument. @var{=} is used for testing element equality.
@end deffn
@deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
Return the intersection of all argument list sets. The intersection
is the set containing all elements which appear in all argument sets.
@code{lset-intersection!} is allowed, but not required to modify its
first argument. @var{=} is used for testing element equality.
@end deffn
@deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
Return the difference of all argument list sets. The difference is
the the set containing all elements of the first list which do not
appear in the other lists. @code{lset-difference!} is allowed, but
not required to modify its first argument. @var{=} is used for testing
element equality.
@end deffn
@deffn {Scheme Procedure} lset-xor = list1 @dots{}
@deffnx {Scheme Procedure} lset-xor! = list1 @dots{}
Return the set containing all elements which appear in the first
argument list set, but not in the second; or, more generally: which
appear in an odd number of sets. @code{lset-xor!} is allowed, but
not required to modify its first argument. @var{=} is used for testing
element equality.
@end deffn
@deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
Return two values, the difference and the intersection of the argument
list sets. This works like a combination of @code{lset-difference} and
@code{lset-intersection}, but is more efficient.
@code{lset-diff+intersection!} is allowed, but not required to modify
its first argument. @var{=} is used for testing element equality. You
have to use some means to deal with the multiple values these
procedures return (@pxref{Multiple Values}).
@end deffn
@node SRFI-2
@subsection SRFI-2 - and-let*
@cindex SRFI-2
@noindent
The following syntax can be obtained with
@lisp
(use-modules (srfi srfi-2))
@end lisp
@deffn {library syntax} and-let* (clause @dots{}) body @dots{}
A combination of @code{and} and @code{let*}.
Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
then evaluation stops and @code{#f} is returned. If all are
non-@code{#f} then @var{body} is evaluated and the last form gives the
return value, or if @var{body} is empty then the result is @code{#t}.
Each @var{clause} should be one of the following,
@table @code
@item (symbol expr)
Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
Like @code{let*}, that binding is available to subsequent clauses.
@item (expr)
Evaluate @var{expr} and check for @code{#f}.
@item symbol
Get the value bound to @var{symbol} and check for @code{#f}.
@end table
Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
instance @code{((eq? x y))}. One way to remember this is to imagine
the @code{symbol} in @code{(symbol expr)} is omitted.
@code{and-let*} is good for calculations where a @code{#f} value means
termination, but where a non-@code{#f} value is going to be needed in
subsequent expressions.
The following illustrates this, it returns text between brackets
@samp{[...]} in a string, or @code{#f} if there are no such brackets
(ie.@: either @code{string-index} gives @code{#f}).
@example
(define (extract-brackets str)
(and-let* ((start (string-index str #\[))
(end (string-index str #\] start)))
(substring str (1+ start) end)))
@end example
The following shows plain variables and expressions tested too.
@code{diagnostic-levels} is taken to be an alist associating a
diagnostic type with a level. @code{str} is printed only if the type
is known and its level is high enough.
@example
(define (show-diagnostic type str)
(and-let* (want-diagnostics
(level (assq-ref diagnostic-levels type))
((>= level current-diagnostic-level)))
(display str)))
@end example
The advantage of @code{and-let*} is that an extended sequence of
expressions and tests doesn't require lots of nesting as would arise
from separate @code{and} and @code{let*}, or from @code{cond} with
@code{=>}.
@end deffn
@node SRFI-4
@subsection SRFI-4 - Homogeneous numeric vector datatypes
@cindex SRFI-4
The SRFI-4 procedures and data types are always available, @xref{Uniform
Numeric Vectors}.
@node SRFI-6
@subsection SRFI-6 - Basic String Ports
@cindex SRFI-6
SRFI-6 defines the procedures @code{open-input-string},
@code{open-output-string} and @code{get-output-string}. These
procedures are included in the Guile core, so using this module does not
make any difference at the moment. But it is possible that support for
SRFI-6 will be factored out of the core library in the future, so using
this module does not hurt, after all.
@node SRFI-8
@subsection SRFI-8 - receive
@cindex SRFI-8
@code{receive} is a syntax for making the handling of multiple-value
procedures easier. It is documented in @xref{Multiple Values}.
@node SRFI-9
@subsection SRFI-9 - define-record-type
@cindex SRFI-9
@cindex record
This SRFI is a syntax for defining new record types and creating
predicate, constructor, and field getter and setter functions. In
Guile this is simply an alternate interface to the core record
functionality (@pxref{Records}). It can be used with,
@example
(use-modules (srfi srfi-9))
@end example
@deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
@sp 1
Create a new record type, and make various @code{define}s for using
it. This syntax can only occur at the top-level, not nested within
some other form.
@var{type} is bound to the record type, which is as per the return
from the core @code{make-record-type}. @var{type} also provides the
name for the record, as per @code{record-type-name}.
@var{constructor} is bound to a function to be called as
@code{(@var{constructor} fieldval @dots{})} to create a new record of
this type. The arguments are initial values for the fields, one
argument for each field, in the order they appear in the
@code{define-record-type} form.
The @var{fieldname}s provide the names for the record fields, as per
the core @code{record-type-fields} etc, and are referred to in the
subsequent accessor/modifier forms.
@var{predictate} is bound to a function to be called as
@code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f}
according to whether @var{obj} is a record of this type.
Each @var{accessor} is bound to a function to be called
@code{(@var{accessor} record)} to retrieve the respective field from a
@var{record}. Similarly each @var{modifier} is bound to a function to
be called @code{(@var{modifier} record val)} to set the respective
field in a @var{record}.
@end deffn
@noindent
An example will illustrate typical usage,
@example
(define-record-type employee-type
(make-employee name age salary)
employee?
(name get-employee-name)
(age get-employee-age set-employee-age)
(salary get-employee-salary set-employee-salary))
@end example
This creates a new employee data type, with name, age and salary
fields. Accessor functions are created for each field, but no
modifier function for the name (the intention in this example being
that it's established only when an employee object is created). These
can all then be used as for example,
@example
employee-type @result{} #<record-type employee-type>
(define fred (make-employee "Fred" 45 20000.00))
(employee? fred) @result{} #t
(get-employee-age fred) @result{} 45
(set-employee-salary fred 25000.00) ;; pay rise
@end example
The functions created by @code{define-record-type} are ordinary
top-level @code{define}s. They can be redefined or @code{set!} as
desired, exported from a module, etc.
@node SRFI-10
@subsection SRFI-10 - Hash-Comma Reader Extension
@cindex SRFI-10
@cindex hash-comma
@cindex #,()
This SRFI implements a reader extension @code{#,()} called hash-comma.
It allows the reader to give new kinds of objects, for use both in
data and as constants or literals in source code. This feature is
available with
@example
(use-modules (srfi srfi-10))
@end example
@noindent
The new read syntax is of the form
@example
#,(@var{tag} @var{arg}@dots{})
@end example
@noindent
where @var{tag} is a symbol and the @var{arg}s are objects taken as
parameters. @var{tag}s are registered with the following procedure.
@deffn {Scheme Procedure} define-reader-ctor tag proc
Register @var{proc} as the constructor for a hash-comma read syntax
starting with symbol @var{tag}, ie. @nicode{#,(@var{tag} arg@dots{})}.
@var{proc} is called with the given arguments @code{(@var{proc}
arg@dots{})} and the object it returns is the result of the read.
@end deffn
@noindent
For example, a syntax giving a list of @var{N} copies of an object.
@example
(define-reader-ctor 'repeat
(lambda (obj reps)
(make-list reps obj)))
(display '#,(repeat 99 3))
@print{} (99 99 99)
@end example
Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
@code{repeat} handler returns a list and the program must quote to use
it literally, the same as any other list. Ie.
@example
(display '#,(repeat 99 3))
@result{}
(display '(99 99 99))
@end example
When a handler returns an object which is self-evaluating, like a
number or a string, then there's no need for quoting, just as there's
no need when giving those directly as literals. For example an
addition,
@example
(define-reader-ctor 'sum
(lambda (x y)
(+ x y)))
(display #,(sum 123 456)) @print{} 579
@end example
A typical use for @nicode{#,()} is to get a read syntax for objects
which don't otherwise have one. For example, the following allows a
hash table to be given literally, with tags and values, ready for fast
lookup.
@example
(define-reader-ctor 'hash
(lambda elems
(let ((table (make-hash-table)))
(for-each (lambda (elem)
(apply hash-set! table elem))
elems)
table)))
(define (animal->family animal)
(hash-ref '#,(hash ("tiger" "cat")
("lion" "cat")
("wolf" "dog"))
animal))
(animal->family "lion") @result{} "cat"
@end example
Or for example the following is a syntax for a compiled regular
expression (@pxref{Regular Expressions}).
@example
(use-modules (ice-9 regex))
(define-reader-ctor 'regexp make-regexp)
(define (extract-angs str)
(let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str)))
(and match
(match:substring match 1))))
(extract-angs "foo <BAR> quux") @result{} "BAR"
@end example
@sp 1
@nicode{#,()} is somewhat similar to @code{define-macro}
(@pxref{Macros}) in that handler code is run to produce a result, but
@nicode{#,()} operates at the read stage, so it can appear in data for
@code{read} (@pxref{Scheme Read}), not just in code to be executed.
Because @nicode{#,()} is handled at read-time it has no direct access
to variables etc. A symbol in the arguments is just a symbol, not a
variable reference. The arguments are essentially constants, though
the handler procedure can use them in any complicated way it might
want.
Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
globally, there's no need to use @code{(srfi srfi-10)} in later
modules. Similarly the tags registered are global and can be used
anywhere once registered.
There's no attempt to record what previous @nicode{#,()} forms have
been seen, if two identical forms occur then two calls are made to the
handler procedure. The handler might like to maintain a cache or
similar to avoid making copies of large objects, depending on expected
usage.
In code the best uses of @nicode{#,()} are generally when there's a
lot of objects of a particular kind as literals or constants. If
there's just a few then some local variables and initializers are
fine, but that becomes tedious and error prone when there's a lot, and
the anonymous and compact syntax of @nicode{#,()} is much better.
@node SRFI-11
@subsection SRFI-11 - let-values
@cindex SRFI-11
@findex let-values
@findex let-values*
This module implements the binding forms for multiple values
@code{let-values} and @code{let-values*}. These forms are similar to
@code{let} and @code{let*} (@pxref{Local Bindings}), but they support
binding of the values returned by multiple-valued expressions.
Write @code{(use-modules (srfi srfi-11))} to make the bindings
available.
@lisp
(let-values (((x y) (values 1 2))
((z f) (values 3 4)))
(+ x y z f))
@result{}
10
@end lisp
@code{let-values} performs all bindings simultaneously, which means that
no expression in the binding clauses may refer to variables bound in the
same clause list. @code{let-values*}, on the other hand, performs the
bindings sequentially, just like @code{let*} does for single-valued
expressions.
@node SRFI-13
@subsection SRFI-13 - String Library
@cindex SRFI-13
The SRFI-13 procedures are always available, @xref{Strings}.
@node SRFI-14
@subsection SRFI-14 - Character-set Library
@cindex SRFI-14
The SRFI-14 data type and procedures are always available,
@xref{Character Sets}.
@node SRFI-16
@subsection SRFI-16 - case-lambda
@cindex SRFI-16
@cindex variable arity
@cindex arity, variable
@c FIXME::martin: Review me!
@findex case-lambda
The syntactic form @code{case-lambda} creates procedures, just like
@code{lambda}, but has syntactic extensions for writing procedures of
varying arity easier.
The syntax of the @code{case-lambda} form is defined in the following
EBNF grammar.
@example
@group
<case-lambda>
--> (case-lambda <case-lambda-clause>)
<case-lambda-clause>
--> (<formals> <definition-or-command>*)
<formals>
--> (<identifier>*)
| (<identifier>* . <identifier>)
| <identifier>
@end group
@end example
The value returned by a @code{case-lambda} form is a procedure which
matches the number of actual arguments against the formals in the
various clauses, in order. @dfn{Formals} means a formal argument list
just like with @code{lambda} (@pxref{Lambda}). The first matching clause
is selected, the corresponding values from the actual parameter list are
bound to the variable names in the clauses and the body of the clause is
evaluated. If no clause matches, an error is signalled.
The following (silly) definition creates a procedure @var{foo} which
acts differently, depending on the number of actual arguments. If one
argument is given, the constant @code{#t} is returned, two arguments are
added and if more arguments are passed, their product is calculated.
@lisp
(define foo (case-lambda
((x) #t)
((x y) (+ x y))
(z
(apply * z))))
(foo 'bar)
@result{}
#t
(foo 2 4)
@result{}
6
(foo 3 3 3)
@result{}
27
(foo)
@result{}
1
@end lisp
The last expression evaluates to 1 because the last clause is matched,
@var{z} is bound to the empty list and the following multiplication,
applied to zero arguments, yields 1.
@node SRFI-17
@subsection SRFI-17 - Generalized set!
@cindex SRFI-17
This is an implementation of SRFI-17: Generalized set!
@findex getter-with-setter
It exports the Guile procedure @code{make-procedure-with-setter} under
the SRFI name @code{getter-with-setter} and exports the standard
procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
@code{string-ref} and @code{vector-ref} as procedures with setters, as
required by the SRFI.
SRFI-17 was heavily criticized during its discussion period but it was
finalized anyway. One issue was its concept of globally associating
setter @dfn{properties} with (procedure) values, which is non-Schemy.
For this reason, this implementation chooses not to provide a way to set
the setter of a procedure. In fact, @code{(set! (setter @var{proc})
@var{setter})} signals an error. The only way to attach a setter to a
procedure is to create a new object (a @dfn{procedure with setter}) via
the @code{getter-with-setter} procedure. This procedure is also
specified in the SRFI. Using it avoids the described problems.
@node SRFI-19
@subsection SRFI-19 - Time/Date Library
@cindex SRFI-19
@cindex time
@cindex date
This is an implementation of the SRFI-19 time/date library. The
functions and variables described here are provided by
@example
(use-modules (srfi srfi-19))
@end example
@menu
* SRFI-19 Introduction::
* SRFI-19 Time::
* SRFI-19 Date::
* SRFI-19 Time/Date conversions::
* SRFI-19 Date to string::
* SRFI-19 String to date::
@end menu
@node SRFI-19 Introduction
@subsubsection SRFI-19 Introduction
@cindex universal time
@cindex atomic time
@cindex UTC
@cindex TAI
This module implements time and date representations and calculations,
in various time systems, including universal time (UTC) and atomic
time (TAI).
For those not familiar with these time systems, TAI is based on a
fixed length second derived from oscillations of certain atoms. UTC
differs from TAI by an integral number of seconds, which is increased
or decreased at announced times to keep UTC aligned to a mean solar
day (the orbit and rotation of the earth are not quite constant).
@cindex leap second
So far, only increases in the TAI
@tex
$\leftrightarrow$
@end tex
@ifnottex
<->
@end ifnottex
UTC difference have been needed. Such an increase is a ``leap
second'', an extra second of TAI introduced at the end of a UTC day.
When working entirely within UTC this is never seen, every day simply
has 86400 seconds. But when converting from TAI to a UTC date, an
extra 23:59:60 is present, where normally a day would end at 23:59:59.
Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
seconds.
@cindex system clock
In the current implementation, the system clock is assumed to be UTC,
and a table of leap seconds in the code converts to TAI. See comments
in @file{srfi-19.scm} for how to update this table.
@cindex julian day
@cindex modified julian day
Also, for those not familiar with the terminology, a @dfn{Julian Day}
is a real number which is a count of days and fraction of a day, in
UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from
1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time
is julian day 2400000.5.
@c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
@c noon, UTC), but this is incorrect. It looks like it might have
@c arisen from the code incorrectly treating years a multiple of 100
@c but not 400 prior to 1582 as non-leap years, where instead the Julian
@c calendar should be used so all multiples of 4 before 1582 are leap
@c years.
@node SRFI-19 Time
@subsubsection SRFI-19 Time
@cindex time
A @dfn{time} object has type, seconds and nanoseconds fields
representing a point in time starting from some epoch. This is an
arbitrary point in time, not just a time of day. Although times are
represented in nanoseconds, the actual resolution may be lower.
The following variables hold the possible time types. For instance
@code{(current-time time-process)} would give the current CPU process
time.
@defvar time-utc
Universal Coordinated Time (UTC).
@cindex UTC
@end defvar
@defvar time-tai
International Atomic Time (TAI).
@cindex TAI
@end defvar
@defvar time-monotonic
Monotonic time, meaning a monotonically increasing time starting from
an unspecified epoch.
Note that in the current implementation @code{time-monotonic} is the
same as @code{time-tai}, and unfortunately is therefore affected by
adjustments to the system clock. Perhaps this will change in the
future.
@end defvar
@defvar time-duration
A duration, meaning simply a difference between two times.
@end defvar
@defvar time-process
CPU time spent in the current process, starting from when the process
began.
@cindex process time
@end defvar
@defvar time-thread
CPU time spent in the current thread. Not currently implemented.
@cindex thread time
@end defvar
@sp 1
@defun time? obj
Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
@end defun
@defun make-time type nanoseconds seconds
Create a time object with the given @var{type}, @var{seconds} and
@var{nanoseconds}.
@end defun
@defun time-type time
@defunx time-nanosecond time
@defunx time-second time
@defunx set-time-type! time type
@defunx set-time-nanosecond! time nsec
@defunx set-time-second! time sec
Get or set the type, seconds or nanoseconds fields of a time object.
@code{set-time-type!} merely changes the field, it doesn't convert the
time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
@end defun
@defun copy-time time
Return a new time object, which is a copy of the given @var{time}.
@end defun
@defun current-time [type]
Return the current time of the given @var{type}. The default
@var{type} is @code{time-utc}.
Note that the name @code{current-time} conflicts with the Guile core
@code{current-time} function (@pxref{Time}). Applications wanting to
use both will need to use a different name for one of them.
@end defun
@defun time-resolution [type]
Return the resolution, in nanoseconds, of the given time @var{type}.
The default @var{type} is @code{time-utc}.
@end defun
@defun time<=? t1 t2
@defunx time<? t1 t2
@defunx time=? t1 t2
@defunx time>=? t1 t2
@defunx time>? t1 t2
Return @code{#t} or @code{#f} according to the respective relation
between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
must be the same time type.
@end defun
@defun time-difference t1 t2
@defunx time-difference! t1 t2
Return a time object of type @code{time-duration} representing the
period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
the same time type.
@code{time-difference} returns a new time object,
@code{time-difference!} may modify @var{t1} to form its return.
@end defun
@defun add-duration time duration
@defunx add-duration! time duration
@defunx subtract-duration time duration
@defunx subtract-duration! time duration
Return a time object which is @var{time} with the given @var{duration}
added or subtracted. @var{duration} must be a time object of type
@code{time-duration}.
@code{add-duration} and @code{subtract-duration} return a new time
object. @code{add-duration!} and @code{subtract-duration!} may modify
the given @var{time} to form their return.
@end defun
@node SRFI-19 Date
@subsubsection SRFI-19 Date
@cindex date
A @dfn{date} object represents a date in the Gregorian calendar and a
time of day on that date in some timezone.
The fields are year, month, day, hour, minute, second, nanoseconds and
timezone. A date object is immutable, its fields can be read but they
cannot be modified once the object is created.
@defun date? obj
Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
@end defun
@defun make-date nsecs seconds minutes hours date month year zone-offset
Create a new date object.
@c
@c FIXME: What can we say about the ranges of the values. The
@c current code looks it doesn't normalize, but expects then in their
@c usual range already.
@c
@end defun
@defun date-nanosecond date
Nanoseconds, 0 to 999999999.
@end defun
@defun date-second date
Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
entirely within UTC, it's only when converting to or from TAI.
@end defun
@defun date-minute date
Minutes, 0 to 59.
@end defun
@defun date-hour date
Hour, 0 to 23.
@end defun
@defun date-day date
Day of the month, 1 to 31 (or less, according to the month).
@end defun
@defun date-month date
Month, 1 to 12.
@end defun
@defun date-year date
Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
B.C. There is no year 0, year @math{-1} is followed by year 1.
@end defun
@defun date-zone-offset date
Time zone, an integer number of seconds east of Greenwich.
@end defun
@defun date-year-day date
Day of the year, starting from 1 for 1st January.
@end defun
@defun date-week-day date
Day of the week, starting from 0 for Sunday.
@end defun
@defun date-week-number date dstartw
Week of the year, ignoring a first partial week. @var{dstartw} is the
day of the week which is taken to start a week, 0 for Sunday, 1 for
Monday, etc.
@c
@c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
@c The code looks like it's 0, if that's the correct intention.
@c
@end defun
@c The SRFI text doesn't actually give the default for tz-offset, but
@c the reference implementation has the local timezone and the
@c conversions functions all specify that, so it should be ok to
@c document it here.
@c
@defun current-date [tz-offset]
Return a date object representing the current date/time, in UTC offset
by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
defaults to the local timezone.
@end defun
@defun current-julian-day
@cindex julian day
Return the current Julian Day.
@end defun
@defun current-modified-julian-day
@cindex modified julian day
Return the current Modified Julian Day.
@end defun
@node SRFI-19 Time/Date conversions
@subsubsection SRFI-19 Time/Date conversions
@cindex time conversion
@cindex date conversion
@defun date->julian-day date
@defunx date->modified-julian-day date
@defunx date->time-monotonic date
@defunx date->time-tai date
@defunx date->time-utc date
@end defun
@defun julian-day->date jdn [tz-offset]
@defunx julian-day->time-monotonic jdn
@defunx julian-day->time-tai jdn
@defunx julian-day->time-utc jdn
@end defun
@defun modified-julian-day->date jdn [tz-offset]
@defunx modified-julian-day->time-monotonic jdn
@defunx modified-julian-day->time-tai jdn
@defunx modified-julian-day->time-utc jdn
@end defun
@defun time-monotonic->date time [tz-offset]
@defunx time-monotonic->time-tai time
@defunx time-monotonic->time-tai! time
@defunx time-monotonic->time-utc time
@defunx time-monotonic->time-utc! time
@end defun
@defun time-tai->date time [tz-offset]
@defunx time-tai->julian-day time
@defunx time-tai->modified-julian-day time
@defunx time-tai->time-monotonic time
@defunx time-tai->time-monotonic! time
@defunx time-tai->time-utc time
@defunx time-tai->time-utc! time
@end defun
@defun time-utc->date time [tz-offset]
@defunx time-utc->julian-day time
@defunx time-utc->modified-julian-day time
@defunx time-utc->time-monotonic time
@defunx time-utc->time-monotonic! time
@defunx time-utc->time-tai time
@defunx time-utc->time-tai! time
@sp 1
Convert between dates, times and days of the respective types. For
instance @code{time-tai->time-utc} accepts a @var{time} object of type
@code{time-tai} and returns an object of type @code{time-utc}.
The @code{!} variants may modify their @var{time} argument to form
their return. The plain functions create a new object.
For conversions to dates, @var{tz-offset} is seconds east of
Greenwich. The default is the local timezone, at the given time, as
provided by the system, using @code{localtime} (@pxref{Time}).
On 32-bit systems, @code{localtime} is limited to a 32-bit
@code{time_t}, so a default @var{tz-offset} is only available for
times between Dec 1901 and Jan 2038. For prior dates an application
might like to use the value in 1902, though some locations have zone
changes prior to that. For future dates an application might like to
assume today's rules extend indefinitely. But for correct daylight
savings transitions it will be necessary to take an offset for the
same day and time but a year in range and which has the same starting
weekday and same leap/non-leap (to support rules like last Sunday in
October).
@end defun
@node SRFI-19 Date to string
@subsubsection SRFI-19 Date to string
@cindex date to string
@cindex string, from date
@defun date->string date [format]
Convert a date to a string under the control of a format.
@var{format} should be a string containing @samp{~} escapes, which
will be expanded as per the following conversion table. The default
@var{format} is @samp{~c}, a locale-dependent date and time.
Many of these conversion characters are the same as POSIX
@code{strftime} (@pxref{Time}), but there are some extras and some
variations.
@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
@item @nicode{~~} @tab literal ~
@item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
@item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
@item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
@item @nicode{~B} @tab locale full month, eg.@: @samp{January}
@item @nicode{~c} @tab locale date and time, eg.@: @*
@samp{Fri Jul 14 20:28:42-0400 2000}
@item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
@c Spec says d/m/y, reference implementation says m/d/y.
@c Apparently the reference code was the intention, but would like to
@c see an errata published for the spec before contradicting it here.
@c
@c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
@item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
@item @nicode{~f} @tab seconds and fractional seconds,
with locale decimal point, eg.@: @samp{5.2}
@item @nicode{~h} @tab same as @nicode{~b}
@item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
@item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
@item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
@item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
@item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
@item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
@item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
@item @nicode{~n} @tab newline
@item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
@item @nicode{~p} @tab locale AM or PM
@item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
@item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
@item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
(usual limit is 59, 60 is a leap second)
@item @nicode{~t} @tab horizontal tab character
@item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
@item @nicode{~U} @tab week of year, Sunday first day of week,
@samp{00} to @samp{52}
@item @nicode{~V} @tab week of year, Monday first day of week,
@samp{01} to @samp{53}
@item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
@item @nicode{~W} @tab week of year, Monday first day of week,
@samp{00} to @samp{52}
@c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
@c date. The reference code has ~x as the locale date and ~X as a
@c locale time. The rule is apparently that the code should be
@c believed, but would like to see an errata for the spec before
@c contradicting it here.
@c
@c @item @nicode{~x} @tab week of year, Monday as first day of week,
@c @samp{00} to @samp{53}
@c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
@item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
@item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
@item @nicode{~z} @tab time zone, RFC-822 style
@item @nicode{~Z} @tab time zone symbol (not currently implemented)
@item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
@item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
@item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
@item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
@item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
@end multitable
@end defun
Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
described here, since the specification and reference implementation
differ.
Currently Guile doesn't implement any localizations for the above, all
outputs are in English, and the @samp{~c} conversion is POSIX
@code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in
the future.
@node SRFI-19 String to date
@subsubsection SRFI-19 String to date
@cindex string to date
@cindex date, from string
@c FIXME: Can we say what happens when an incomplete date is
@c converted? Ie. fields left as 0, or what? The spec seems to be
@c silent on this.
@defun string->date input template
Convert an @var{input} string to a date under the control of a
@var{template} string. Return a newly created date object.
Literal characters in @var{template} must match characters in
@var{input} and @samp{~} escapes must match the input forms described
in the table below. ``Skip to'' means characters up to one of the
given type are ignored, or ``no skip'' for no skipping. ``Read'' is
what's then read, and ``Set'' is the field affected in the date
object.
For example @samp{~Y} skips input characters until a digit is reached,
at which point it expects a year and stores that to the year field of
the date.
@multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
@item
@tab Skip to
@tab Read
@tab Set
@item @nicode{~~}
@tab no skip
@tab literal ~
@tab nothing
@item @nicode{~a}
@tab @nicode{char-alphabetic?}
@tab locale abbreviated weekday name
@tab nothing
@item @nicode{~A}
@tab @nicode{char-alphabetic?}
@tab locale full weekday name
@tab nothing
@c Note that the SRFI spec says that ~b and ~B don't set anything,
@c but that looks like a mistake. The reference implementation sets
@c the month field, which seems sensible and is what we describe
@c here.
@item @nicode{~b}
@tab @nicode{char-alphabetic?}
@tab locale abbreviated month name
@tab @nicode{date-month}
@item @nicode{~B}
@tab @nicode{char-alphabetic?}
@tab locale full month name
@tab @nicode{date-month}
@item @nicode{~d}
@tab @nicode{char-numeric?}
@tab day of month
@tab @nicode{date-day}
@item @nicode{~e}
@tab no skip
@tab day of month, blank padded
@tab @nicode{date-day}
@item @nicode{~h}
@tab same as @samp{~b}
@item @nicode{~H}
@tab @nicode{char-numeric?}
@tab hour
@tab @nicode{date-hour}
@item @nicode{~k}
@tab no skip
@tab hour, blank padded
@tab @nicode{date-hour}
@item @nicode{~m}
@tab @nicode{char-numeric?}
@tab month
@tab @nicode{date-month}
@item @nicode{~M}
@tab @nicode{char-numeric?}
@tab minute
@tab @nicode{date-minute}
@item @nicode{~S}
@tab @nicode{char-numeric?}
@tab second
@tab @nicode{date-second}
@item @nicode{~y}
@tab no skip
@tab 2-digit year
@tab @nicode{date-year} within 50 years
@item @nicode{~Y}
@tab @nicode{char-numeric?}
@tab year
@tab @nicode{date-year}
@item @nicode{~z}
@tab no skip
@tab time zone
@tab date-zone-offset
@end multitable
Notice that the weekday matching forms don't affect the date object
returned, instead the weekday will be derived from the day, month and
year.
Currently Guile doesn't implement any localizations for the above,
month and weekday names are always expected in English. This may
change in the future.
@end defun
@node SRFI-26
@subsection SRFI-26 - specializing parameters
@cindex SRFI-26
@cindex parameter specialize
@cindex argument specialize
@cindex specialize parameter
This SRFI provides a syntax for conveniently specializing selected
parameters of a function. It can be used with,
@example
(use-modules (srfi srfi-26))
@end example
@deffn {library syntax} cut slot @dots{}
@deffnx {library syntax} cute slot @dots{}
Return a new procedure which will make a call (@var{slot} @dots{}) but
with selected parameters specialized to given expressions.
An example will illustrate the idea. The following is a
specialization of @code{write}, sending output to
@code{my-output-port},
@example
(cut write <> my-output-port)
@result{}
(lambda (obj) (write obj my-output-port))
@end example
The special symbol @code{<>} indicates a slot to be filled by an
argument to the new procedure. @code{my-output-port} on the other
hand is an expression to be evaluated and passed, ie.@: it specializes
the behaviour of @code{write}.
@table @nicode
@item <>
A slot to be filled by an argument from the created procedure.
Arguments are assigned to @code{<>} slots in the order they appear in
the @code{cut} form, there's no way to re-arrange arguments.
The first argument to @code{cut} is usually a procedure (or expression
giving a procedure), but @code{<>} is allowed there too. For example,
@example
(cut <> 1 2 3)
@result{}
(lambda (proc) (proc 1 2 3))
@end example
@item <...>
A slot to be filled by all remaining arguments from the new procedure.
This can only occur at the end of a @code{cut} form.
For example, a procedure taking a variable number of arguments like
@code{max} but in addition enforcing a lower bound,
@example
(define my-lower-bound 123)
(cut max my-lower-bound <...>)
@result{}
(lambda arglist (apply max my-lower-bound arglist))
@end example
@end table
For @code{cut} the specializing expressions are evaluated each time
the new procedure is called. For @code{cute} they're evaluated just
once, when the new procedure is created. The name @code{cute} stands
for ``@code{cut} with evaluated arguments''. In all cases the
evaluations take place in an unspecified order.
The following illustrates the difference between @code{cut} and
@code{cute},
@example
(cut format <> "the time is ~s" (current-time))
@result{}
(lambda (port) (format port "the time is ~s" (current-time)))
(cute format <> "the time is ~s" (current-time))
@result{}
(let ((val (current-time)))
(lambda (port) (format port "the time is ~s" val))
@end example
(There's no provision for a mixture of @code{cut} and @code{cute}
where some expressions would be evaluated every time but others
evaluated only once.)
@code{cut} is really just a shorthand for the sort of @code{lambda}
forms shown in the above examples. But notice @code{cut} avoids the
need to name unspecialized parameters, and is more compact. Use in
functional programming style or just with @code{map}, @code{for-each}
or similar is typical.
@example
(map (cut * 2 <>) '(1 2 3 4))
(for-each (cut write <> my-port) my-list)
@end example
@end deffn
@node SRFI-31
@subsection SRFI-31 - A special form `rec' for recursive evaluation
@cindex SRFI-31
@cindex recursive expression
@findex rec
SRFI-31 defines a special form that can be used to create
self-referential expressions more conveniently. The syntax is as
follows:
@example
@group
<rec expression> --> (rec <variable> <expression>)
<rec expression> --> (rec (<variable>+) <body>)
@end group
@end example
The first syntax can be used to create self-referential expressions,
for example:
@lisp
guile> (define tmp (rec ones (cons 1 (delay ones))))
@end lisp
The second syntax can be used to create anonymous recursive functions:
@lisp
guile> (define tmp (rec (display-n item n)
(if (positive? n)
(begin (display n) (display-n (- n 1))))))
guile> (tmp 42 3)
424242
guile>
@end lisp
@node SRFI-39
@subsection SRFI-39 - Parameters
@cindex SRFI-39
@cindex parameter object
@tindex Parameter
This SRFI provides parameter objects, which implement dynamically
bound locations for values. The functions below are available from
@example
(use-modules (srfi srfi-39))
@end example
A parameter object is a procedure. Called with no arguments it
returns its value, called with one argument it sets the value.
@example
(define my-param (make-parameter 123))
(my-param) @result{} 123
(my-param 456)
(my-param) @result{} 456
@end example
The @code{parameterize} special form establishes new locations for
parameters, those new locations having effect within the dynamic scope
of the @code{parameterize} body. Leaving restores the previous
locations, or re-entering through a saved continuation will again use
the new locations.
@example
(parameterize ((my-param 789))
(my-param) @result{} 789
)
(my-param) @result{} 456
@end example
Parameters are like dynamically bound variables in other Lisp dialets.
They allow an application to establish parameter settings (as the name
suggests) just for the execution of a particular bit of code,
restoring when done. Examples of such parameters might be
case-sensitivity for a search, or a prompt for user input.
Global variables are not as good as parameter objects for this sort of
thing. Changes to them are visible to all threads, but in Guile
parameter object locations are per-thread, thereby truely limiting the
effect of @code{parameterize} to just its dynamic execution.
Passing arguments to functions is thread-safe, but that soon becomes
tedious when there's more than a few or when they need to pass down
through several layers of calls before reaching the point they should
affect. And introducing a new setting to existing code is often
easier with a parameter object than adding arguments.
@sp 1
@defun make-parameter init [converter]
Return a new parameter object, with initial value @var{init}.
A parameter object is a procedure. When called @code{(param)} it
returns its value, or a call @code{(param val)} sets its value. For
example,
@example
(define my-param (make-parameter 123))
(my-param) @result{} 123
(my-param 456)
(my-param) @result{} 456
@end example
If a @var{converter} is given, then a call @code{(@var{converter}
val)} is made for each value set, its return is the value stored.
Such a call is made for the @var{init} initial value too.
A @var{converter} allows values to be validated, or put into a
canonical form. For example,
@example
(define my-param (make-parameter 123
(lambda (val)
(if (not (number? val))
(error "must be a number"))
(inexact->exact val))))
(my-param 0.75)
(my-param) @result{} 3/4
@end example
@end defun
@deffn {library syntax} parameterize ((param value) @dots{}) body @dots{}
Establish a new dynamic scope with the given @var{param}s bound to new
locations and set to the given @var{value}s. @var{body} is evaluated
in that environment, the result is the return from the last form in
@var{body}.
Each @var{param} is an expression which is evaluated to get the
parameter object. Often this will just be the name of a variable
holding the object, but it can be anything that evaluates to a
parameter.
The @var{param} expressions and @var{value} expressions are all
evaluated before establishing the new dynamic bindings, and they're
evaluated in an unspecified order.
For example,
@example
(define prompt (make-parameter "Type something: "))
(define (get-input)
(display (prompt))
...)
(parameterize ((prompt "Type a number: "))
(get-input)
...)
@end example
@end deffn
@deffn {Parameter object} current-input-port [new-port]
@deffnx {Parameter object} current-output-port [new-port]
@deffnx {Parameter object} current-error-port [new-port]
This SRFI extends the core @code{current-input-port} and
@code{current-output-port}, making them parameter objects. The
Guile-specific @code{current-error-port} is extended too, for
consistency. (@pxref{Default Ports}.)
This is an upwardly compatible extension, a plain call like
@code{(current-input-port)} still returns the current input port, and
@code{set-current-input-port} can still be used. But the port can now
also be set with @code{(current-input-port my-port)} and bound
dynamically with @code{parameterize}.
@end deffn
@defun with-parameters* param-list value-list thunk
Establish a new dynamic scope, as per @code{parameterize} above,
taking parameters from @var{param-list} and corresponding values from
@var{values-list}. A call @code{(@var{thunk})} is made in the new
scope and the result from that @var{thunk} is the return from
@code{with-parameters*}.
This function is a Guile-specific addition to the SRFI, it's similar
to the core @code{with-fluids*} (@pxref{Fluids}).
@end defun
@sp 1
Parameter objects are implemented using fluids (@pxref{Fluids}), so
each dynamic root has it's own parameter locations. That includes the
separate locations when outside any @code{parameterize} form. When a
parameter is created it gets a separate initial location in each
dynamic root, all initialized to the given @var{init} value.
As alluded to above, because each thread is a separate dynamic root,
each thread has it's own locations behind parameter objects, and
changes in one thread are not visible to any other. When a new
dynamic root or thread is created, the values of parameters in the
originating context are copied, into new locations.
SRFI-39 doesn't specify the interaction between parameter objects and
threads, so the threading behaviour described here should be regarded
as Guile-specific.
@c srfi-modules.texi ends here
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
|