srfi-modules.texi 201 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580
  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Guile Reference Manual.
  3. @c Copyright (C) 1996, 1997, 2000-2004, 2006, 2007-2014, 2017, 2018
  4. @c Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node SRFI Support
  7. @section SRFI Support Modules
  8. @cindex SRFI
  9. SRFI is an acronym for Scheme Request For Implementation. The SRFI
  10. documents define a lot of syntactic and procedure extensions to standard
  11. Scheme as defined in R5RS.
  12. Guile has support for a number of SRFIs. This chapter gives an overview
  13. over the available SRFIs and some usage hints. For complete
  14. documentation, design rationales and further examples, we advise you to
  15. get the relevant SRFI documents from the SRFI home page
  16. @url{http://srfi.schemers.org/}.
  17. @menu
  18. * About SRFI Usage:: What to know about Guile's SRFI support.
  19. * SRFI-0:: cond-expand
  20. * SRFI-1:: List library.
  21. * SRFI-2:: and-let*.
  22. * SRFI-4:: Homogeneous numeric vector datatypes.
  23. * SRFI-6:: Basic String Ports.
  24. * SRFI-8:: receive.
  25. * SRFI-9:: define-record-type.
  26. * SRFI-10:: Hash-Comma Reader Extension.
  27. * SRFI-11:: let-values and let*-values.
  28. * SRFI-13:: String library.
  29. * SRFI-14:: Character-set library.
  30. * SRFI-16:: case-lambda
  31. * SRFI-17:: Generalized set!
  32. * SRFI-18:: Multithreading support
  33. * SRFI-19:: Time/Date library.
  34. * SRFI-23:: Error reporting
  35. * SRFI-26:: Specializing parameters
  36. * SRFI-27:: Sources of Random Bits
  37. * SRFI-28:: Basic format strings.
  38. * SRFI-30:: Nested multi-line block comments
  39. * SRFI-31:: A special form `rec' for recursive evaluation
  40. * SRFI-34:: Exception handling.
  41. * SRFI-35:: Conditions.
  42. * SRFI-37:: args-fold program argument processor
  43. * SRFI-38:: External Representation for Data With Shared Structure
  44. * SRFI-39:: Parameter objects
  45. * SRFI-41:: Streams.
  46. * SRFI-42:: Eager comprehensions
  47. * SRFI-43:: Vector Library.
  48. * SRFI-45:: Primitives for expressing iterative lazy algorithms
  49. * SRFI-46:: Basic syntax-rules Extensions.
  50. * SRFI-55:: Requiring Features.
  51. * SRFI-60:: Integers as bits.
  52. * SRFI-61:: A more general `cond' clause
  53. * SRFI-62:: S-expression comments.
  54. * SRFI-64:: A Scheme API for test suites.
  55. * SRFI-67:: Compare procedures
  56. * SRFI-69:: Basic hash tables.
  57. * SRFI-71:: Extended let-syntax for multiple values.
  58. * SRFI-87:: => in case clauses.
  59. * SRFI-88:: Keyword objects.
  60. * SRFI-98:: Accessing environment variables.
  61. * SRFI-105:: Curly-infix expressions.
  62. * SRFI-111:: Boxes.
  63. @end menu
  64. @node About SRFI Usage
  65. @subsection About SRFI Usage
  66. @c FIXME::martin: Review me!
  67. SRFI support in Guile is currently implemented partly in the core
  68. library, and partly as add-on modules. That means that some SRFIs are
  69. automatically available when the interpreter is started, whereas the
  70. other SRFIs require you to use the appropriate support module
  71. explicitly.
  72. There are several reasons for this inconsistency. First, the feature
  73. checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
  74. available immediately, because it must be there when the user wants to
  75. check for the Scheme implementation, that is, before she can know that
  76. it is safe to use @code{use-modules} to load SRFI support modules. The
  77. second reason is that some features defined in SRFIs had been
  78. implemented in Guile before the developers started to add SRFI
  79. implementations as modules (for example SRFI-13 (@pxref{SRFI-13})). In
  80. the future, it is possible that SRFIs in the core library might be
  81. factored out into separate modules, requiring explicit module loading
  82. when they are needed. So you should be prepared to have to use
  83. @code{use-modules} someday in the future to access SRFI-13 bindings. If
  84. you want, you can do that already. We have included the module
  85. @code{(srfi srfi-13)} in the distribution, which currently does nothing,
  86. but ensures that you can write future-safe code.
  87. Generally, support for a specific SRFI is made available by using
  88. modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
  89. number of the SRFI needed. Another possibility is to use the command
  90. line option @code{--use-srfi}, which will load the necessary modules
  91. automatically (@pxref{Invoking Guile}).
  92. @node SRFI-0
  93. @subsection SRFI-0 - cond-expand
  94. @cindex SRFI-0
  95. This SRFI lets a portable Scheme program test for the presence of
  96. certain features, and adapt itself by using different blocks of code,
  97. or fail if the necessary features are not available. There's no
  98. module to load, this is in the Guile core.
  99. A program designed only for Guile will generally not need this
  100. mechanism, such a program can of course directly use the various
  101. documented parts of Guile.
  102. @deffn syntax cond-expand (feature body@dots{}) @dots{}
  103. Expand to the @var{body} of the first clause whose @var{feature}
  104. specification is satisfied. It is an error if no @var{feature} is
  105. satisfied.
  106. Features are symbols such as @code{srfi-1}, and a feature
  107. specification can use @code{and}, @code{or} and @code{not} forms to
  108. test combinations. The last clause can be an @code{else}, to be used
  109. if no other passes.
  110. For example, define a private version of @code{alist-cons} if SRFI-1
  111. is not available.
  112. @example
  113. (cond-expand (srfi-1
  114. )
  115. (else
  116. (define (alist-cons key val alist)
  117. (cons (cons key val) alist))))
  118. @end example
  119. Or demand a certain set of SRFIs (list operations, string ports,
  120. @code{receive} and string operations), failing if they're not
  121. available.
  122. @example
  123. (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
  124. ))
  125. @end example
  126. @end deffn
  127. @noindent
  128. The Guile core has the following features,
  129. @example
  130. guile
  131. guile-2 ;; starting from Guile 2.x
  132. guile-2.2 ;; starting from Guile 2.2
  133. r5rs
  134. srfi-0
  135. srfi-4
  136. srfi-6
  137. srfi-13
  138. srfi-14
  139. srfi-16
  140. srfi-23
  141. srfi-30
  142. srfi-39
  143. srfi-46
  144. srfi-55
  145. srfi-61
  146. srfi-62
  147. srfi-87
  148. srfi-105
  149. @end example
  150. Other SRFI feature symbols are defined once their code has been loaded
  151. with @code{use-modules}, since only then are their bindings available.
  152. The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
  153. a good way to load SRFIs to satisfy @code{cond-expand} when running a
  154. portable program.
  155. Testing the @code{guile} feature allows a program to adapt itself to
  156. the Guile module system, but still run on other Scheme systems. For
  157. example the following demands SRFI-8 (@code{receive}), but also knows
  158. how to load it with the Guile mechanism.
  159. @example
  160. (cond-expand (srfi-8
  161. )
  162. (guile
  163. (use-modules (srfi srfi-8))))
  164. @end example
  165. @cindex @code{guile-2} SRFI-0 feature
  166. @cindex portability between 2.0 and older versions
  167. Likewise, testing the @code{guile-2} feature allows code to be portable
  168. between Guile 2.@var{x} and previous versions of Guile. For instance, it
  169. makes it possible to write code that accounts for Guile 2.@var{x}'s compiler,
  170. yet be correctly interpreted on 1.8 and earlier versions:
  171. @example
  172. (cond-expand (guile-2 (eval-when (compile)
  173. ;; This must be evaluated at compile time.
  174. (fluid-set! current-reader my-reader)))
  175. (guile
  176. ;; Earlier versions of Guile do not have a
  177. ;; separate compilation phase.
  178. (fluid-set! current-reader my-reader)))
  179. @end example
  180. It should be noted that @code{cond-expand} is separate from the
  181. @code{*features*} mechanism (@pxref{Feature Tracking}), feature
  182. symbols in one are unrelated to those in the other.
  183. @node SRFI-1
  184. @subsection SRFI-1 - List library
  185. @cindex SRFI-1
  186. @cindex list
  187. @c FIXME::martin: Review me!
  188. The list library defined in SRFI-1 contains a lot of useful list
  189. processing procedures for construction, examining, destructuring and
  190. manipulating lists and pairs.
  191. Since SRFI-1 also defines some procedures which are already contained
  192. in R5RS and thus are supported by the Guile core library, some list
  193. and pair procedures which appear in the SRFI-1 document may not appear
  194. in this section. So when looking for a particular list/pair
  195. processing procedure, you should also have a look at the sections
  196. @ref{Lists} and @ref{Pairs}.
  197. @menu
  198. * SRFI-1 Constructors:: Constructing new lists.
  199. * SRFI-1 Predicates:: Testing list for specific properties.
  200. * SRFI-1 Selectors:: Selecting elements from lists.
  201. * SRFI-1 Length Append etc:: Length calculation and list appending.
  202. * SRFI-1 Fold and Map:: Higher-order list processing.
  203. * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
  204. * SRFI-1 Searching:: Search for elements.
  205. * SRFI-1 Deleting:: Delete elements from lists.
  206. * SRFI-1 Association Lists:: Handle association lists.
  207. * SRFI-1 Set Operations:: Use lists for representing sets.
  208. @end menu
  209. @node SRFI-1 Constructors
  210. @subsubsection Constructors
  211. @cindex list constructor
  212. @c FIXME::martin: Review me!
  213. New lists can be constructed by calling one of the following
  214. procedures.
  215. @deffn {Scheme Procedure} xcons d a
  216. Like @code{cons}, but with interchanged arguments. Useful mostly when
  217. passed to higher-order procedures.
  218. @end deffn
  219. @deffn {Scheme Procedure} list-tabulate n init-proc
  220. Return an @var{n}-element list, where each list element is produced by
  221. applying the procedure @var{init-proc} to the corresponding list
  222. index. The order in which @var{init-proc} is applied to the indices
  223. is not specified.
  224. @end deffn
  225. @deffn {Scheme Procedure} list-copy lst
  226. Return a new list containing the elements of the list @var{lst}.
  227. This function differs from the core @code{list-copy} (@pxref{List
  228. Constructors}) in accepting improper lists too. And if @var{lst} is
  229. not a pair at all then it's treated as the final tail of an improper
  230. list and simply returned.
  231. @end deffn
  232. @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
  233. Return a circular list containing the given arguments @var{elt1}
  234. @var{elt2} @dots{}.
  235. @end deffn
  236. @deffn {Scheme Procedure} iota count [start step]
  237. Return a list containing @var{count} numbers, starting from
  238. @var{start} and adding @var{step} each time. The default @var{start}
  239. is 0, the default @var{step} is 1. For example,
  240. @example
  241. (iota 6) @result{} (0 1 2 3 4 5)
  242. (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
  243. @end example
  244. This function takes its name from the corresponding primitive in the
  245. APL language.
  246. @end deffn
  247. @node SRFI-1 Predicates
  248. @subsubsection Predicates
  249. @cindex list predicate
  250. @c FIXME::martin: Review me!
  251. The procedures in this section test specific properties of lists.
  252. @deffn {Scheme Procedure} proper-list? obj
  253. Return @code{#t} if @var{obj} is a proper list, or @code{#f}
  254. otherwise. This is the same as the core @code{list?} (@pxref{List
  255. Predicates}).
  256. A proper list is a list which ends with the empty list @code{()} in
  257. the usual way. The empty list @code{()} itself is a proper list too.
  258. @example
  259. (proper-list? '(1 2 3)) @result{} #t
  260. (proper-list? '()) @result{} #t
  261. @end example
  262. @end deffn
  263. @deffn {Scheme Procedure} circular-list? obj
  264. Return @code{#t} if @var{obj} is a circular list, or @code{#f}
  265. otherwise.
  266. A circular list is a list where at some point the @code{cdr} refers
  267. back to a previous pair in the list (either the start or some later
  268. point), so that following the @code{cdr}s takes you around in a
  269. circle, with no end.
  270. @example
  271. (define x (list 1 2 3 4))
  272. (set-cdr! (last-pair x) (cddr x))
  273. x @result{} (1 2 3 4 3 4 3 4 ...)
  274. (circular-list? x) @result{} #t
  275. @end example
  276. @end deffn
  277. @deffn {Scheme Procedure} dotted-list? obj
  278. Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
  279. otherwise.
  280. A dotted list is a list where the @code{cdr} of the last pair is not
  281. the empty list @code{()}. Any non-pair @var{obj} is also considered a
  282. dotted list, with length zero.
  283. @example
  284. (dotted-list? '(1 2 . 3)) @result{} #t
  285. (dotted-list? 99) @result{} #t
  286. @end example
  287. @end deffn
  288. It will be noted that any Scheme object passes exactly one of the
  289. above three tests @code{proper-list?}, @code{circular-list?} and
  290. @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
  291. are either @code{proper-list?} or @code{dotted-list?}, and infinite
  292. lists are @code{circular-list?}.
  293. @sp 1
  294. @deffn {Scheme Procedure} null-list? lst
  295. Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
  296. otherwise. If something else than a proper or circular list is passed
  297. as @var{lst}, an error is signalled. This procedure is recommended
  298. for checking for the end of a list in contexts where dotted lists are
  299. not allowed.
  300. @end deffn
  301. @deffn {Scheme Procedure} not-pair? obj
  302. Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
  303. This is shorthand notation @code{(not (pair? @var{obj}))} and is
  304. supposed to be used for end-of-list checking in contexts where dotted
  305. lists are allowed.
  306. @end deffn
  307. @deffn {Scheme Procedure} list= elt= list1 @dots{}
  308. Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
  309. List equality is determined by testing whether all lists have the same
  310. length and the corresponding elements are equal in the sense of the
  311. equality predicate @var{elt=}. If no or only one list is given,
  312. @code{#t} is returned.
  313. @end deffn
  314. @node SRFI-1 Selectors
  315. @subsubsection Selectors
  316. @cindex list selector
  317. @c FIXME::martin: Review me!
  318. @deffn {Scheme Procedure} first pair
  319. @deffnx {Scheme Procedure} second pair
  320. @deffnx {Scheme Procedure} third pair
  321. @deffnx {Scheme Procedure} fourth pair
  322. @deffnx {Scheme Procedure} fifth pair
  323. @deffnx {Scheme Procedure} sixth pair
  324. @deffnx {Scheme Procedure} seventh pair
  325. @deffnx {Scheme Procedure} eighth pair
  326. @deffnx {Scheme Procedure} ninth pair
  327. @deffnx {Scheme Procedure} tenth pair
  328. These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
  329. @end deffn
  330. @deffn {Scheme Procedure} car+cdr pair
  331. Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
  332. @end deffn
  333. @deffn {Scheme Procedure} take lst i
  334. @deffnx {Scheme Procedure} take! lst i
  335. Return a list containing the first @var{i} elements of @var{lst}.
  336. @code{take!} may modify the structure of the argument list @var{lst}
  337. in order to produce the result.
  338. @end deffn
  339. @deffn {Scheme Procedure} drop lst i
  340. Return a list containing all but the first @var{i} elements of
  341. @var{lst}.
  342. @end deffn
  343. @deffn {Scheme Procedure} take-right lst i
  344. Return a list containing the @var{i} last elements of @var{lst}.
  345. The return shares a common tail with @var{lst}.
  346. @end deffn
  347. @deffn {Scheme Procedure} drop-right lst i
  348. @deffnx {Scheme Procedure} drop-right! lst i
  349. Return a list containing all but the @var{i} last elements of
  350. @var{lst}.
  351. @code{drop-right} always returns a new list, even when @var{i} is
  352. zero. @code{drop-right!} may modify the structure of the argument
  353. list @var{lst} in order to produce the result.
  354. @end deffn
  355. @deffn {Scheme Procedure} split-at lst i
  356. @deffnx {Scheme Procedure} split-at! lst i
  357. Return two values, a list containing the first @var{i} elements of the
  358. list @var{lst} and a list containing the remaining elements.
  359. @code{split-at!} may modify the structure of the argument list
  360. @var{lst} in order to produce the result.
  361. @end deffn
  362. @deffn {Scheme Procedure} last lst
  363. Return the last element of the non-empty, finite list @var{lst}.
  364. @end deffn
  365. @node SRFI-1 Length Append etc
  366. @subsubsection Length, Append, Concatenate, etc.
  367. @c FIXME::martin: Review me!
  368. @deffn {Scheme Procedure} length+ lst
  369. Return the length of the argument list @var{lst}. When @var{lst} is a
  370. circular list, @code{#f} is returned.
  371. @end deffn
  372. @deffn {Scheme Procedure} concatenate list-of-lists
  373. @deffnx {Scheme Procedure} concatenate! list-of-lists
  374. Construct a list by appending all lists in @var{list-of-lists}.
  375. @code{concatenate!} may modify the structure of the given lists in
  376. order to produce the result.
  377. @code{concatenate} is the same as @code{(apply append
  378. @var{list-of-lists})}. It exists because some Scheme implementations
  379. have a limit on the number of arguments a function takes, which the
  380. @code{apply} might exceed. In Guile there is no such limit.
  381. @end deffn
  382. @deffn {Scheme Procedure} append-reverse rev-head tail
  383. @deffnx {Scheme Procedure} append-reverse! rev-head tail
  384. Reverse @var{rev-head}, append @var{tail} to it, and return the
  385. result. This is equivalent to @code{(append (reverse @var{rev-head})
  386. @var{tail})}, but its implementation is more efficient.
  387. @example
  388. (append-reverse '(1 2 3) '(4 5 6)) @result{} (3 2 1 4 5 6)
  389. @end example
  390. @code{append-reverse!} may modify @var{rev-head} in order to produce
  391. the result.
  392. @end deffn
  393. @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
  394. Return a list as long as the shortest of the argument lists, where
  395. each element is a list. The first list contains the first elements of
  396. the argument lists, the second list contains the second elements, and
  397. so on.
  398. @end deffn
  399. @deffn {Scheme Procedure} unzip1 lst
  400. @deffnx {Scheme Procedure} unzip2 lst
  401. @deffnx {Scheme Procedure} unzip3 lst
  402. @deffnx {Scheme Procedure} unzip4 lst
  403. @deffnx {Scheme Procedure} unzip5 lst
  404. @code{unzip1} takes a list of lists, and returns a list containing the
  405. first elements of each list, @code{unzip2} returns two lists, the
  406. first containing the first elements of each lists and the second
  407. containing the second elements of each lists, and so on.
  408. @end deffn
  409. @deffn {Scheme Procedure} count pred lst1 lst2 @dots{}
  410. Return a count of the number of times @var{pred} returns true when
  411. called on elements from the given lists.
  412. @var{pred} is called with @var{N} parameters @code{(@var{pred}
  413. @var{elem1} @dots{} @var{elemN} )}, each element being from the
  414. corresponding list. The first call is with the first element of each
  415. list, the second with the second element from each, and so on.
  416. Counting stops when the end of the shortest list is reached. At least
  417. one list must be non-circular.
  418. @end deffn
  419. @node SRFI-1 Fold and Map
  420. @subsubsection Fold, Unfold & Map
  421. @cindex list fold
  422. @cindex list map
  423. @c FIXME::martin: Review me!
  424. @deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{}
  425. @deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{}
  426. Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to
  427. build a result, and return that result.
  428. Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2}
  429. @dots{} @var{previous})}, where @var{elem1} is from @var{lst1},
  430. @var{elem2} is from @var{lst2}, and so on. @var{previous} is the return
  431. from the previous call to @var{proc}, or the given @var{init} for the
  432. first call. If any list is empty, just @var{init} is returned.
  433. @code{fold} works through the list elements from first to last. The
  434. following shows a list reversal and the calls it makes,
  435. @example
  436. (fold cons '() '(1 2 3))
  437. (cons 1 '())
  438. (cons 2 '(1))
  439. (cons 3 '(2 1)
  440. @result{} (3 2 1)
  441. @end example
  442. @code{fold-right} works through the list elements from last to first,
  443. ie.@: from the right. So for example the following finds the longest
  444. string, and the last among equal longest,
  445. @example
  446. (fold-right (lambda (str prev)
  447. (if (> (string-length str) (string-length prev))
  448. str
  449. prev))
  450. ""
  451. '("x" "abc" "xyz" "jk"))
  452. @result{} "xyz"
  453. @end example
  454. If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold}
  455. stops when the end of the shortest is reached; @code{fold-right}
  456. commences at the last element of the shortest. Ie.@: elements past the
  457. length of the shortest are ignored in the other @var{lst}s. At least
  458. one @var{lst} must be non-circular.
  459. @code{fold} should be preferred over @code{fold-right} if the order of
  460. processing doesn't matter, or can be arranged either way, since
  461. @code{fold} is a little more efficient.
  462. The way @code{fold} builds a result from iterating is quite general,
  463. it can do more than other iterations like say @code{map} or
  464. @code{filter}. The following for example removes adjacent duplicate
  465. elements from a list,
  466. @example
  467. (define (delete-adjacent-duplicates lst)
  468. (fold-right (lambda (elem ret)
  469. (if (equal? elem (first ret))
  470. ret
  471. (cons elem ret)))
  472. (list (last lst))
  473. lst))
  474. (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
  475. @result{} (1 2 3 4 5)
  476. @end example
  477. Clearly the same sort of thing can be done with a @code{for-each} and
  478. a variable in which to build the result, but a self-contained
  479. @var{proc} can be re-used in multiple contexts, where a
  480. @code{for-each} would have to be written out each time.
  481. @end deffn
  482. @deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{}
  483. @deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{}
  484. The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
  485. the pairs of the lists instead of the list elements.
  486. @end deffn
  487. @deffn {Scheme Procedure} reduce proc default lst
  488. @deffnx {Scheme Procedure} reduce-right proc default lst
  489. @code{reduce} is a variant of @code{fold}, where the first call to
  490. @var{proc} is on two elements from @var{lst}, rather than one element
  491. and a given initial value.
  492. If @var{lst} is empty, @code{reduce} returns @var{default} (this is
  493. the only use for @var{default}). If @var{lst} has just one element
  494. then that's the return value. Otherwise @var{proc} is called on the
  495. elements of @var{lst}.
  496. Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
  497. where @var{elem} is from @var{lst} (the second and subsequent elements
  498. of @var{lst}), and @var{previous} is the return from the previous call
  499. to @var{proc}. The first element of @var{lst} is the @var{previous}
  500. for the first call to @var{proc}.
  501. For example, the following adds a list of numbers, the calls made to
  502. @code{+} are shown. (Of course @code{+} accepts multiple arguments
  503. and can add a list directly, with @code{apply}.)
  504. @example
  505. (reduce + 0 '(5 6 7)) @result{} 18
  506. (+ 6 5) @result{} 11
  507. (+ 7 11) @result{} 18
  508. @end example
  509. @code{reduce} can be used instead of @code{fold} where the @var{init}
  510. value is an ``identity'', meaning a value which under @var{proc}
  511. doesn't change the result, in this case 0 is an identity since
  512. @code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
  513. @code{reduce-right} is a similar variation on @code{fold-right},
  514. working from the end (ie.@: the right) of @var{lst}. The last element
  515. of @var{lst} is the @var{previous} for the first call to @var{proc},
  516. and the @var{elem} values go from the second last.
  517. @code{reduce} should be preferred over @code{reduce-right} if the
  518. order of processing doesn't matter, or can be arranged either way,
  519. since @code{reduce} is a little more efficient.
  520. @end deffn
  521. @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
  522. @code{unfold} is defined as follows:
  523. @lisp
  524. (unfold p f g seed) =
  525. (if (p seed) (tail-gen seed)
  526. (cons (f seed)
  527. (unfold p f g (g seed))))
  528. @end lisp
  529. @table @var
  530. @item p
  531. Determines when to stop unfolding.
  532. @item f
  533. Maps each seed value to the corresponding list element.
  534. @item g
  535. Maps each seed value to next seed value.
  536. @item seed
  537. The state value for the unfold.
  538. @item tail-gen
  539. Creates the tail of the list; defaults to @code{(lambda (x) '())}.
  540. @end table
  541. @var{g} produces a series of seed values, which are mapped to list
  542. elements by @var{f}. These elements are put into a list in
  543. left-to-right order, and @var{p} tells when to stop unfolding.
  544. @end deffn
  545. @deffn {Scheme Procedure} unfold-right p f g seed [tail]
  546. Construct a list with the following loop.
  547. @lisp
  548. (let lp ((seed seed) (lis tail))
  549. (if (p seed) lis
  550. (lp (g seed)
  551. (cons (f seed) lis))))
  552. @end lisp
  553. @table @var
  554. @item p
  555. Determines when to stop unfolding.
  556. @item f
  557. Maps each seed value to the corresponding list element.
  558. @item g
  559. Maps each seed value to next seed value.
  560. @item seed
  561. The state value for the unfold.
  562. @item tail
  563. The tail of the list; defaults to @code{'()}.
  564. @end table
  565. @end deffn
  566. @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
  567. Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
  568. return a list containing the results of the procedure applications.
  569. This procedure is extended with respect to R5RS, because the argument
  570. lists may have different lengths. The result list will have the same
  571. length as the shortest argument lists. The order in which @var{f}
  572. will be applied to the list element(s) is not specified.
  573. @end deffn
  574. @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
  575. Apply the procedure @var{f} to each pair of corresponding elements of
  576. the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
  577. specified. This procedure is extended with respect to R5RS, because
  578. the argument lists may have different lengths. The shortest argument
  579. list determines the number of times @var{f} is called. @var{f} will
  580. be applied to the list elements in left-to-right order.
  581. @end deffn
  582. @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
  583. @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
  584. Equivalent to
  585. @lisp
  586. (apply append (map f clist1 clist2 ...))
  587. @end lisp
  588. and
  589. @lisp
  590. (apply append! (map f clist1 clist2 ...))
  591. @end lisp
  592. Map @var{f} over the elements of the lists, just as in the @code{map}
  593. function. However, the results of the applications are appended
  594. together to make the final result. @code{append-map} uses
  595. @code{append} to append the results together; @code{append-map!} uses
  596. @code{append!}.
  597. The dynamic order in which the various applications of @var{f} are
  598. made is not specified.
  599. @end deffn
  600. @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
  601. Linear-update variant of @code{map} -- @code{map!} is allowed, but not
  602. required, to alter the cons cells of @var{lst1} to construct the
  603. result list.
  604. The dynamic order in which the various applications of @var{f} are
  605. made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
  606. @dots{} must have at least as many elements as @var{lst1}.
  607. @end deffn
  608. @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
  609. Like @code{for-each}, but applies the procedure @var{f} to the pairs
  610. from which the argument lists are constructed, instead of the list
  611. elements. The return value is not specified.
  612. @end deffn
  613. @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
  614. Like @code{map}, but only results from the applications of @var{f}
  615. which are true are saved in the result list.
  616. @end deffn
  617. @node SRFI-1 Filtering and Partitioning
  618. @subsubsection Filtering and Partitioning
  619. @cindex list filter
  620. @cindex list partition
  621. @c FIXME::martin: Review me!
  622. Filtering means to collect all elements from a list which satisfy a
  623. specific condition. Partitioning a list means to make two groups of
  624. list elements, one which contains the elements satisfying a condition,
  625. and the other for the elements which don't.
  626. The @code{filter} and @code{filter!} functions are implemented in the
  627. Guile core, @xref{List Modification}.
  628. @deffn {Scheme Procedure} partition pred lst
  629. @deffnx {Scheme Procedure} partition! pred lst
  630. Split @var{lst} into those elements which do and don't satisfy the
  631. predicate @var{pred}.
  632. The return is two values (@pxref{Multiple Values}), the first being a
  633. list of all elements from @var{lst} which satisfy @var{pred}, the
  634. second a list of those which do not.
  635. The elements in the result lists are in the same order as in @var{lst}
  636. but the order in which the calls @code{(@var{pred} elem)} are made on
  637. the list elements is unspecified.
  638. @code{partition} does not change @var{lst}, but one of the returned
  639. lists may share a tail with it. @code{partition!} may modify
  640. @var{lst} to construct its return.
  641. @end deffn
  642. @deffn {Scheme Procedure} remove pred lst
  643. @deffnx {Scheme Procedure} remove! pred lst
  644. Return a list containing all elements from @var{lst} which do not
  645. satisfy the predicate @var{pred}. The elements in the result list
  646. have the same order as in @var{lst}. The order in which @var{pred} is
  647. applied to the list elements is not specified.
  648. @code{remove!} is allowed, but not required to modify the structure of
  649. the input list.
  650. @end deffn
  651. @node SRFI-1 Searching
  652. @subsubsection Searching
  653. @cindex list search
  654. @c FIXME::martin: Review me!
  655. The procedures for searching elements in lists either accept a
  656. predicate or a comparison object for determining which elements are to
  657. be searched.
  658. @deffn {Scheme Procedure} find pred lst
  659. Return the first element of @var{lst} which satisfies the predicate
  660. @var{pred} and @code{#f} if no such element is found.
  661. @end deffn
  662. @deffn {Scheme Procedure} find-tail pred lst
  663. Return the first pair of @var{lst} whose @sc{car} satisfies the
  664. predicate @var{pred} and @code{#f} if no such element is found.
  665. @end deffn
  666. @deffn {Scheme Procedure} take-while pred lst
  667. @deffnx {Scheme Procedure} take-while! pred lst
  668. Return the longest initial prefix of @var{lst} whose elements all
  669. satisfy the predicate @var{pred}.
  670. @code{take-while!} is allowed, but not required to modify the input
  671. list while producing the result.
  672. @end deffn
  673. @deffn {Scheme Procedure} drop-while pred lst
  674. Drop the longest initial prefix of @var{lst} whose elements all
  675. satisfy the predicate @var{pred}.
  676. @end deffn
  677. @deffn {Scheme Procedure} span pred lst
  678. @deffnx {Scheme Procedure} span! pred lst
  679. @deffnx {Scheme Procedure} break pred lst
  680. @deffnx {Scheme Procedure} break! pred lst
  681. @code{span} splits the list @var{lst} into the longest initial prefix
  682. whose elements all satisfy the predicate @var{pred}, and the remaining
  683. tail. @code{break} inverts the sense of the predicate.
  684. @code{span!} and @code{break!} are allowed, but not required to modify
  685. the structure of the input list @var{lst} in order to produce the
  686. result.
  687. Note that the name @code{break} conflicts with the @code{break}
  688. binding established by @code{while} (@pxref{while do}). Applications
  689. wanting to use @code{break} from within a @code{while} loop will need
  690. to make a new define under a different name.
  691. @end deffn
  692. @deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
  693. Test whether any set of elements from @var{lst1} @var{lst2} @dots{}
  694. satisfies @var{pred}. If so, the return value is the return value from
  695. the successful @var{pred} call, or if not, the return value is
  696. @code{#f}.
  697. If there are n list arguments, then @var{pred} must be a predicate
  698. taking n arguments. Each @var{pred} call is @code{(@var{pred}
  699. @var{elem1} @var{elem2} @dots{} )} taking an element from each
  700. @var{lst}. The calls are made successively for the first, second, etc.
  701. elements of the lists, stopping when @var{pred} returns non-@code{#f},
  702. or when the end of the shortest list is reached.
  703. The @var{pred} call on the last set of elements (i.e., when the end of
  704. the shortest list has been reached), if that point is reached, is a
  705. tail call.
  706. @end deffn
  707. @deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
  708. Test whether every set of elements from @var{lst1} @var{lst2} @dots{}
  709. satisfies @var{pred}. If so, the return value is the return from the
  710. final @var{pred} call, or if not, the return value is @code{#f}.
  711. If there are n list arguments, then @var{pred} must be a predicate
  712. taking n arguments. Each @var{pred} call is @code{(@var{pred}
  713. @var{elem1} @var{elem2 @dots{}})} taking an element from each
  714. @var{lst}. The calls are made successively for the first, second, etc.
  715. elements of the lists, stopping if @var{pred} returns @code{#f}, or when
  716. the end of any of the lists is reached.
  717. The @var{pred} call on the last set of elements (i.e., when the end of
  718. the shortest list has been reached) is a tail call.
  719. If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to
  720. @var{pred} are made, and the return value is @code{#t}.
  721. @end deffn
  722. @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
  723. Return the index of the first set of elements, one from each of
  724. @var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}.
  725. @var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}.
  726. Searching stops when the end of the shortest @var{lst} is reached.
  727. The return index starts from 0 for the first set of elements. If no
  728. set of elements pass, then the return value is @code{#f}.
  729. @example
  730. (list-index odd? '(2 4 6 9)) @result{} 3
  731. (list-index = '(1 2 3) '(3 1 2)) @result{} #f
  732. @end example
  733. @end deffn
  734. @deffn {Scheme Procedure} member x lst [=]
  735. Return the first sublist of @var{lst} whose @sc{car} is equal to
  736. @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
  737. Equality is determined by @code{equal?}, or by the equality predicate
  738. @var{=} if given. @var{=} is called @code{(= @var{x} elem)},
  739. ie.@: with the given @var{x} first, so for example to find the first
  740. element greater than 5,
  741. @example
  742. (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
  743. @end example
  744. This version of @code{member} extends the core @code{member}
  745. (@pxref{List Searching}) by accepting an equality predicate.
  746. @end deffn
  747. @node SRFI-1 Deleting
  748. @subsubsection Deleting
  749. @cindex list delete
  750. @deffn {Scheme Procedure} delete x lst [=]
  751. @deffnx {Scheme Procedure} delete! x lst [=]
  752. Return a list containing the elements of @var{lst} but with those
  753. equal to @var{x} deleted. The returned elements will be in the same
  754. order as they were in @var{lst}.
  755. Equality is determined by the @var{=} predicate, or @code{equal?} if
  756. not given. An equality call is made just once for each element, but
  757. the order in which the calls are made on the elements is unspecified.
  758. The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
  759. is first. This means for instance elements greater than 5 can be
  760. deleted with @code{(delete 5 lst <)}.
  761. @code{delete} does not modify @var{lst}, but the return might share a
  762. common tail with @var{lst}. @code{delete!} may modify the structure
  763. of @var{lst} to construct its return.
  764. These functions extend the core @code{delete} and @code{delete!}
  765. (@pxref{List Modification}) in accepting an equality predicate. See
  766. also @code{lset-difference} (@pxref{SRFI-1 Set Operations}) for
  767. deleting multiple elements from a list.
  768. @end deffn
  769. @deffn {Scheme Procedure} delete-duplicates lst [=]
  770. @deffnx {Scheme Procedure} delete-duplicates! lst [=]
  771. Return a list containing the elements of @var{lst} but without
  772. duplicates.
  773. When elements are equal, only the first in @var{lst} is retained.
  774. Equal elements can be anywhere in @var{lst}, they don't have to be
  775. adjacent. The returned list will have the retained elements in the
  776. same order as they were in @var{lst}.
  777. Equality is determined by the @var{=} predicate, or @code{equal?} if
  778. not given. Calls @code{(= x y)} are made with element @var{x} being
  779. before @var{y} in @var{lst}. A call is made at most once for each
  780. combination, but the sequence of the calls across the elements is
  781. unspecified.
  782. @code{delete-duplicates} does not modify @var{lst}, but the return
  783. might share a common tail with @var{lst}. @code{delete-duplicates!}
  784. may modify the structure of @var{lst} to construct its return.
  785. In the worst case, this is an @math{O(N^2)} algorithm because it must
  786. check each element against all those preceding it. For long lists it
  787. is more efficient to sort and then compare only adjacent elements.
  788. @end deffn
  789. @node SRFI-1 Association Lists
  790. @subsubsection Association Lists
  791. @cindex association list
  792. @cindex alist
  793. @c FIXME::martin: Review me!
  794. Association lists are described in detail in section @ref{Association
  795. Lists}. The present section only documents the additional procedures
  796. for dealing with association lists defined by SRFI-1.
  797. @deffn {Scheme Procedure} assoc key alist [=]
  798. Return the pair from @var{alist} which matches @var{key}. This
  799. extends the core @code{assoc} (@pxref{Retrieving Alist Entries}) by
  800. taking an optional @var{=} comparison procedure.
  801. The default comparison is @code{equal?}. If an @var{=} parameter is
  802. given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
  803. given target @var{key} is the first argument, and a @code{car} from
  804. @var{alist} is second.
  805. For example a case-insensitive string lookup,
  806. @example
  807. (assoc "yy" '(("XX" . 1) ("YY" . 2)) string-ci=?)
  808. @result{} ("YY" . 2)
  809. @end example
  810. @end deffn
  811. @deffn {Scheme Procedure} alist-cons key datum alist
  812. Cons a new association @var{key} and @var{datum} onto @var{alist} and
  813. return the result. This is equivalent to
  814. @lisp
  815. (cons (cons @var{key} @var{datum}) @var{alist})
  816. @end lisp
  817. @code{acons} (@pxref{Adding or Setting Alist Entries}) in the Guile
  818. core does the same thing.
  819. @end deffn
  820. @deffn {Scheme Procedure} alist-copy alist
  821. Return a newly allocated copy of @var{alist}, that means that the
  822. spine of the list as well as the pairs are copied.
  823. @end deffn
  824. @deffn {Scheme Procedure} alist-delete key alist [=]
  825. @deffnx {Scheme Procedure} alist-delete! key alist [=]
  826. Return a list containing the elements of @var{alist} but with those
  827. elements whose keys are equal to @var{key} deleted. The returned
  828. elements will be in the same order as they were in @var{alist}.
  829. Equality is determined by the @var{=} predicate, or @code{equal?} if
  830. not given. The order in which elements are tested is unspecified, but
  831. each equality call is made @code{(= key alistkey)}, i.e.@: the given
  832. @var{key} parameter is first and the key from @var{alist} second.
  833. This means for instance all associations with a key greater than 5 can
  834. be removed with @code{(alist-delete 5 alist <)}.
  835. @code{alist-delete} does not modify @var{alist}, but the return might
  836. share a common tail with @var{alist}. @code{alist-delete!} may modify
  837. the list structure of @var{alist} to construct its return.
  838. @end deffn
  839. @node SRFI-1 Set Operations
  840. @subsubsection Set Operations on Lists
  841. @cindex list set operation
  842. Lists can be used to represent sets of objects. The procedures in
  843. this section operate on such lists as sets.
  844. Note that lists are not an efficient way to implement large sets. The
  845. procedures here typically take time @math{@var{m}@cross{}@var{n}} when
  846. operating on @var{m} and @var{n} element lists. Other data structures
  847. like trees, bitsets (@pxref{Bit Vectors}) or hash tables (@pxref{Hash
  848. Tables}) are faster.
  849. All these procedures take an equality predicate as the first argument.
  850. This predicate is used for testing the objects in the list sets for
  851. sameness. This predicate must be consistent with @code{eq?}
  852. (@pxref{Equality}) in the sense that if two list elements are
  853. @code{eq?} then they must also be equal under the predicate. This
  854. simply means a given object must be equal to itself.
  855. @deffn {Scheme Procedure} lset<= = list @dots{}
  856. Return @code{#t} if each list is a subset of the one following it.
  857. I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of
  858. @var{list3}, etc., for as many lists as given. If only one list or no
  859. lists are given, the return value is @code{#t}.
  860. A list @var{x} is a subset of @var{y} if each element of @var{x} is
  861. equal to some element in @var{y}. Elements are compared using the
  862. given @var{=} procedure, called as @code{(@var{=} xelem yelem)}.
  863. @example
  864. (lset<= eq?) @result{} #t
  865. (lset<= eqv? '(1 2 3) '(1)) @result{} #f
  866. (lset<= eqv? '(1 3 2) '(4 3 1 2)) @result{} #t
  867. @end example
  868. @end deffn
  869. @deffn {Scheme Procedure} lset= = list @dots{}
  870. Return @code{#t} if all argument lists are set-equal. @var{list1} is
  871. compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many
  872. lists as given. If only one list or no lists are given, the return
  873. value is @code{#t}.
  874. Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
  875. is equal to some element of @var{y} and conversely each element of
  876. @var{y} is equal to some element of @var{x}. The order of the
  877. elements in the lists doesn't matter. Element equality is determined
  878. with the given @var{=} procedure, called as @code{(@var{=} xelem
  879. yelem)}, but exactly which calls are made is unspecified.
  880. @example
  881. (lset= eq?) @result{} #t
  882. (lset= eqv? '(1 2 3) '(3 2 1)) @result{} #t
  883. (lset= string-ci=? '("a" "A" "b") '("B" "b" "a")) @result{} #t
  884. @end example
  885. @end deffn
  886. @deffn {Scheme Procedure} lset-adjoin = list elem @dots{}
  887. Add to @var{list} any of the given @var{elem}s not already in the list.
  888. @var{elem}s are @code{cons}ed onto the start of @var{list} (so the
  889. return value shares a common tail with @var{list}), but the order that
  890. the @var{elem}s are added is unspecified.
  891. The given @var{=} procedure is used for comparing elements, called as
  892. @code{(@var{=} listelem elem)}, i.e., the second argument is one of
  893. the given @var{elem} parameters.
  894. @example
  895. (lset-adjoin eqv? '(1 2 3) 4 1 5) @result{} (5 4 1 2 3)
  896. @end example
  897. @end deffn
  898. @deffn {Scheme Procedure} lset-union = list @dots{}
  899. @deffnx {Scheme Procedure} lset-union! = list @dots{}
  900. Return the union of the argument list sets. The result is built by
  901. taking the union of @var{list1} and @var{list2}, then the union of
  902. that with @var{list3}, etc., for as many lists as given. For one list
  903. argument that list itself is the result, for no list arguments the
  904. result is the empty list.
  905. The union of two lists @var{x} and @var{y} is formed as follows. If
  906. @var{x} is empty then the result is @var{y}. Otherwise start with
  907. @var{x} as the result and consider each @var{y} element (from first to
  908. last). A @var{y} element not equal to something already in the result
  909. is @code{cons}ed onto the result.
  910. The given @var{=} procedure is used for comparing elements, called as
  911. @code{(@var{=} relem yelem)}. The first argument is from the result
  912. accumulated so far, and the second is from the list being union-ed in.
  913. But exactly which calls are made is otherwise unspecified.
  914. Notice that duplicate elements in @var{list1} (or the first non-empty
  915. list) are preserved, but that repeated elements in subsequent lists
  916. are only added once.
  917. @example
  918. (lset-union eqv?) @result{} ()
  919. (lset-union eqv? '(1 2 3)) @result{} (1 2 3)
  920. (lset-union eqv? '(1 2 1 3) '(2 4 5) '(5)) @result{} (5 4 1 2 1 3)
  921. @end example
  922. @code{lset-union} doesn't change the given lists but the result may
  923. share a tail with the first non-empty list. @code{lset-union!} can
  924. modify all of the given lists to form the result.
  925. @end deffn
  926. @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
  927. @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
  928. Return the intersection of @var{list1} with the other argument lists,
  929. meaning those elements of @var{list1} which are also in all of
  930. @var{list2} etc. For one list argument, just that list is returned.
  931. The test for an element of @var{list1} to be in the return is simply
  932. that it's equal to some element in each of @var{list2} etc. Notice
  933. this means an element appearing twice in @var{list1} but only once in
  934. each of @var{list2} etc will go into the return twice. The return has
  935. its elements in the same order as they were in @var{list1}.
  936. The given @var{=} procedure is used for comparing elements, called as
  937. @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
  938. and the second is from one of the subsequent lists. But exactly which
  939. calls are made and in what order is unspecified.
  940. @example
  941. (lset-intersection eqv? '(x y)) @result{} (x y)
  942. (lset-intersection eqv? '(1 2 3) '(4 3 2)) @result{} (2 3)
  943. (lset-intersection eqv? '(1 1 2 2) '(1 2) '(2 1) '(2)) @result{} (2 2)
  944. @end example
  945. The return from @code{lset-intersection} may share a tail with
  946. @var{list1}. @code{lset-intersection!} may modify @var{list1} to form
  947. its result.
  948. @end deffn
  949. @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
  950. @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
  951. Return @var{list1} with any elements in @var{list2}, @var{list3} etc
  952. removed (ie.@: subtracted). For one list argument, just that list is
  953. returned.
  954. The given @var{=} procedure is used for comparing elements, called as
  955. @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
  956. and the second from one of the subsequent lists. But exactly which
  957. calls are made and in what order is unspecified.
  958. @example
  959. (lset-difference eqv? '(x y)) @result{} (x y)
  960. (lset-difference eqv? '(1 2 3) '(3 1)) @result{} (2)
  961. (lset-difference eqv? '(1 2 3) '(3) '(2)) @result{} (1)
  962. @end example
  963. The return from @code{lset-difference} may share a tail with
  964. @var{list1}. @code{lset-difference!} may modify @var{list1} to form
  965. its result.
  966. @end deffn
  967. @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
  968. @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
  969. Return two values (@pxref{Multiple Values}), the difference and
  970. intersection of the argument lists as per @code{lset-difference} and
  971. @code{lset-intersection} above.
  972. For two list arguments this partitions @var{list1} into those elements
  973. of @var{list1} which are in @var{list2} and not in @var{list2}. (But
  974. for more than two arguments there can be elements of @var{list1} which
  975. are neither part of the difference nor the intersection.)
  976. One of the return values from @code{lset-diff+intersection} may share
  977. a tail with @var{list1}. @code{lset-diff+intersection!} may modify
  978. @var{list1} to form its results.
  979. @end deffn
  980. @deffn {Scheme Procedure} lset-xor = list @dots{}
  981. @deffnx {Scheme Procedure} lset-xor! = list @dots{}
  982. Return an XOR of the argument lists. For two lists this means those
  983. elements which are in exactly one of the lists. For more than two
  984. lists it means those elements which appear in an odd number of the
  985. lists.
  986. To be precise, the XOR of two lists @var{x} and @var{y} is formed by
  987. taking those elements of @var{x} not equal to any element of @var{y},
  988. plus those elements of @var{y} not equal to any element of @var{x}.
  989. Equality is determined with the given @var{=} procedure, called as
  990. @code{(@var{=} e1 e2)}. One argument is from @var{x} and the other
  991. from @var{y}, but which way around is unspecified. Exactly which
  992. calls are made is also unspecified, as is the order of the elements in
  993. the result.
  994. @example
  995. (lset-xor eqv? '(x y)) @result{} (x y)
  996. (lset-xor eqv? '(1 2 3) '(4 3 2)) @result{} (4 1)
  997. @end example
  998. The return from @code{lset-xor} may share a tail with one of the list
  999. arguments. @code{lset-xor!} may modify @var{list1} to form its
  1000. result.
  1001. @end deffn
  1002. @node SRFI-2
  1003. @subsection SRFI-2 - and-let*
  1004. @cindex SRFI-2
  1005. @noindent
  1006. The following syntax can be obtained with
  1007. @lisp
  1008. (use-modules (srfi srfi-2))
  1009. @end lisp
  1010. or alternatively
  1011. @lisp
  1012. (use-modules (ice-9 and-let-star))
  1013. @end lisp
  1014. @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
  1015. A combination of @code{and} and @code{let*}.
  1016. Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
  1017. then evaluation stops and @code{#f} is returned. If all are
  1018. non-@code{#f} then @var{body} is evaluated and the last form gives the
  1019. return value, or if @var{body} is empty then the result is @code{#t}.
  1020. Each @var{clause} should be one of the following,
  1021. @table @code
  1022. @item (symbol expr)
  1023. Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
  1024. Like @code{let*}, that binding is available to subsequent clauses.
  1025. @item (expr)
  1026. Evaluate @var{expr} and check for @code{#f}.
  1027. @item symbol
  1028. Get the value bound to @var{symbol} and check for @code{#f}.
  1029. @end table
  1030. Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
  1031. instance @code{((eq? x y))}. One way to remember this is to imagine
  1032. the @code{symbol} in @code{(symbol expr)} is omitted.
  1033. @code{and-let*} is good for calculations where a @code{#f} value means
  1034. termination, but where a non-@code{#f} value is going to be needed in
  1035. subsequent expressions.
  1036. The following illustrates this, it returns text between brackets
  1037. @samp{[...]} in a string, or @code{#f} if there are no such brackets
  1038. (ie.@: either @code{string-index} gives @code{#f}).
  1039. @example
  1040. (define (extract-brackets str)
  1041. (and-let* ((start (string-index str #\[))
  1042. (end (string-index str #\] start)))
  1043. (substring str (1+ start) end)))
  1044. @end example
  1045. The following shows plain variables and expressions tested too.
  1046. @code{diagnostic-levels} is taken to be an alist associating a
  1047. diagnostic type with a level. @code{str} is printed only if the type
  1048. is known and its level is high enough.
  1049. @example
  1050. (define (show-diagnostic type str)
  1051. (and-let* (want-diagnostics
  1052. (level (assq-ref diagnostic-levels type))
  1053. ((>= level current-diagnostic-level)))
  1054. (display str)))
  1055. @end example
  1056. The advantage of @code{and-let*} is that an extended sequence of
  1057. expressions and tests doesn't require lots of nesting as would arise
  1058. from separate @code{and} and @code{let*}, or from @code{cond} with
  1059. @code{=>}.
  1060. @end deffn
  1061. @node SRFI-4
  1062. @subsection SRFI-4 - Homogeneous numeric vector datatypes
  1063. @cindex SRFI-4
  1064. SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements
  1065. are all of a single numeric type. Guile offers uniform numeric vectors for
  1066. signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
  1067. floating point values, and, as an extension to SRFI-4, complex floating-point
  1068. numbers of these two sizes.
  1069. The standard SRFI-4 procedures and data types may be included via loading the
  1070. appropriate module:
  1071. @example
  1072. (use-modules (srfi srfi-4))
  1073. @end example
  1074. This module is currently a part of the default Guile environment, but it is a
  1075. good practice to explicitly import the module. In the future, using SRFI-4
  1076. procedures without importing the SRFI-4 module will cause a deprecation message
  1077. to be printed. (Of course, one may call the C functions at any time. Would that
  1078. C had modules!)
  1079. @menu
  1080. * SRFI-4 Overview:: The warp and weft of uniform numeric vectors.
  1081. * SRFI-4 API:: Uniform vectors, from Scheme and from C.
  1082. * SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors.
  1083. * SRFI-4 Extensions:: Guile-specific extensions to the standard.
  1084. @end menu
  1085. @node SRFI-4 Overview
  1086. @subsubsection SRFI-4 - Overview
  1087. Uniform numeric vectors can be useful since they consume less memory
  1088. than the non-uniform, general vectors. Also, since the types they can
  1089. store correspond directly to C types, it is easier to work with them
  1090. efficiently on a low level. Consider image processing as an example,
  1091. where you want to apply a filter to some image. While you could store
  1092. the pixels of an image in a general vector and write a general
  1093. convolution function, things are much more efficient with uniform
  1094. vectors: the convolution function knows that all pixels are unsigned
  1095. 8-bit values (say), and can use a very tight inner loop.
  1096. This is implemented in Scheme by having the compiler notice calls to the SRFI-4
  1097. accessors, and inline them to appropriate compiled code. From C you have access
  1098. to the raw array; functions for efficiently working with uniform numeric vectors
  1099. from C are listed at the end of this section.
  1100. Uniform numeric vectors are the special case of one dimensional uniform
  1101. numeric arrays.
  1102. There are 12 standard kinds of uniform numeric vectors, and they all have their
  1103. own complement of constructors, accessors, and so on. Procedures that operate on
  1104. a specific kind of uniform numeric vector have a ``tag'' in their name,
  1105. indicating the element type.
  1106. @table @nicode
  1107. @item u8
  1108. unsigned 8-bit integers
  1109. @item s8
  1110. signed 8-bit integers
  1111. @item u16
  1112. unsigned 16-bit integers
  1113. @item s16
  1114. signed 16-bit integers
  1115. @item u32
  1116. unsigned 32-bit integers
  1117. @item s32
  1118. signed 32-bit integers
  1119. @item u64
  1120. unsigned 64-bit integers
  1121. @item s64
  1122. signed 64-bit integers
  1123. @item f32
  1124. the C type @code{float}
  1125. @item f64
  1126. the C type @code{double}
  1127. @end table
  1128. In addition, Guile supports uniform arrays of complex numbers, with the
  1129. nonstandard tags:
  1130. @table @nicode
  1131. @item c32
  1132. complex numbers in rectangular form with the real and imaginary part
  1133. being a @code{float}
  1134. @item c64
  1135. complex numbers in rectangular form with the real and imaginary part
  1136. being a @code{double}
  1137. @end table
  1138. The external representation (ie.@: read syntax) for these vectors is
  1139. similar to normal Scheme vectors, but with an additional tag from the
  1140. tables above indicating the vector's type. For example,
  1141. @lisp
  1142. #u16(1 2 3)
  1143. #f64(3.1415 2.71)
  1144. @end lisp
  1145. Note that the read syntax for floating-point here conflicts with
  1146. @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
  1147. for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
  1148. is invalid. @code{(1 #f 3)} is almost certainly what one should write
  1149. anyway to make the intention clear, so this is rarely a problem.
  1150. @node SRFI-4 API
  1151. @subsubsection SRFI-4 - API
  1152. Note that the @nicode{c32} and @nicode{c64} functions are only available from
  1153. @nicode{(srfi srfi-4 gnu)}.
  1154. @deffn {Scheme Procedure} u8vector? obj
  1155. @deffnx {Scheme Procedure} s8vector? obj
  1156. @deffnx {Scheme Procedure} u16vector? obj
  1157. @deffnx {Scheme Procedure} s16vector? obj
  1158. @deffnx {Scheme Procedure} u32vector? obj
  1159. @deffnx {Scheme Procedure} s32vector? obj
  1160. @deffnx {Scheme Procedure} u64vector? obj
  1161. @deffnx {Scheme Procedure} s64vector? obj
  1162. @deffnx {Scheme Procedure} f32vector? obj
  1163. @deffnx {Scheme Procedure} f64vector? obj
  1164. @deffnx {Scheme Procedure} c32vector? obj
  1165. @deffnx {Scheme Procedure} c64vector? obj
  1166. @deffnx {C Function} scm_u8vector_p (obj)
  1167. @deffnx {C Function} scm_s8vector_p (obj)
  1168. @deffnx {C Function} scm_u16vector_p (obj)
  1169. @deffnx {C Function} scm_s16vector_p (obj)
  1170. @deffnx {C Function} scm_u32vector_p (obj)
  1171. @deffnx {C Function} scm_s32vector_p (obj)
  1172. @deffnx {C Function} scm_u64vector_p (obj)
  1173. @deffnx {C Function} scm_s64vector_p (obj)
  1174. @deffnx {C Function} scm_f32vector_p (obj)
  1175. @deffnx {C Function} scm_f64vector_p (obj)
  1176. @deffnx {C Function} scm_c32vector_p (obj)
  1177. @deffnx {C Function} scm_c64vector_p (obj)
  1178. Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
  1179. indicated type.
  1180. @end deffn
  1181. @deffn {Scheme Procedure} make-u8vector n [value]
  1182. @deffnx {Scheme Procedure} make-s8vector n [value]
  1183. @deffnx {Scheme Procedure} make-u16vector n [value]
  1184. @deffnx {Scheme Procedure} make-s16vector n [value]
  1185. @deffnx {Scheme Procedure} make-u32vector n [value]
  1186. @deffnx {Scheme Procedure} make-s32vector n [value]
  1187. @deffnx {Scheme Procedure} make-u64vector n [value]
  1188. @deffnx {Scheme Procedure} make-s64vector n [value]
  1189. @deffnx {Scheme Procedure} make-f32vector n [value]
  1190. @deffnx {Scheme Procedure} make-f64vector n [value]
  1191. @deffnx {Scheme Procedure} make-c32vector n [value]
  1192. @deffnx {Scheme Procedure} make-c64vector n [value]
  1193. @deffnx {C Function} scm_make_u8vector (n, value)
  1194. @deffnx {C Function} scm_make_s8vector (n, value)
  1195. @deffnx {C Function} scm_make_u16vector (n, value)
  1196. @deffnx {C Function} scm_make_s16vector (n, value)
  1197. @deffnx {C Function} scm_make_u32vector (n, value)
  1198. @deffnx {C Function} scm_make_s32vector (n, value)
  1199. @deffnx {C Function} scm_make_u64vector (n, value)
  1200. @deffnx {C Function} scm_make_s64vector (n, value)
  1201. @deffnx {C Function} scm_make_f32vector (n, value)
  1202. @deffnx {C Function} scm_make_f64vector (n, value)
  1203. @deffnx {C Function} scm_make_c32vector (n, value)
  1204. @deffnx {C Function} scm_make_c64vector (n, value)
  1205. Return a newly allocated homogeneous numeric vector holding @var{n}
  1206. elements of the indicated type. If @var{value} is given, the vector
  1207. is initialized with that value, otherwise the contents are
  1208. unspecified.
  1209. @end deffn
  1210. @deffn {Scheme Procedure} u8vector value @dots{}
  1211. @deffnx {Scheme Procedure} s8vector value @dots{}
  1212. @deffnx {Scheme Procedure} u16vector value @dots{}
  1213. @deffnx {Scheme Procedure} s16vector value @dots{}
  1214. @deffnx {Scheme Procedure} u32vector value @dots{}
  1215. @deffnx {Scheme Procedure} s32vector value @dots{}
  1216. @deffnx {Scheme Procedure} u64vector value @dots{}
  1217. @deffnx {Scheme Procedure} s64vector value @dots{}
  1218. @deffnx {Scheme Procedure} f32vector value @dots{}
  1219. @deffnx {Scheme Procedure} f64vector value @dots{}
  1220. @deffnx {Scheme Procedure} c32vector value @dots{}
  1221. @deffnx {Scheme Procedure} c64vector value @dots{}
  1222. @deffnx {C Function} scm_u8vector (values)
  1223. @deffnx {C Function} scm_s8vector (values)
  1224. @deffnx {C Function} scm_u16vector (values)
  1225. @deffnx {C Function} scm_s16vector (values)
  1226. @deffnx {C Function} scm_u32vector (values)
  1227. @deffnx {C Function} scm_s32vector (values)
  1228. @deffnx {C Function} scm_u64vector (values)
  1229. @deffnx {C Function} scm_s64vector (values)
  1230. @deffnx {C Function} scm_f32vector (values)
  1231. @deffnx {C Function} scm_f64vector (values)
  1232. @deffnx {C Function} scm_c32vector (values)
  1233. @deffnx {C Function} scm_c64vector (values)
  1234. Return a newly allocated homogeneous numeric vector of the indicated
  1235. type, holding the given parameter @var{value}s. The vector length is
  1236. the number of parameters given.
  1237. @end deffn
  1238. @deffn {Scheme Procedure} u8vector-length vec
  1239. @deffnx {Scheme Procedure} s8vector-length vec
  1240. @deffnx {Scheme Procedure} u16vector-length vec
  1241. @deffnx {Scheme Procedure} s16vector-length vec
  1242. @deffnx {Scheme Procedure} u32vector-length vec
  1243. @deffnx {Scheme Procedure} s32vector-length vec
  1244. @deffnx {Scheme Procedure} u64vector-length vec
  1245. @deffnx {Scheme Procedure} s64vector-length vec
  1246. @deffnx {Scheme Procedure} f32vector-length vec
  1247. @deffnx {Scheme Procedure} f64vector-length vec
  1248. @deffnx {Scheme Procedure} c32vector-length vec
  1249. @deffnx {Scheme Procedure} c64vector-length vec
  1250. @deffnx {C Function} scm_u8vector_length (vec)
  1251. @deffnx {C Function} scm_s8vector_length (vec)
  1252. @deffnx {C Function} scm_u16vector_length (vec)
  1253. @deffnx {C Function} scm_s16vector_length (vec)
  1254. @deffnx {C Function} scm_u32vector_length (vec)
  1255. @deffnx {C Function} scm_s32vector_length (vec)
  1256. @deffnx {C Function} scm_u64vector_length (vec)
  1257. @deffnx {C Function} scm_s64vector_length (vec)
  1258. @deffnx {C Function} scm_f32vector_length (vec)
  1259. @deffnx {C Function} scm_f64vector_length (vec)
  1260. @deffnx {C Function} scm_c32vector_length (vec)
  1261. @deffnx {C Function} scm_c64vector_length (vec)
  1262. Return the number of elements in @var{vec}.
  1263. @end deffn
  1264. @deffn {Scheme Procedure} u8vector-ref vec i
  1265. @deffnx {Scheme Procedure} s8vector-ref vec i
  1266. @deffnx {Scheme Procedure} u16vector-ref vec i
  1267. @deffnx {Scheme Procedure} s16vector-ref vec i
  1268. @deffnx {Scheme Procedure} u32vector-ref vec i
  1269. @deffnx {Scheme Procedure} s32vector-ref vec i
  1270. @deffnx {Scheme Procedure} u64vector-ref vec i
  1271. @deffnx {Scheme Procedure} s64vector-ref vec i
  1272. @deffnx {Scheme Procedure} f32vector-ref vec i
  1273. @deffnx {Scheme Procedure} f64vector-ref vec i
  1274. @deffnx {Scheme Procedure} c32vector-ref vec i
  1275. @deffnx {Scheme Procedure} c64vector-ref vec i
  1276. @deffnx {C Function} scm_u8vector_ref (vec, i)
  1277. @deffnx {C Function} scm_s8vector_ref (vec, i)
  1278. @deffnx {C Function} scm_u16vector_ref (vec, i)
  1279. @deffnx {C Function} scm_s16vector_ref (vec, i)
  1280. @deffnx {C Function} scm_u32vector_ref (vec, i)
  1281. @deffnx {C Function} scm_s32vector_ref (vec, i)
  1282. @deffnx {C Function} scm_u64vector_ref (vec, i)
  1283. @deffnx {C Function} scm_s64vector_ref (vec, i)
  1284. @deffnx {C Function} scm_f32vector_ref (vec, i)
  1285. @deffnx {C Function} scm_f64vector_ref (vec, i)
  1286. @deffnx {C Function} scm_c32vector_ref (vec, i)
  1287. @deffnx {C Function} scm_c64vector_ref (vec, i)
  1288. Return the element at index @var{i} in @var{vec}. The first element
  1289. in @var{vec} is index 0.
  1290. @end deffn
  1291. @deffn {Scheme Procedure} u8vector-set! vec i value
  1292. @deffnx {Scheme Procedure} s8vector-set! vec i value
  1293. @deffnx {Scheme Procedure} u16vector-set! vec i value
  1294. @deffnx {Scheme Procedure} s16vector-set! vec i value
  1295. @deffnx {Scheme Procedure} u32vector-set! vec i value
  1296. @deffnx {Scheme Procedure} s32vector-set! vec i value
  1297. @deffnx {Scheme Procedure} u64vector-set! vec i value
  1298. @deffnx {Scheme Procedure} s64vector-set! vec i value
  1299. @deffnx {Scheme Procedure} f32vector-set! vec i value
  1300. @deffnx {Scheme Procedure} f64vector-set! vec i value
  1301. @deffnx {Scheme Procedure} c32vector-set! vec i value
  1302. @deffnx {Scheme Procedure} c64vector-set! vec i value
  1303. @deffnx {C Function} scm_u8vector_set_x (vec, i, value)
  1304. @deffnx {C Function} scm_s8vector_set_x (vec, i, value)
  1305. @deffnx {C Function} scm_u16vector_set_x (vec, i, value)
  1306. @deffnx {C Function} scm_s16vector_set_x (vec, i, value)
  1307. @deffnx {C Function} scm_u32vector_set_x (vec, i, value)
  1308. @deffnx {C Function} scm_s32vector_set_x (vec, i, value)
  1309. @deffnx {C Function} scm_u64vector_set_x (vec, i, value)
  1310. @deffnx {C Function} scm_s64vector_set_x (vec, i, value)
  1311. @deffnx {C Function} scm_f32vector_set_x (vec, i, value)
  1312. @deffnx {C Function} scm_f64vector_set_x (vec, i, value)
  1313. @deffnx {C Function} scm_c32vector_set_x (vec, i, value)
  1314. @deffnx {C Function} scm_c64vector_set_x (vec, i, value)
  1315. Set the element at index @var{i} in @var{vec} to @var{value}. The
  1316. first element in @var{vec} is index 0. The return value is
  1317. unspecified.
  1318. @end deffn
  1319. @deffn {Scheme Procedure} u8vector->list vec
  1320. @deffnx {Scheme Procedure} s8vector->list vec
  1321. @deffnx {Scheme Procedure} u16vector->list vec
  1322. @deffnx {Scheme Procedure} s16vector->list vec
  1323. @deffnx {Scheme Procedure} u32vector->list vec
  1324. @deffnx {Scheme Procedure} s32vector->list vec
  1325. @deffnx {Scheme Procedure} u64vector->list vec
  1326. @deffnx {Scheme Procedure} s64vector->list vec
  1327. @deffnx {Scheme Procedure} f32vector->list vec
  1328. @deffnx {Scheme Procedure} f64vector->list vec
  1329. @deffnx {Scheme Procedure} c32vector->list vec
  1330. @deffnx {Scheme Procedure} c64vector->list vec
  1331. @deffnx {C Function} scm_u8vector_to_list (vec)
  1332. @deffnx {C Function} scm_s8vector_to_list (vec)
  1333. @deffnx {C Function} scm_u16vector_to_list (vec)
  1334. @deffnx {C Function} scm_s16vector_to_list (vec)
  1335. @deffnx {C Function} scm_u32vector_to_list (vec)
  1336. @deffnx {C Function} scm_s32vector_to_list (vec)
  1337. @deffnx {C Function} scm_u64vector_to_list (vec)
  1338. @deffnx {C Function} scm_s64vector_to_list (vec)
  1339. @deffnx {C Function} scm_f32vector_to_list (vec)
  1340. @deffnx {C Function} scm_f64vector_to_list (vec)
  1341. @deffnx {C Function} scm_c32vector_to_list (vec)
  1342. @deffnx {C Function} scm_c64vector_to_list (vec)
  1343. Return a newly allocated list holding all elements of @var{vec}.
  1344. @end deffn
  1345. @deffn {Scheme Procedure} list->u8vector lst
  1346. @deffnx {Scheme Procedure} list->s8vector lst
  1347. @deffnx {Scheme Procedure} list->u16vector lst
  1348. @deffnx {Scheme Procedure} list->s16vector lst
  1349. @deffnx {Scheme Procedure} list->u32vector lst
  1350. @deffnx {Scheme Procedure} list->s32vector lst
  1351. @deffnx {Scheme Procedure} list->u64vector lst
  1352. @deffnx {Scheme Procedure} list->s64vector lst
  1353. @deffnx {Scheme Procedure} list->f32vector lst
  1354. @deffnx {Scheme Procedure} list->f64vector lst
  1355. @deffnx {Scheme Procedure} list->c32vector lst
  1356. @deffnx {Scheme Procedure} list->c64vector lst
  1357. @deffnx {C Function} scm_list_to_u8vector (lst)
  1358. @deffnx {C Function} scm_list_to_s8vector (lst)
  1359. @deffnx {C Function} scm_list_to_u16vector (lst)
  1360. @deffnx {C Function} scm_list_to_s16vector (lst)
  1361. @deffnx {C Function} scm_list_to_u32vector (lst)
  1362. @deffnx {C Function} scm_list_to_s32vector (lst)
  1363. @deffnx {C Function} scm_list_to_u64vector (lst)
  1364. @deffnx {C Function} scm_list_to_s64vector (lst)
  1365. @deffnx {C Function} scm_list_to_f32vector (lst)
  1366. @deffnx {C Function} scm_list_to_f64vector (lst)
  1367. @deffnx {C Function} scm_list_to_c32vector (lst)
  1368. @deffnx {C Function} scm_list_to_c64vector (lst)
  1369. Return a newly allocated homogeneous numeric vector of the indicated type,
  1370. initialized with the elements of the list @var{lst}.
  1371. @end deffn
  1372. @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
  1373. @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
  1374. @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
  1375. @deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
  1376. @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
  1377. @deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
  1378. @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
  1379. @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
  1380. @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
  1381. @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
  1382. @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
  1383. @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
  1384. Return a new uniform numeric vector of the indicated type and length
  1385. that uses the memory pointed to by @var{data} to store its elements.
  1386. This memory will eventually be freed with @code{free}. The argument
  1387. @var{len} specifies the number of elements in @var{data}, not its size
  1388. in bytes.
  1389. The @code{c32} and @code{c64} variants take a pointer to a C array of
  1390. @code{float}s or @code{double}s. The real parts of the complex numbers
  1391. are at even indices in that array, the corresponding imaginary parts are
  1392. at the following odd index.
  1393. @end deftypefn
  1394. @deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1395. @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1396. @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1397. @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1398. @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1399. @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1400. @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1401. @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1402. @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1403. @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1404. @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1405. @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1406. Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
  1407. returns a pointer to the elements of a uniform numeric vector of the
  1408. indicated kind.
  1409. @end deftypefn
  1410. @deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1411. @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1412. @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1413. @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1414. @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1415. @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1416. @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1417. @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1418. @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1419. @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1420. @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1421. @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
  1422. Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
  1423. C}), but returns a pointer to the elements of a uniform numeric vector
  1424. of the indicated kind.
  1425. @end deftypefn
  1426. @node SRFI-4 and Bytevectors
  1427. @subsubsection SRFI-4 - Relation to bytevectors
  1428. Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often
  1429. when you have a numeric vector, you end up wanting to write its bytes somewhere,
  1430. or have access to the underlying bytes, or read in bytes from somewhere else.
  1431. Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer
  1432. to use when doing number-crunching, because they are addressed by element and
  1433. not by byte.
  1434. So as a compromise, Guile allows all bytevector functions to operate on numeric
  1435. vectors. They address the underlying bytes in the native endianness, as one
  1436. would expect.
  1437. Following the same reasoning, that it's just bytes underneath, Guile also allows
  1438. uniform vectors of a given type to be accessed as if they were of any type. One
  1439. can fill a @nicode{u32vector}, and access its elements with
  1440. @nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's
  1441. all the same to Guile.
  1442. In this way, uniform numeric vectors may be written to and read from
  1443. input/output ports using the procedures that operate on bytevectors.
  1444. @xref{Bytevectors}, for more information.
  1445. @node SRFI-4 Extensions
  1446. @subsubsection SRFI-4 - Guile extensions
  1447. Guile defines some useful extensions to SRFI-4, which are not available in the
  1448. default Guile environment. They may be imported by loading the extensions
  1449. module:
  1450. @example
  1451. (use-modules (srfi srfi-4 gnu))
  1452. @end example
  1453. @deffn {Scheme Procedure} any->u8vector obj
  1454. @deffnx {Scheme Procedure} any->s8vector obj
  1455. @deffnx {Scheme Procedure} any->u16vector obj
  1456. @deffnx {Scheme Procedure} any->s16vector obj
  1457. @deffnx {Scheme Procedure} any->u32vector obj
  1458. @deffnx {Scheme Procedure} any->s32vector obj
  1459. @deffnx {Scheme Procedure} any->u64vector obj
  1460. @deffnx {Scheme Procedure} any->s64vector obj
  1461. @deffnx {Scheme Procedure} any->f32vector obj
  1462. @deffnx {Scheme Procedure} any->f64vector obj
  1463. @deffnx {Scheme Procedure} any->c32vector obj
  1464. @deffnx {Scheme Procedure} any->c64vector obj
  1465. @deffnx {C Function} scm_any_to_u8vector (obj)
  1466. @deffnx {C Function} scm_any_to_s8vector (obj)
  1467. @deffnx {C Function} scm_any_to_u16vector (obj)
  1468. @deffnx {C Function} scm_any_to_s16vector (obj)
  1469. @deffnx {C Function} scm_any_to_u32vector (obj)
  1470. @deffnx {C Function} scm_any_to_s32vector (obj)
  1471. @deffnx {C Function} scm_any_to_u64vector (obj)
  1472. @deffnx {C Function} scm_any_to_s64vector (obj)
  1473. @deffnx {C Function} scm_any_to_f32vector (obj)
  1474. @deffnx {C Function} scm_any_to_f64vector (obj)
  1475. @deffnx {C Function} scm_any_to_c32vector (obj)
  1476. @deffnx {C Function} scm_any_to_c64vector (obj)
  1477. Return a (maybe newly allocated) uniform numeric vector of the indicated
  1478. type, initialized with the elements of @var{obj}, which must be a list,
  1479. a vector, or a uniform vector. When @var{obj} is already a suitable
  1480. uniform numeric vector, it is returned unchanged.
  1481. @end deffn
  1482. @node SRFI-6
  1483. @subsection SRFI-6 - Basic String Ports
  1484. @cindex SRFI-6
  1485. SRFI-6 defines the procedures @code{open-input-string},
  1486. @code{open-output-string} and @code{get-output-string}. These
  1487. procedures are included in the Guile core, so using this module does not
  1488. make any difference at the moment. But it is possible that support for
  1489. SRFI-6 will be factored out of the core library in the future, so using
  1490. this module does not hurt, after all.
  1491. @node SRFI-8
  1492. @subsection SRFI-8 - receive
  1493. @cindex SRFI-8
  1494. @code{receive} is a syntax for making the handling of multiple-value
  1495. procedures easier. It is documented in @xref{Multiple Values}.
  1496. @node SRFI-9
  1497. @subsection SRFI-9 - define-record-type
  1498. This SRFI is a syntax for defining new record types and creating
  1499. predicate, constructor, and field getter and setter functions. It is
  1500. documented in the ``Data Types'' section of the manual (@pxref{SRFI-9
  1501. Records}).
  1502. @node SRFI-10
  1503. @subsection SRFI-10 - Hash-Comma Reader Extension
  1504. @cindex SRFI-10
  1505. @cindex hash-comma
  1506. @cindex #,()
  1507. This SRFI implements a reader extension @code{#,()} called hash-comma.
  1508. It allows the reader to give new kinds of objects, for use both in data
  1509. and as constants or literals in source code. This feature is available
  1510. with
  1511. @example
  1512. (use-modules (srfi srfi-10))
  1513. @end example
  1514. @noindent
  1515. The new read syntax is of the form
  1516. @example
  1517. #,(@var{tag} @var{arg}@dots{})
  1518. @end example
  1519. @noindent
  1520. where @var{tag} is a symbol and the @var{arg}s are objects taken as
  1521. parameters. @var{tag}s are registered with the following procedure.
  1522. @deffn {Scheme Procedure} define-reader-ctor tag proc
  1523. Register @var{proc} as the constructor for a hash-comma read syntax
  1524. starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
  1525. @var{proc} is called with the given arguments @code{(@var{proc}
  1526. arg@dots{})} and the object it returns is the result of the read.
  1527. @end deffn
  1528. @noindent
  1529. For example, a syntax giving a list of @var{N} copies of an object.
  1530. @example
  1531. (define-reader-ctor 'repeat
  1532. (lambda (obj reps)
  1533. (make-list reps obj)))
  1534. (display '#,(repeat 99 3))
  1535. @print{} (99 99 99)
  1536. @end example
  1537. Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
  1538. @code{repeat} handler returns a list and the program must quote to use
  1539. it literally, the same as any other list. Ie.
  1540. @example
  1541. (display '#,(repeat 99 3))
  1542. @result{}
  1543. (display '(99 99 99))
  1544. @end example
  1545. When a handler returns an object which is self-evaluating, like a
  1546. number or a string, then there's no need for quoting, just as there's
  1547. no need when giving those directly as literals. For example an
  1548. addition,
  1549. @example
  1550. (define-reader-ctor 'sum
  1551. (lambda (x y)
  1552. (+ x y)))
  1553. (display #,(sum 123 456)) @print{} 579
  1554. @end example
  1555. Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
  1556. globally, there's no need to use @code{(srfi srfi-10)} in later
  1557. modules. Similarly the tags registered are global and can be used
  1558. anywhere once registered.
  1559. We do not recommend @nicode{#,()} reader extensions, however, and for
  1560. three reasons.
  1561. First of all, this SRFI is not modular: the tag is matched by name, not
  1562. as an identifier within a scope. Defining a reader extension in one
  1563. part of a program can thus affect unrelated parts of a program because
  1564. the tag is not scoped.
  1565. Secondly, reader extensions can be hard to manage from a time
  1566. perspective: when does the reader extension take effect? @xref{Eval
  1567. When}, for more discussion.
  1568. Finally, reader extensions can easily produce objects that can't be
  1569. reified to an object file by the compiler. For example if you define a
  1570. reader extension that makes a hash table (@pxref{Hash Tables}), then it
  1571. will work fine when run with the interpreter, and you think you have a
  1572. neat hack. But then if you try to compile your program, after wrangling
  1573. with the @code{eval-when} concerns mentioned above, the compiler will
  1574. carp that it doesn't know how to serialize a hash table to disk.
  1575. In the specific case of hash tables, it would be possible for Guile to
  1576. know how to pack hash tables into compiled files, but this doesn't work
  1577. in general. What if the object you produce is an instance of a record
  1578. type? Guile would then have to serialize the record type to disk too,
  1579. and then what happens if the program independently loads the code that
  1580. defines the record type? Does it define the same type or a different
  1581. type? Guile's record types are nominal, not structural, so the answer
  1582. is not clear at all.
  1583. For all of these reasons we recommend macros over reader extensions.
  1584. Macros fulfill many of the same needs while preserving modular
  1585. composition, and their interaction with @code{eval-when} is well-known.
  1586. If you need brevity, instead use @code{read-hash-extend} and make your
  1587. reader extension expand to a macro invocation. In that way we preserve
  1588. scoping as much as possible. @xref{Reader Extensions}.
  1589. @node SRFI-11
  1590. @subsection SRFI-11 - let-values
  1591. @cindex SRFI-11
  1592. @findex let-values
  1593. @findex let*-values
  1594. This module implements the binding forms for multiple values
  1595. @code{let-values} and @code{let*-values}. These forms are similar to
  1596. @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
  1597. binding of the values returned by multiple-valued expressions.
  1598. Write @code{(use-modules (srfi srfi-11))} to make the bindings
  1599. available.
  1600. @lisp
  1601. (let-values (((x y) (values 1 2))
  1602. ((z f) (values 3 4)))
  1603. (+ x y z f))
  1604. @result{}
  1605. 10
  1606. @end lisp
  1607. @code{let-values} performs all bindings simultaneously, which means that
  1608. no expression in the binding clauses may refer to variables bound in the
  1609. same clause list. @code{let*-values}, on the other hand, performs the
  1610. bindings sequentially, just like @code{let*} does for single-valued
  1611. expressions.
  1612. @node SRFI-13
  1613. @subsection SRFI-13 - String Library
  1614. @cindex SRFI-13
  1615. The SRFI-13 procedures are always available, @xref{Strings}.
  1616. @node SRFI-14
  1617. @subsection SRFI-14 - Character-set Library
  1618. @cindex SRFI-14
  1619. The SRFI-14 data type and procedures are always available,
  1620. @xref{Character Sets}.
  1621. @node SRFI-16
  1622. @subsection SRFI-16 - case-lambda
  1623. @cindex SRFI-16
  1624. @cindex variable arity
  1625. @cindex arity, variable
  1626. SRFI-16 defines a variable-arity @code{lambda} form,
  1627. @code{case-lambda}. This form is available in the default Guile
  1628. environment. @xref{Case-lambda}, for more information.
  1629. @node SRFI-17
  1630. @subsection SRFI-17 - Generalized set!
  1631. @cindex SRFI-17
  1632. This SRFI implements a generalized @code{set!}, allowing some
  1633. ``referencing'' functions to be used as the target location of a
  1634. @code{set!}. This feature is available from
  1635. @example
  1636. (use-modules (srfi srfi-17))
  1637. @end example
  1638. @noindent
  1639. For example @code{vector-ref} is extended so that
  1640. @example
  1641. (set! (vector-ref vec idx) new-value)
  1642. @end example
  1643. @noindent
  1644. is equivalent to
  1645. @example
  1646. (vector-set! vec idx new-value)
  1647. @end example
  1648. The idea is that a @code{vector-ref} expression identifies a location,
  1649. which may be either fetched or stored. The same form is used for the
  1650. location in both cases, encouraging visual clarity. This is similar
  1651. to the idea of an ``lvalue'' in C.
  1652. The mechanism for this kind of @code{set!} is in the Guile core
  1653. (@pxref{Procedures with Setters}). This module adds definitions of
  1654. the following functions as procedures with setters, allowing them to
  1655. be targets of a @code{set!},
  1656. @quotation
  1657. @nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
  1658. @nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
  1659. @nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
  1660. @nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
  1661. @nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
  1662. @nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
  1663. @nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
  1664. @nicode{cdddar}, @nicode{cddddr}
  1665. @nicode{string-ref}, @nicode{vector-ref}
  1666. @end quotation
  1667. The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
  1668. a procedure with setter, allowing the setter for a procedure to be
  1669. changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
  1670. Currently Guile does not implement this, a setter can only be
  1671. specified on creation (@code{getter-with-setter} below).
  1672. @defun getter-with-setter
  1673. The same as the Guile core @code{make-procedure-with-setter}
  1674. (@pxref{Procedures with Setters}).
  1675. @end defun
  1676. @node SRFI-18
  1677. @subsection SRFI-18 - Multithreading support
  1678. @cindex SRFI-18
  1679. This is an implementation of the SRFI-18 threading and synchronization
  1680. library. The functions and variables described here are provided by
  1681. @example
  1682. (use-modules (srfi srfi-18))
  1683. @end example
  1684. SRFI-18 defines facilities for threads, mutexes, condition variables,
  1685. time, and exception handling. Because these facilities are at a higher
  1686. level than Guile's primitives, they are implemented as a layer on top of
  1687. what Guile provides. In particular this means that a Guile mutex is not
  1688. a SRFI-18 mutex, and a Guile thread is not a SRFI-18 thread, and so on.
  1689. Guile provides a set of primitives and SRFI-18 is one of the systems built in terms of those primitives.
  1690. @menu
  1691. * SRFI-18 Threads:: Executing code
  1692. * SRFI-18 Mutexes:: Mutual exclusion devices
  1693. * SRFI-18 Condition variables:: Synchronizing of groups of threads
  1694. * SRFI-18 Time:: Representation of times and durations
  1695. * SRFI-18 Exceptions:: Signalling and handling errors
  1696. @end menu
  1697. @node SRFI-18 Threads
  1698. @subsubsection SRFI-18 Threads
  1699. Threads created by SRFI-18 differ in two ways from threads created by
  1700. Guile's built-in thread functions. First, a thread created by SRFI-18
  1701. @code{make-thread} begins in a blocked state and will not start
  1702. execution until @code{thread-start!} is called on it. Second, SRFI-18
  1703. threads are constructed with a top-level exception handler that
  1704. captures any exceptions that are thrown on thread exit.
  1705. SRFI-18 threads are disjoint from Guile's primitive threads.
  1706. @xref{Threads}, for more on Guile's primitive facility.
  1707. @defun current-thread
  1708. Returns the thread that called this function. This is the same
  1709. procedure as the same-named built-in procedure @code{current-thread}
  1710. (@pxref{Threads}).
  1711. @end defun
  1712. @defun thread? obj
  1713. Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This
  1714. is the same procedure as the same-named built-in procedure
  1715. @code{thread?} (@pxref{Threads}).
  1716. @end defun
  1717. @defun make-thread thunk [name]
  1718. Call @code{thunk} in a new thread and with a new dynamic state,
  1719. returning the new thread and optionally assigning it the object name
  1720. @var{name}, which may be any Scheme object.
  1721. Note that the name @code{make-thread} conflicts with the
  1722. @code{(ice-9 threads)} function @code{make-thread}. Applications
  1723. wanting to use both of these functions will need to refer to them by
  1724. different names.
  1725. @end defun
  1726. @defun thread-name thread
  1727. Returns the name assigned to @var{thread} at the time of its creation,
  1728. or @code{#f} if it was not given a name.
  1729. @end defun
  1730. @defun thread-specific thread
  1731. @defunx thread-specific-set! thread obj
  1732. Get or set the ``object-specific'' property of @var{thread}. In
  1733. Guile's implementation of SRFI-18, this value is stored as an object
  1734. property, and will be @code{#f} if not set.
  1735. @end defun
  1736. @defun thread-start! thread
  1737. Unblocks @var{thread} and allows it to begin execution if it has not
  1738. done so already.
  1739. @end defun
  1740. @defun thread-yield!
  1741. If one or more threads are waiting to execute, calling
  1742. @code{thread-yield!} forces an immediate context switch to one of them.
  1743. Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!}
  1744. behaves identically to the Guile built-in function @code{yield}.
  1745. @end defun
  1746. @defun thread-sleep! timeout
  1747. The current thread waits until the point specified by the time object
  1748. @var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the
  1749. thread only if @var{timeout} represents a point in the future. it is
  1750. an error for @var{timeout} to be @code{#f}.
  1751. @end defun
  1752. @defun thread-terminate! thread
  1753. Causes an abnormal termination of @var{thread}. If @var{thread} is
  1754. not already terminated, all mutexes owned by @var{thread} become
  1755. unlocked/abandoned. If @var{thread} is the current thread,
  1756. @code{thread-terminate!} does not return. Otherwise
  1757. @code{thread-terminate!} returns an unspecified value; the termination
  1758. of @var{thread} will occur before @code{thread-terminate!} returns.
  1759. Subsequent attempts to join on @var{thread} will cause a ``terminated
  1760. thread exception'' to be raised.
  1761. @code{thread-terminate!} is compatible with the thread cancellation
  1762. procedures in the core threads API (@pxref{Threads}) in that if a
  1763. cleanup handler has been installed for the target thread, it will be
  1764. called before the thread exits and its return value (or exception, if
  1765. any) will be stored for later retrieval via a call to
  1766. @code{thread-join!}.
  1767. @end defun
  1768. @defun thread-join! thread [timeout [timeout-val]]
  1769. Wait for @var{thread} to terminate and return its exit value. When a
  1770. time value @var{timeout} is given, it specifies a point in time where
  1771. the waiting should be aborted. When the waiting is aborted,
  1772. @var{timeout-val} is returned if it is specified; otherwise, a
  1773. @code{join-timeout-exception} exception is raised
  1774. (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
  1775. thread was terminated by a call to @code{thread-terminate!}
  1776. (@code{terminated-thread-exception} will be raised) or if the thread
  1777. exited by raising an exception that was handled by the top-level
  1778. exception handler (@code{uncaught-exception} will be raised; the
  1779. original exception can be retrieved using
  1780. @code{uncaught-exception-reason}).
  1781. @end defun
  1782. @node SRFI-18 Mutexes
  1783. @subsubsection SRFI-18 Mutexes
  1784. SRFI-18 mutexes are disjoint from Guile's primitive mutexes.
  1785. @xref{Mutexes and Condition Variables}, for more on Guile's primitive
  1786. facility.
  1787. @defun make-mutex [name]
  1788. Returns a new mutex, optionally assigning it the object name @var{name},
  1789. which may be any Scheme object. The returned mutex will be created with
  1790. the configuration described above.
  1791. @end defun
  1792. @defun mutex-name mutex
  1793. Returns the name assigned to @var{mutex} at the time of its creation, or
  1794. @code{#f} if it was not given a name.
  1795. @end defun
  1796. @defun mutex-specific mutex
  1797. Return the ``object-specific'' property of @var{mutex}, or @code{#f} if
  1798. none is set.
  1799. @end defun
  1800. @defun mutex-specific-set! mutex obj
  1801. Set the ``object-specific'' property of @var{mutex}.
  1802. @end defun
  1803. @defun mutex-state mutex
  1804. Returns information about the state of @var{mutex}. Possible values
  1805. are:
  1806. @itemize @bullet
  1807. @item
  1808. thread @var{t}: the mutex is in the locked/owned state and thread
  1809. @var{t} is the owner of the mutex
  1810. @item
  1811. symbol @code{not-owned}: the mutex is in the locked/not-owned state
  1812. @item
  1813. symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
  1814. @item
  1815. symbol @code{not-abandoned}: the mutex is in the
  1816. unlocked/not-abandoned state
  1817. @end itemize
  1818. @end defun
  1819. @defun mutex-lock! mutex [timeout [thread]]
  1820. Lock @var{mutex}, optionally specifying a time object @var{timeout}
  1821. after which to abort the lock attempt and a thread @var{thread} giving
  1822. a new owner for @var{mutex} different than the current thread.
  1823. @end defun
  1824. @defun mutex-unlock! mutex [condition-variable [timeout]]
  1825. Unlock @var{mutex}, optionally specifying a condition variable
  1826. @var{condition-variable} on which to wait, either indefinitely or,
  1827. optionally, until the time object @var{timeout} has passed, to be
  1828. signalled.
  1829. @end defun
  1830. @node SRFI-18 Condition variables
  1831. @subsubsection SRFI-18 Condition variables
  1832. SRFI-18 does not specify a ``wait'' function for condition variables.
  1833. Waiting on a condition variable can be simulated using the SRFI-18
  1834. @code{mutex-unlock!} function described in the previous section.
  1835. SRFI-18 condition variables are disjoint from Guile's primitive
  1836. condition variables. @xref{Mutexes and Condition Variables}, for more
  1837. on Guile's primitive facility.
  1838. @defun condition-variable? obj
  1839. Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
  1840. otherwise.
  1841. @end defun
  1842. @defun make-condition-variable [name]
  1843. Returns a new condition variable, optionally assigning it the object
  1844. name @var{name}, which may be any Scheme object.
  1845. @end defun
  1846. @defun condition-variable-name condition-variable
  1847. Returns the name assigned to @var{condition-variable} at the time of its
  1848. creation, or @code{#f} if it was not given a name.
  1849. @end defun
  1850. @defun condition-variable-specific condition-variable
  1851. Return the ``object-specific'' property of @var{condition-variable}, or
  1852. @code{#f} if none is set.
  1853. @end defun
  1854. @defun condition-variable-specific-set! condition-variable obj
  1855. Set the ``object-specific'' property of @var{condition-variable}.
  1856. @end defun
  1857. @defun condition-variable-signal! condition-variable
  1858. @defunx condition-variable-broadcast! condition-variable
  1859. Wake up one thread that is waiting for @var{condition-variable}, in
  1860. the case of @code{condition-variable-signal!}, or all threads waiting
  1861. for it, in the case of @code{condition-variable-broadcast!}.
  1862. @end defun
  1863. @node SRFI-18 Time
  1864. @subsubsection SRFI-18 Time
  1865. The SRFI-18 time functions manipulate time in two formats: a
  1866. ``time object'' type that represents an absolute point in time in some
  1867. implementation-specific way; and the number of seconds since some
  1868. unspecified ``epoch''. In Guile's implementation, the epoch is the
  1869. Unix epoch, 00:00:00 UTC, January 1, 1970.
  1870. @defun current-time
  1871. Return the current time as a time object. This procedure replaces
  1872. the procedure of the same name in the core library, which returns the
  1873. current time in seconds since the epoch.
  1874. @end defun
  1875. @defun time? obj
  1876. Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
  1877. @end defun
  1878. @defun time->seconds time
  1879. @defunx seconds->time seconds
  1880. Convert between time objects and numerical values representing the
  1881. number of seconds since the epoch. When converting from a time object
  1882. to seconds, the return value is the number of seconds between
  1883. @var{time} and the epoch. When converting from seconds to a time
  1884. object, the return value is a time object that represents a time
  1885. @var{seconds} seconds after the epoch.
  1886. @end defun
  1887. @node SRFI-18 Exceptions
  1888. @subsubsection SRFI-18 Exceptions
  1889. SRFI-18 exceptions are identical to the exceptions provided by
  1890. Guile's implementation of SRFI-34. The behavior of exception
  1891. handlers invoked to handle exceptions thrown from SRFI-18 functions,
  1892. however, differs from the conventional behavior of SRFI-34 in that
  1893. the continuation of the handler is the same as that of the call to
  1894. the function. Handlers are called in a tail-recursive manner; the
  1895. exceptions do not ``bubble up''.
  1896. @defun current-exception-handler
  1897. Returns the current exception handler.
  1898. @end defun
  1899. @defun with-exception-handler handler thunk
  1900. Installs @var{handler} as the current exception handler and calls the
  1901. procedure @var{thunk} with no arguments, returning its value as the
  1902. value of the exception. @var{handler} must be a procedure that accepts
  1903. a single argument. The current exception handler at the time this
  1904. procedure is called will be restored after the call returns.
  1905. @end defun
  1906. @defun raise obj
  1907. Raise @var{obj} as an exception. This is the same procedure as the
  1908. same-named procedure defined in SRFI 34.
  1909. @end defun
  1910. @defun join-timeout-exception? obj
  1911. Returns @code{#t} if @var{obj} is an exception raised as the result of
  1912. performing a timed join on a thread that does not exit within the
  1913. specified timeout, @code{#f} otherwise.
  1914. @end defun
  1915. @defun abandoned-mutex-exception? obj
  1916. Returns @code{#t} if @var{obj} is an exception raised as the result of
  1917. attempting to lock a mutex that has been abandoned by its owner thread,
  1918. @code{#f} otherwise.
  1919. @end defun
  1920. @defun terminated-thread-exception? obj
  1921. Returns @code{#t} if @var{obj} is an exception raised as the result of
  1922. joining on a thread that exited as the result of a call to
  1923. @code{thread-terminate!}.
  1924. @end defun
  1925. @defun uncaught-exception? obj
  1926. @defunx uncaught-exception-reason exc
  1927. @code{uncaught-exception?} returns @code{#t} if @var{obj} is an
  1928. exception thrown as the result of joining a thread that exited by
  1929. raising an exception that was handled by the top-level exception
  1930. handler installed by @code{make-thread}. When this occurs, the
  1931. original exception is preserved as part of the exception thrown by
  1932. @code{thread-join!} and can be accessed by calling
  1933. @code{uncaught-exception-reason} on that exception. Note that
  1934. because this exception-preservation mechanism is a side-effect of
  1935. @code{make-thread}, joining on threads that exited as described above
  1936. but were created by other means will not raise this
  1937. @code{uncaught-exception} error.
  1938. @end defun
  1939. @node SRFI-19
  1940. @subsection SRFI-19 - Time/Date Library
  1941. @cindex SRFI-19
  1942. @cindex time
  1943. @cindex date
  1944. This is an implementation of the SRFI-19 time/date library. The
  1945. functions and variables described here are provided by
  1946. @example
  1947. (use-modules (srfi srfi-19))
  1948. @end example
  1949. @menu
  1950. * SRFI-19 Introduction::
  1951. * SRFI-19 Time::
  1952. * SRFI-19 Date::
  1953. * SRFI-19 Time/Date conversions::
  1954. * SRFI-19 Date to string::
  1955. * SRFI-19 String to date::
  1956. @end menu
  1957. @node SRFI-19 Introduction
  1958. @subsubsection SRFI-19 Introduction
  1959. @cindex universal time
  1960. @cindex atomic time
  1961. @cindex UTC
  1962. @cindex TAI
  1963. This module implements time and date representations and calculations,
  1964. in various time systems, including Coordinated Universal Time (UTC)
  1965. and International Atomic Time (TAI).
  1966. For those not familiar with these time systems, TAI is based on a
  1967. fixed length second derived from oscillations of certain atoms. UTC
  1968. differs from TAI by an integral number of seconds, which is increased
  1969. or decreased at announced times to keep UTC aligned to a mean solar
  1970. day (the orbit and rotation of the earth are not quite constant).
  1971. @cindex leap second
  1972. So far, only increases in the TAI
  1973. @tex
  1974. $\leftrightarrow$
  1975. @end tex
  1976. @ifnottex
  1977. <->
  1978. @end ifnottex
  1979. UTC difference have been needed. Such an increase is a ``leap
  1980. second'', an extra second of TAI introduced at the end of a UTC day.
  1981. When working entirely within UTC this is never seen, every day simply
  1982. has 86400 seconds. But when converting from TAI to a UTC date, an
  1983. extra 23:59:60 is present, where normally a day would end at 23:59:59.
  1984. Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
  1985. seconds.
  1986. @cindex system clock
  1987. In the current implementation, the system clock is assumed to be UTC,
  1988. and a table of leap seconds in the code converts to TAI. See comments
  1989. in @file{srfi-19.scm} for how to update this table.
  1990. @cindex julian day
  1991. @cindex modified julian day
  1992. Also, for those not familiar with the terminology, a @dfn{Julian Day}
  1993. represents a point in time as a real number of days since
  1994. -4713-11-24T12:00:00Z, i.e.@: midday UT on 24 November 4714 BC in the
  1995. proleptic Gregorian calendar (1 January 4713 BC in the proleptic Julian
  1996. calendar).
  1997. A @dfn{Modified Julian Day} represents a point in time as a real number
  1998. of days since 1858-11-17T00:00:00Z, i.e.@: midnight UT on Wednesday 17
  1999. November AD 1858. That time is julian day 2400000.5.
  2000. @node SRFI-19 Time
  2001. @subsubsection SRFI-19 Time
  2002. @cindex time
  2003. A @dfn{time} object has type, seconds and nanoseconds fields
  2004. representing a point in time starting from some epoch. This is an
  2005. arbitrary point in time, not just a time of day. Although times are
  2006. represented in nanoseconds, the actual resolution may be lower.
  2007. The following variables hold the possible time types. For instance
  2008. @code{(current-time time-process)} would give the current CPU process
  2009. time.
  2010. @defvar time-utc
  2011. Universal Coordinated Time (UTC).
  2012. @cindex UTC
  2013. @end defvar
  2014. @defvar time-tai
  2015. International Atomic Time (TAI).
  2016. @cindex TAI
  2017. @end defvar
  2018. @defvar time-monotonic
  2019. Monotonic time, meaning a monotonically increasing time starting from
  2020. an unspecified epoch.
  2021. Note that in the current implementation @code{time-monotonic} is the
  2022. same as @code{time-tai}, and unfortunately is therefore affected by
  2023. adjustments to the system clock. Perhaps this will change in the
  2024. future.
  2025. @end defvar
  2026. @defvar time-duration
  2027. A duration, meaning simply a difference between two times.
  2028. @end defvar
  2029. @defvar time-process
  2030. CPU time spent in the current process, starting from when the process
  2031. began.
  2032. @cindex process time
  2033. @end defvar
  2034. @defvar time-thread
  2035. CPU time spent in the current thread. Not currently implemented.
  2036. @cindex thread time
  2037. @end defvar
  2038. @sp 1
  2039. @defun time? obj
  2040. Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
  2041. @end defun
  2042. @defun make-time type nanoseconds seconds
  2043. Create a time object with the given @var{type}, @var{seconds} and
  2044. @var{nanoseconds}.
  2045. @end defun
  2046. @defun time-type time
  2047. @defunx time-nanosecond time
  2048. @defunx time-second time
  2049. @defunx set-time-type! time type
  2050. @defunx set-time-nanosecond! time nsec
  2051. @defunx set-time-second! time sec
  2052. Get or set the type, seconds or nanoseconds fields of a time object.
  2053. @code{set-time-type!} merely changes the field, it doesn't convert the
  2054. time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
  2055. @end defun
  2056. @defun copy-time time
  2057. Return a new time object, which is a copy of the given @var{time}.
  2058. @end defun
  2059. @defun current-time [type]
  2060. Return the current time of the given @var{type}. The default
  2061. @var{type} is @code{time-utc}.
  2062. Note that the name @code{current-time} conflicts with the Guile core
  2063. @code{current-time} function (@pxref{Time}) as well as the SRFI-18
  2064. @code{current-time} function (@pxref{SRFI-18 Time}). Applications
  2065. wanting to use more than one of these functions will need to refer to
  2066. them by different names.
  2067. @end defun
  2068. @defun time-resolution [type]
  2069. Return the resolution, in nanoseconds, of the given time @var{type}.
  2070. The default @var{type} is @code{time-utc}.
  2071. @end defun
  2072. @defun time<=? t1 t2
  2073. @defunx time<? t1 t2
  2074. @defunx time=? t1 t2
  2075. @defunx time>=? t1 t2
  2076. @defunx time>? t1 t2
  2077. Return @code{#t} or @code{#f} according to the respective relation
  2078. between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
  2079. must be the same time type.
  2080. @end defun
  2081. @defun time-difference t1 t2
  2082. @defunx time-difference! t1 t2
  2083. Return a time object of type @code{time-duration} representing the
  2084. period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
  2085. the same time type.
  2086. @code{time-difference} returns a new time object,
  2087. @code{time-difference!} may modify @var{t1} to form its return.
  2088. @end defun
  2089. @defun add-duration time duration
  2090. @defunx add-duration! time duration
  2091. @defunx subtract-duration time duration
  2092. @defunx subtract-duration! time duration
  2093. Return a time object which is @var{time} with the given @var{duration}
  2094. added or subtracted. @var{duration} must be a time object of type
  2095. @code{time-duration}.
  2096. @code{add-duration} and @code{subtract-duration} return a new time
  2097. object. @code{add-duration!} and @code{subtract-duration!} may modify
  2098. the given @var{time} to form their return.
  2099. @end defun
  2100. @node SRFI-19 Date
  2101. @subsubsection SRFI-19 Date
  2102. @cindex date
  2103. A @dfn{date} object represents a date in the Gregorian calendar and a
  2104. time of day on that date in some timezone.
  2105. The fields are year, month, day, hour, minute, second, nanoseconds and
  2106. timezone. A date object is immutable, its fields can be read but they
  2107. cannot be modified once the object is created.
  2108. Historically, the Gregorian calendar was only used from the latter part
  2109. of the year 1582 onwards, and not until even later in many countries.
  2110. Prior to that most countries used the Julian calendar. SRFI-19 does
  2111. not deal with the Julian calendar at all, and so does not reflect this
  2112. historical calendar reform. Instead it projects the Gregorian calendar
  2113. back proleptically as far as necessary. When dealing with historical
  2114. data, especially prior to the British Empire's adoption of the Gregorian
  2115. calendar in 1752, one should be mindful of which calendar is used in
  2116. each context, and apply non-SRFI-19 facilities to convert where necessary.
  2117. @defun date? obj
  2118. Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
  2119. @end defun
  2120. @defun make-date nsecs seconds minutes hours date month year zone-offset
  2121. Create a new date object.
  2122. @c
  2123. @c FIXME: What can we say about the ranges of the values. The
  2124. @c current code looks it doesn't normalize, but expects then in their
  2125. @c usual range already.
  2126. @c
  2127. @end defun
  2128. @defun date-nanosecond date
  2129. Nanoseconds, 0 to 999999999.
  2130. @end defun
  2131. @defun date-second date
  2132. Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
  2133. entirely within UTC, it's only when converting to or from TAI.
  2134. @end defun
  2135. @defun date-minute date
  2136. Minutes, 0 to 59.
  2137. @end defun
  2138. @defun date-hour date
  2139. Hour, 0 to 23.
  2140. @end defun
  2141. @defun date-day date
  2142. Day of the month, 1 to 31 (or less, according to the month).
  2143. @end defun
  2144. @defun date-month date
  2145. Month, 1 to 12.
  2146. @end defun
  2147. @defun date-year date
  2148. Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
  2149. B.C. There is no year 0, year @math{-1} is followed by year 1.
  2150. @end defun
  2151. @defun date-zone-offset date
  2152. Time zone, an integer number of seconds east of Greenwich.
  2153. @end defun
  2154. @defun date-year-day date
  2155. Day of the year, starting from 1 for 1st January.
  2156. @end defun
  2157. @defun date-week-day date
  2158. Day of the week, starting from 0 for Sunday.
  2159. @end defun
  2160. @defun date-week-number date dstartw
  2161. Week of the year, ignoring a first partial week. @var{dstartw} is the
  2162. day of the week which is taken to start a week, 0 for Sunday, 1 for
  2163. Monday, etc.
  2164. @c
  2165. @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
  2166. @c The code looks like it's 0, if that's the correct intention.
  2167. @c
  2168. @end defun
  2169. @c The SRFI text doesn't actually give the default for tz-offset, but
  2170. @c the reference implementation has the local timezone and the
  2171. @c conversions functions all specify that, so it should be ok to
  2172. @c document it here.
  2173. @c
  2174. @defun current-date [tz-offset]
  2175. Return a date object representing the current date/time, in UTC offset
  2176. by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
  2177. defaults to the local timezone.
  2178. @end defun
  2179. @defun current-julian-day
  2180. @cindex julian day
  2181. Return the current Julian Day.
  2182. @end defun
  2183. @defun current-modified-julian-day
  2184. @cindex modified julian day
  2185. Return the current Modified Julian Day.
  2186. @end defun
  2187. @node SRFI-19 Time/Date conversions
  2188. @subsubsection SRFI-19 Time/Date conversions
  2189. @cindex time conversion
  2190. @cindex date conversion
  2191. @defun date->julian-day date
  2192. @defunx date->modified-julian-day date
  2193. @defunx date->time-monotonic date
  2194. @defunx date->time-tai date
  2195. @defunx date->time-utc date
  2196. @end defun
  2197. @defun julian-day->date jdn [tz-offset]
  2198. @defunx julian-day->time-monotonic jdn
  2199. @defunx julian-day->time-tai jdn
  2200. @defunx julian-day->time-utc jdn
  2201. @end defun
  2202. @defun modified-julian-day->date jdn [tz-offset]
  2203. @defunx modified-julian-day->time-monotonic jdn
  2204. @defunx modified-julian-day->time-tai jdn
  2205. @defunx modified-julian-day->time-utc jdn
  2206. @end defun
  2207. @defun time-monotonic->date time [tz-offset]
  2208. @defunx time-monotonic->time-tai time
  2209. @defunx time-monotonic->time-tai! time
  2210. @defunx time-monotonic->time-utc time
  2211. @defunx time-monotonic->time-utc! time
  2212. @end defun
  2213. @defun time-tai->date time [tz-offset]
  2214. @defunx time-tai->julian-day time
  2215. @defunx time-tai->modified-julian-day time
  2216. @defunx time-tai->time-monotonic time
  2217. @defunx time-tai->time-monotonic! time
  2218. @defunx time-tai->time-utc time
  2219. @defunx time-tai->time-utc! time
  2220. @end defun
  2221. @defun time-utc->date time [tz-offset]
  2222. @defunx time-utc->julian-day time
  2223. @defunx time-utc->modified-julian-day time
  2224. @defunx time-utc->time-monotonic time
  2225. @defunx time-utc->time-monotonic! time
  2226. @defunx time-utc->time-tai time
  2227. @defunx time-utc->time-tai! time
  2228. @sp 1
  2229. Convert between dates, times and days of the respective types. For
  2230. instance @code{time-tai->time-utc} accepts a @var{time} object of type
  2231. @code{time-tai} and returns an object of type @code{time-utc}.
  2232. The @code{!} variants may modify their @var{time} argument to form
  2233. their return. The plain functions create a new object.
  2234. For conversions to dates, @var{tz-offset} is seconds east of
  2235. Greenwich. The default is the local timezone, at the given time, as
  2236. provided by the system, using @code{localtime} (@pxref{Time}).
  2237. On 32-bit systems, @code{localtime} is limited to a 32-bit
  2238. @code{time_t}, so a default @var{tz-offset} is only available for
  2239. times between Dec 1901 and Jan 2038. For prior dates an application
  2240. might like to use the value in 1902, though some locations have zone
  2241. changes prior to that. For future dates an application might like to
  2242. assume today's rules extend indefinitely. But for correct daylight
  2243. savings transitions it will be necessary to take an offset for the
  2244. same day and time but a year in range and which has the same starting
  2245. weekday and same leap/non-leap (to support rules like last Sunday in
  2246. October).
  2247. @end defun
  2248. @node SRFI-19 Date to string
  2249. @subsubsection SRFI-19 Date to string
  2250. @cindex date to string
  2251. @cindex string, from date
  2252. @defun date->string date [format]
  2253. Convert a date to a string under the control of a format.
  2254. @var{format} should be a string containing @samp{~} escapes, which
  2255. will be expanded as per the following conversion table. The default
  2256. @var{format} is @samp{~c}, a locale-dependent date and time.
  2257. Many of these conversion characters are the same as POSIX
  2258. @code{strftime} (@pxref{Time}), but there are some extras and some
  2259. variations.
  2260. @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
  2261. @item @nicode{~~} @tab literal ~
  2262. @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
  2263. @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
  2264. @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
  2265. @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
  2266. @item @nicode{~c} @tab locale date and time, eg.@: @*
  2267. @samp{Fri Jul 14 20:28:42-0400 2000}
  2268. @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
  2269. @c Spec says d/m/y, reference implementation says m/d/y.
  2270. @c Apparently the reference code was the intention, but would like to
  2271. @c see an errata published for the spec before contradicting it here.
  2272. @c
  2273. @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
  2274. @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
  2275. @item @nicode{~f} @tab seconds and fractional seconds,
  2276. with locale decimal point, eg.@: @samp{5.2}
  2277. @item @nicode{~h} @tab same as @nicode{~b}
  2278. @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
  2279. @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
  2280. @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
  2281. @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
  2282. @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
  2283. @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
  2284. @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
  2285. @item @nicode{~n} @tab newline
  2286. @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
  2287. @item @nicode{~p} @tab locale AM or PM
  2288. @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
  2289. @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
  2290. @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
  2291. (usual limit is 59, 60 is a leap second)
  2292. @item @nicode{~t} @tab horizontal tab character
  2293. @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
  2294. @item @nicode{~U} @tab week of year, Sunday first day of week,
  2295. @samp{00} to @samp{52}
  2296. @item @nicode{~V} @tab week of year, Monday first day of week,
  2297. @samp{01} to @samp{53}
  2298. @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
  2299. @item @nicode{~W} @tab week of year, Monday first day of week,
  2300. @samp{00} to @samp{52}
  2301. @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
  2302. @c date. The reference code has ~x as the locale date and ~X as a
  2303. @c locale time. The rule is apparently that the code should be
  2304. @c believed, but would like to see an errata for the spec before
  2305. @c contradicting it here.
  2306. @c
  2307. @c @item @nicode{~x} @tab week of year, Monday as first day of week,
  2308. @c @samp{00} to @samp{53}
  2309. @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
  2310. @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
  2311. @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
  2312. @item @nicode{~z} @tab time zone, RFC-822 style
  2313. @item @nicode{~Z} @tab time zone symbol (not currently implemented)
  2314. @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
  2315. @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~H:~M:~S~z}
  2316. @item @nicode{~3} @tab ISO-8601 time, @samp{~H:~M:~S}
  2317. @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~H:~M:~S~z}
  2318. @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~H:~M:~S}
  2319. @end multitable
  2320. @end defun
  2321. Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
  2322. described here, since the specification and reference implementation
  2323. differ.
  2324. Conversion is locale-dependent on systems that support it
  2325. (@pxref{Accessing Locale Information}). @xref{Locales,
  2326. @code{setlocale}}, for information on how to change the current
  2327. locale.
  2328. @node SRFI-19 String to date
  2329. @subsubsection SRFI-19 String to date
  2330. @cindex string to date
  2331. @cindex date, from string
  2332. @c FIXME: Can we say what happens when an incomplete date is
  2333. @c converted? I.e. fields left as 0, or what? The spec seems to be
  2334. @c silent on this.
  2335. @defun string->date input template
  2336. Convert an @var{input} string to a date under the control of a
  2337. @var{template} string. Return a newly created date object.
  2338. Literal characters in @var{template} must match characters in
  2339. @var{input} and @samp{~} escapes must match the input forms described
  2340. in the table below. ``Skip to'' means characters up to one of the
  2341. given type are ignored, or ``no skip'' for no skipping. ``Read'' is
  2342. what's then read, and ``Set'' is the field affected in the date
  2343. object.
  2344. For example @samp{~Y} skips input characters until a digit is reached,
  2345. at which point it expects a year and stores that to the year field of
  2346. the date.
  2347. @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
  2348. @item
  2349. @tab Skip to
  2350. @tab Read
  2351. @tab Set
  2352. @item @nicode{~~}
  2353. @tab no skip
  2354. @tab literal ~
  2355. @tab nothing
  2356. @item @nicode{~a}
  2357. @tab @nicode{char-alphabetic?}
  2358. @tab locale abbreviated weekday name
  2359. @tab nothing
  2360. @item @nicode{~A}
  2361. @tab @nicode{char-alphabetic?}
  2362. @tab locale full weekday name
  2363. @tab nothing
  2364. @c Note that the SRFI spec says that ~b and ~B don't set anything,
  2365. @c but that looks like a mistake. The reference implementation sets
  2366. @c the month field, which seems sensible and is what we describe
  2367. @c here.
  2368. @item @nicode{~b}
  2369. @tab @nicode{char-alphabetic?}
  2370. @tab locale abbreviated month name
  2371. @tab @nicode{date-month}
  2372. @item @nicode{~B}
  2373. @tab @nicode{char-alphabetic?}
  2374. @tab locale full month name
  2375. @tab @nicode{date-month}
  2376. @item @nicode{~d}
  2377. @tab @nicode{char-numeric?}
  2378. @tab day of month
  2379. @tab @nicode{date-day}
  2380. @item @nicode{~e}
  2381. @tab no skip
  2382. @tab day of month, blank padded
  2383. @tab @nicode{date-day}
  2384. @item @nicode{~h}
  2385. @tab same as @samp{~b}
  2386. @item @nicode{~H}
  2387. @tab @nicode{char-numeric?}
  2388. @tab hour
  2389. @tab @nicode{date-hour}
  2390. @item @nicode{~k}
  2391. @tab no skip
  2392. @tab hour, blank padded
  2393. @tab @nicode{date-hour}
  2394. @item @nicode{~m}
  2395. @tab @nicode{char-numeric?}
  2396. @tab month
  2397. @tab @nicode{date-month}
  2398. @item @nicode{~M}
  2399. @tab @nicode{char-numeric?}
  2400. @tab minute
  2401. @tab @nicode{date-minute}
  2402. @item @nicode{~N}
  2403. @tab @nicode{char-numeric?}
  2404. @tab nanosecond
  2405. @tab @nicode{date-nanosecond}
  2406. @item @nicode{~S}
  2407. @tab @nicode{char-numeric?}
  2408. @tab second
  2409. @tab @nicode{date-second}
  2410. @item @nicode{~y}
  2411. @tab no skip
  2412. @tab 2-digit year
  2413. @tab @nicode{date-year} within 50 years
  2414. @item @nicode{~Y}
  2415. @tab @nicode{char-numeric?}
  2416. @tab year
  2417. @tab @nicode{date-year}
  2418. @item @nicode{~z}
  2419. @tab no skip
  2420. @tab time zone
  2421. @tab date-zone-offset
  2422. @end multitable
  2423. Notice that the weekday matching forms don't affect the date object
  2424. returned, instead the weekday will be derived from the day, month and
  2425. year.
  2426. Conversion is locale-dependent on systems that support it
  2427. (@pxref{Accessing Locale Information}). @xref{Locales,
  2428. @code{setlocale}}, for information on how to change the current
  2429. locale.
  2430. @end defun
  2431. @node SRFI-23
  2432. @subsection SRFI-23 - Error Reporting
  2433. @cindex SRFI-23
  2434. The SRFI-23 @code{error} procedure is always available.
  2435. @node SRFI-26
  2436. @subsection SRFI-26 - specializing parameters
  2437. @cindex SRFI-26
  2438. @cindex parameter specialize
  2439. @cindex argument specialize
  2440. @cindex specialize parameter
  2441. This SRFI provides a syntax for conveniently specializing selected
  2442. parameters of a function. It can be used with,
  2443. @example
  2444. (use-modules (srfi srfi-26))
  2445. @end example
  2446. @deffn {library syntax} cut slot1 slot2 @dots{}
  2447. @deffnx {library syntax} cute slot1 slot2 @dots{}
  2448. Return a new procedure which will make a call (@var{slot1} @var{slot2}
  2449. @dots{}) but with selected parameters specialized to given expressions.
  2450. An example will illustrate the idea. The following is a
  2451. specialization of @code{write}, sending output to
  2452. @code{my-output-port},
  2453. @example
  2454. (cut write <> my-output-port)
  2455. @result{}
  2456. (lambda (obj) (write obj my-output-port))
  2457. @end example
  2458. The special symbol @code{<>} indicates a slot to be filled by an
  2459. argument to the new procedure. @code{my-output-port} on the other
  2460. hand is an expression to be evaluated and passed, ie.@: it specializes
  2461. the behaviour of @code{write}.
  2462. @table @nicode
  2463. @item <>
  2464. A slot to be filled by an argument from the created procedure.
  2465. Arguments are assigned to @code{<>} slots in the order they appear in
  2466. the @code{cut} form, there's no way to re-arrange arguments.
  2467. The first argument to @code{cut} is usually a procedure (or expression
  2468. giving a procedure), but @code{<>} is allowed there too. For example,
  2469. @example
  2470. (cut <> 1 2 3)
  2471. @result{}
  2472. (lambda (proc) (proc 1 2 3))
  2473. @end example
  2474. @item <...>
  2475. A slot to be filled by all remaining arguments from the new procedure.
  2476. This can only occur at the end of a @code{cut} form.
  2477. For example, a procedure taking a variable number of arguments like
  2478. @code{max} but in addition enforcing a lower bound,
  2479. @example
  2480. (define my-lower-bound 123)
  2481. (cut max my-lower-bound <...>)
  2482. @result{}
  2483. (lambda arglist (apply max my-lower-bound arglist))
  2484. @end example
  2485. @end table
  2486. For @code{cut} the specializing expressions are evaluated each time
  2487. the new procedure is called. For @code{cute} they're evaluated just
  2488. once, when the new procedure is created. The name @code{cute} stands
  2489. for ``@code{cut} with evaluated arguments''. In all cases the
  2490. evaluations take place in an unspecified order.
  2491. The following illustrates the difference between @code{cut} and
  2492. @code{cute},
  2493. @example
  2494. (cut format <> "the time is ~s" (current-time))
  2495. @result{}
  2496. (lambda (port) (format port "the time is ~s" (current-time)))
  2497. (cute format <> "the time is ~s" (current-time))
  2498. @result{}
  2499. (let ((val (current-time)))
  2500. (lambda (port) (format port "the time is ~s" val))
  2501. @end example
  2502. (There's no provision for a mixture of @code{cut} and @code{cute}
  2503. where some expressions would be evaluated every time but others
  2504. evaluated only once.)
  2505. @code{cut} is really just a shorthand for the sort of @code{lambda}
  2506. forms shown in the above examples. But notice @code{cut} avoids the
  2507. need to name unspecialized parameters, and is more compact. Use in
  2508. functional programming style or just with @code{map}, @code{for-each}
  2509. or similar is typical.
  2510. @example
  2511. (map (cut * 2 <>) '(1 2 3 4))
  2512. (for-each (cut write <> my-port) my-list)
  2513. @end example
  2514. @end deffn
  2515. @node SRFI-27
  2516. @subsection SRFI-27 - Sources of Random Bits
  2517. @cindex SRFI-27
  2518. This subsection is based on the
  2519. @uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
  2520. SRFI-27} written by Sebastian Egner.
  2521. @c The copyright notice and license text of the SRFI-27 specification is
  2522. @c reproduced below:
  2523. @c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
  2524. @c Permission is hereby granted, free of charge, to any person obtaining a
  2525. @c copy of this software and associated documentation files (the
  2526. @c "Software"), to deal in the Software without restriction, including
  2527. @c without limitation the rights to use, copy, modify, merge, publish,
  2528. @c distribute, sublicense, and/or sell copies of the Software, and to
  2529. @c permit persons to whom the Software is furnished to do so, subject to
  2530. @c the following conditions:
  2531. @c The above copyright notice and this permission notice shall be included
  2532. @c in all copies or substantial portions of the Software.
  2533. @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  2534. @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  2535. @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  2536. @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  2537. @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  2538. @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  2539. @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  2540. This SRFI provides access to a (pseudo) random number generator; for
  2541. Guile's built-in random number facilities, which SRFI-27 is implemented
  2542. upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
  2543. @emph{random source}, which encapsulates a random number generation
  2544. algorithm and its state.
  2545. @menu
  2546. * SRFI-27 Default Random Source:: Obtaining random numbers
  2547. * SRFI-27 Random Sources:: Creating and manipulating random sources
  2548. * SRFI-27 Random Number Generators:: Obtaining random number generators
  2549. @end menu
  2550. @node SRFI-27 Default Random Source
  2551. @subsubsection The Default Random Source
  2552. @cindex SRFI-27
  2553. @defun random-integer n
  2554. Return a random number between zero (inclusive) and @var{n} (exclusive),
  2555. using the default random source. The numbers returned have a uniform
  2556. distribution.
  2557. @end defun
  2558. @defun random-real
  2559. Return a random number in (0,1), using the default random source. The
  2560. numbers returned have a uniform distribution.
  2561. @end defun
  2562. @defun default-random-source
  2563. A random source from which @code{random-integer} and @code{random-real}
  2564. have been derived using @code{random-source-make-integers} and
  2565. @code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
  2566. for those procedures). Note that an assignment to
  2567. @code{default-random-source} does not change @code{random-integer} or
  2568. @code{random-real}; it is also strongly recommended not to assign a new
  2569. value.
  2570. @end defun
  2571. @node SRFI-27 Random Sources
  2572. @subsubsection Random Sources
  2573. @cindex SRFI-27
  2574. @defun make-random-source
  2575. Create a new random source. The stream of random numbers obtained from
  2576. each random source created by this procedure will be identical, unless
  2577. its state is changed by one of the procedures below.
  2578. @end defun
  2579. @defun random-source? object
  2580. Tests whether @var{object} is a random source. Random sources are a
  2581. disjoint type.
  2582. @end defun
  2583. @defun random-source-randomize! source
  2584. Attempt to set the state of the random source to a truly random value.
  2585. The current implementation uses a seed based on the current system time.
  2586. @end defun
  2587. @defun random-source-pseudo-randomize! source i j
  2588. Changes the state of the random source s into the initial state of the
  2589. (@var{i}, @var{j})-th independent random source, where @var{i} and
  2590. @var{j} are non-negative integers. This procedure provides a mechanism
  2591. to obtain a large number of independent random sources (usually all
  2592. derived from the same backbone generator), indexed by two integers. In
  2593. contrast to @code{random-source-randomize!}, this procedure is entirely
  2594. deterministic.
  2595. @end defun
  2596. The state associated with a random state can be obtained an reinstated
  2597. with the following procedures:
  2598. @defun random-source-state-ref source
  2599. @defunx random-source-state-set! source state
  2600. Get and set the state of a random source. No assumptions should be made
  2601. about the nature of the state object, besides it having an external
  2602. representation (i.e.@: it can be passed to @code{write} and subsequently
  2603. @code{read} back).
  2604. @end defun
  2605. @node SRFI-27 Random Number Generators
  2606. @subsubsection Obtaining random number generator procedures
  2607. @cindex SRFI-27
  2608. @defun random-source-make-integers source
  2609. Obtains a procedure to generate random integers using the random source
  2610. @var{source}. The returned procedure takes a single argument @var{n},
  2611. which must be a positive integer, and returns the next uniformly
  2612. distributed random integer from the interval @{0, ..., @var{n}-1@} by
  2613. advancing the state of @var{source}.
  2614. If an application obtains and uses several generators for the same
  2615. random source @var{source}, a call to any of these generators advances
  2616. the state of @var{source}. Hence, the generators do not produce the
  2617. same sequence of random integers each but rather share a state. This
  2618. also holds for all other types of generators derived from a fixed random
  2619. sources.
  2620. While the SRFI text specifies that ``Implementations that support
  2621. concurrency make sure that the state of a generator is properly
  2622. advanced'', this is currently not the case in Guile's implementation of
  2623. SRFI-27, as it would cause a severe performance penalty. So in
  2624. multi-threaded programs, you either must perform locking on random
  2625. sources shared between threads yourself, or use different random sources
  2626. for multiple threads.
  2627. @end defun
  2628. @defun random-source-make-reals source
  2629. @defunx random-source-make-reals source unit
  2630. Obtains a procedure to generate random real numbers @math{0 < x < 1}
  2631. using the random source @var{source}. The procedure rand is called
  2632. without arguments.
  2633. The optional parameter @var{unit} determines the type of numbers being
  2634. produced by the returned procedure and the quantization of the output.
  2635. @var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
  2636. numbers created by the returned procedure are of the same numerical type
  2637. as @var{unit} and the potential output values are spaced by at most
  2638. @var{unit}. One can imagine rand to create numbers as @var{x} *
  2639. @var{unit} where @var{x} is a random integer in @{1, ...,
  2640. floor(1/unit)-1@}. Note, however, that this need not be the way the
  2641. values are actually created and that the actual resolution of rand can
  2642. be much higher than unit. In case @var{unit} is absent it defaults to a
  2643. reasonably small value (related to the width of the mantissa of an
  2644. efficient number format).
  2645. @end defun
  2646. @node SRFI-28
  2647. @subsection SRFI-28 - Basic Format Strings
  2648. @cindex SRFI-28
  2649. SRFI-28 provides a basic @code{format} procedure that provides only
  2650. the @code{~a}, @code{~s}, @code{~%}, and @code{~~} format specifiers.
  2651. You can import this procedure by using:
  2652. @lisp
  2653. (use-modules (srfi srfi-28))
  2654. @end lisp
  2655. @deffn {Scheme Procedure} format message arg @dots{}
  2656. Returns a formatted message, using @var{message} as the format string,
  2657. which can contain the following format specifiers:
  2658. @table @code
  2659. @item ~a
  2660. Insert the textual representation of the next @var{arg}, as if printed
  2661. by @code{display}.
  2662. @item ~s
  2663. Insert the textual representation of the next @var{arg}, as if printed
  2664. by @code{write}.
  2665. @item ~%
  2666. Insert a newline.
  2667. @item ~~
  2668. Insert a tilde.
  2669. @end table
  2670. This procedure is the same as calling @code{simple-format}
  2671. (@pxref{Simple Output}) with @code{#f} as the destination.
  2672. @end deffn
  2673. @node SRFI-30
  2674. @subsection SRFI-30 - Nested Multi-line Comments
  2675. @cindex SRFI-30
  2676. Starting from version 2.0, Guile's @code{read} supports SRFI-30/R6RS
  2677. nested multi-line comments by default, @ref{Block Comments}.
  2678. @node SRFI-31
  2679. @subsection SRFI-31 - A special form `rec' for recursive evaluation
  2680. @cindex SRFI-31
  2681. @cindex recursive expression
  2682. @findex rec
  2683. SRFI-31 defines a special form that can be used to create
  2684. self-referential expressions more conveniently. The syntax is as
  2685. follows:
  2686. @example
  2687. @group
  2688. <rec expression> --> (rec <variable> <expression>)
  2689. <rec expression> --> (rec (<variable>+) <body>)
  2690. @end group
  2691. @end example
  2692. The first syntax can be used to create self-referential expressions,
  2693. for example:
  2694. @lisp
  2695. guile> (define tmp (rec ones (cons 1 (delay ones))))
  2696. @end lisp
  2697. The second syntax can be used to create anonymous recursive functions:
  2698. @lisp
  2699. guile> (define tmp (rec (display-n item n)
  2700. (if (positive? n)
  2701. (begin (display n) (display-n (- n 1))))))
  2702. guile> (tmp 42 3)
  2703. 424242
  2704. guile>
  2705. @end lisp
  2706. @node SRFI-34
  2707. @subsection SRFI-34 - Exception handling for programs
  2708. @cindex SRFI-34
  2709. Guile provides an implementation of
  2710. @uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception
  2711. handling mechanisms} as an alternative to its own built-in mechanisms
  2712. (@pxref{Exceptions}). It can be made available as follows:
  2713. @lisp
  2714. (use-modules (srfi srfi-34))
  2715. @end lisp
  2716. @c FIXME: Document it.
  2717. @node SRFI-35
  2718. @subsection SRFI-35 - Conditions
  2719. @cindex SRFI-35
  2720. @cindex conditions
  2721. @cindex exceptions
  2722. @uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements
  2723. @dfn{conditions}, a data structure akin to records designed to convey
  2724. information about exceptional conditions between parts of a program. It
  2725. is normally used in conjunction with SRFI-34's @code{raise}:
  2726. @lisp
  2727. (raise (condition (&message
  2728. (message "An error occurred"))))
  2729. @end lisp
  2730. Users can define @dfn{condition types} containing arbitrary information.
  2731. Condition types may inherit from one another. This allows the part of
  2732. the program that handles (or ``catches'') conditions to get accurate
  2733. information about the exceptional condition that arose.
  2734. SRFI-35 conditions are made available using:
  2735. @lisp
  2736. (use-modules (srfi srfi-35))
  2737. @end lisp
  2738. The procedures available to manipulate condition types are the
  2739. following:
  2740. @deffn {Scheme Procedure} make-condition-type id parent field-names
  2741. Return a new condition type named @var{id}, inheriting from
  2742. @var{parent}, and with the fields whose names are listed in
  2743. @var{field-names}. @var{field-names} must be a list of symbols and must
  2744. not contain names already used by @var{parent} or one of its supertypes.
  2745. @end deffn
  2746. @deffn {Scheme Procedure} condition-type? obj
  2747. Return true if @var{obj} is a condition type.
  2748. @end deffn
  2749. Conditions can be created and accessed with the following procedures:
  2750. @deffn {Scheme Procedure} make-condition type . field+value
  2751. Return a new condition of type @var{type} with fields initialized as
  2752. specified by @var{field+value}, a sequence of field names (symbols) and
  2753. values as in the following example:
  2754. @lisp
  2755. (let ((&ct (make-condition-type 'foo &condition '(a b c))))
  2756. (make-condition &ct 'a 1 'b 2 'c 3))
  2757. @end lisp
  2758. Note that all fields of @var{type} and its supertypes must be specified.
  2759. @end deffn
  2760. @deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
  2761. Return a new compound condition composed of @var{condition1}
  2762. @var{condition2} @enddots{}. The returned condition has the type of
  2763. each condition of condition1 condition2 @dots{} (per
  2764. @code{condition-has-type?}).
  2765. @end deffn
  2766. @deffn {Scheme Procedure} condition-has-type? c type
  2767. Return true if condition @var{c} has type @var{type}.
  2768. @end deffn
  2769. @deffn {Scheme Procedure} condition-ref c field-name
  2770. Return the value of the field named @var{field-name} from condition @var{c}.
  2771. If @var{c} is a compound condition and several underlying condition
  2772. types contain a field named @var{field-name}, then the value of the
  2773. first such field is returned, using the order in which conditions were
  2774. passed to @code{make-compound-condition}.
  2775. @end deffn
  2776. @deffn {Scheme Procedure} extract-condition c type
  2777. Return a condition of condition type @var{type} with the field values
  2778. specified by @var{c}.
  2779. If @var{c} is a compound condition, extract the field values from the
  2780. subcondition belonging to @var{type} that appeared first in the call to
  2781. @code{make-compound-condition} that created the condition.
  2782. @end deffn
  2783. Convenience macros are also available to create condition types and
  2784. conditions.
  2785. @deffn {library syntax} define-condition-type type supertype predicate field-spec...
  2786. Define a new condition type named @var{type} that inherits from
  2787. @var{supertype}. In addition, bind @var{predicate} to a type predicate
  2788. that returns true when passed a condition of type @var{type} or any of
  2789. its subtypes. @var{field-spec} must have the form @code{(field
  2790. accessor)} where @var{field} is the name of field of @var{type} and
  2791. @var{accessor} is the name of a procedure to access field @var{field} in
  2792. conditions of type @var{type}.
  2793. The example below defines condition type @code{&foo}, inheriting from
  2794. @code{&condition} with fields @code{a}, @code{b} and @code{c}:
  2795. @lisp
  2796. (define-condition-type &foo &condition
  2797. foo-condition?
  2798. (a foo-a)
  2799. (b foo-b)
  2800. (c foo-c))
  2801. @end lisp
  2802. @end deffn
  2803. @deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{}
  2804. Return a new condition or compound condition, initialized according to
  2805. @var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each
  2806. @var{type-field-binding} must have the form @code{(type
  2807. field-specs...)}, where @var{type} is the name of a variable bound to a
  2808. condition type; each @var{field-spec} must have the form
  2809. @code{(field-name value)} where @var{field-name} is a symbol denoting
  2810. the field being initialized to @var{value}. As for
  2811. @code{make-condition}, all fields must be specified.
  2812. The following example returns a simple condition:
  2813. @lisp
  2814. (condition (&message (message "An error occurred")))
  2815. @end lisp
  2816. The one below returns a compound condition:
  2817. @lisp
  2818. (condition (&message (message "An error occurred"))
  2819. (&serious))
  2820. @end lisp
  2821. @end deffn
  2822. Finally, SRFI-35 defines a several standard condition types.
  2823. @defvar &condition
  2824. This condition type is the root of all condition types. It has no
  2825. fields.
  2826. @end defvar
  2827. @defvar &message
  2828. A condition type that carries a message describing the nature of the
  2829. condition to humans.
  2830. @end defvar
  2831. @deffn {Scheme Procedure} message-condition? c
  2832. Return true if @var{c} is of type @code{&message} or one of its
  2833. subtypes.
  2834. @end deffn
  2835. @deffn {Scheme Procedure} condition-message c
  2836. Return the message associated with message condition @var{c}.
  2837. @end deffn
  2838. @defvar &serious
  2839. This type describes conditions serious enough that they cannot safely be
  2840. ignored. It has no fields.
  2841. @end defvar
  2842. @deffn {Scheme Procedure} serious-condition? c
  2843. Return true if @var{c} is of type @code{&serious} or one of its
  2844. subtypes.
  2845. @end deffn
  2846. @defvar &error
  2847. This condition describes errors, typically caused by something that has
  2848. gone wrong in the interaction of the program with the external world or
  2849. the user.
  2850. @end defvar
  2851. @deffn {Scheme Procedure} error? c
  2852. Return true if @var{c} is of type @code{&error} or one of its subtypes.
  2853. @end deffn
  2854. @node SRFI-37
  2855. @subsection SRFI-37 - args-fold
  2856. @cindex SRFI-37
  2857. This is a processor for GNU @code{getopt_long}-style program
  2858. arguments. It provides an alternative, less declarative interface
  2859. than @code{getopt-long} in @code{(ice-9 getopt-long)}
  2860. (@pxref{getopt-long,,The (ice-9 getopt-long) Module}). Unlike
  2861. @code{getopt-long}, it supports repeated options and any number of
  2862. short and long names per option. Access it with:
  2863. @lisp
  2864. (use-modules (srfi srfi-37))
  2865. @end lisp
  2866. @acronym{SRFI}-37 principally provides an @code{option} type and the
  2867. @code{args-fold} function. To use the library, create a set of
  2868. options with @code{option} and use it as a specification for invoking
  2869. @code{args-fold}.
  2870. Here is an example of a simple argument processor for the typical
  2871. @samp{--version} and @samp{--help} options, which returns a backwards
  2872. list of files given on the command line:
  2873. @lisp
  2874. (args-fold (cdr (program-arguments))
  2875. (let ((display-and-exit-proc
  2876. (lambda (msg)
  2877. (lambda (opt name arg loads)
  2878. (display msg) (quit)))))
  2879. (list (option '(#\v "version") #f #f
  2880. (display-and-exit-proc "Foo version 42.0\n"))
  2881. (option '(#\h "help") #f #f
  2882. (display-and-exit-proc
  2883. "Usage: foo scheme-file ..."))))
  2884. (lambda (opt name arg loads)
  2885. (error "Unrecognized option `~A'" name))
  2886. (lambda (op loads) (cons op loads))
  2887. '())
  2888. @end lisp
  2889. @deffn {Scheme Procedure} option names required-arg? optional-arg? processor
  2890. Return an object that specifies a single kind of program option.
  2891. @var{names} is a list of command-line option names, and should consist of
  2892. characters for traditional @code{getopt} short options and strings for
  2893. @code{getopt_long}-style long options.
  2894. @var{required-arg?} and @var{optional-arg?} are mutually exclusive;
  2895. one or both must be @code{#f}. If @var{required-arg?}, the option
  2896. must be followed by an argument on the command line, such as
  2897. @samp{--opt=value} for long options, or an error will be signalled.
  2898. If @var{optional-arg?}, an argument will be taken if available.
  2899. @var{processor} is a procedure that takes at least 3 arguments, called
  2900. when @code{args-fold} encounters the option: the containing option
  2901. object, the name used on the command line, and the argument given for
  2902. the option (or @code{#f} if none). The rest of the arguments are
  2903. @code{args-fold} ``seeds'', and the @var{processor} should return
  2904. seeds as well.
  2905. @end deffn
  2906. @deffn {Scheme Procedure} option-names opt
  2907. @deffnx {Scheme Procedure} option-required-arg? opt
  2908. @deffnx {Scheme Procedure} option-optional-arg? opt
  2909. @deffnx {Scheme Procedure} option-processor opt
  2910. Return the specified field of @var{opt}, an option object, as
  2911. described above for @code{option}.
  2912. @end deffn
  2913. @deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{}
  2914. Process @var{args}, a list of program arguments such as that returned by
  2915. @code{(cdr (program-arguments))}, in order against @var{options}, a list
  2916. of option objects as described above. All functions called take the
  2917. ``seeds'', or the last multiple-values as multiple arguments, starting
  2918. with @var{seed} @dots{}, and must return the new seeds. Return the
  2919. final seeds.
  2920. Call @code{unrecognized-option-proc}, which is like an option object's
  2921. processor, for any options not found in @var{options}.
  2922. Call @code{operand-proc} with any items on the command line that are
  2923. not named options. This includes arguments after @samp{--}. It is
  2924. called with the argument in question, as well as the seeds.
  2925. @end deffn
  2926. @node SRFI-38
  2927. @subsection SRFI-38 - External Representation for Data With Shared Structure
  2928. @cindex SRFI-38
  2929. This subsection is based on
  2930. @uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
  2931. of SRFI-38} written by Ray Dillinger.
  2932. @c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
  2933. @c Permission is hereby granted, free of charge, to any person obtaining a
  2934. @c copy of this software and associated documentation files (the
  2935. @c "Software"), to deal in the Software without restriction, including
  2936. @c without limitation the rights to use, copy, modify, merge, publish,
  2937. @c distribute, sublicense, and/or sell copies of the Software, and to
  2938. @c permit persons to whom the Software is furnished to do so, subject to
  2939. @c the following conditions:
  2940. @c The above copyright notice and this permission notice shall be included
  2941. @c in all copies or substantial portions of the Software.
  2942. @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  2943. @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  2944. @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  2945. @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  2946. @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  2947. @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  2948. @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  2949. This SRFI creates an alternative external representation for data
  2950. written and read using @code{write-with-shared-structure} and
  2951. @code{read-with-shared-structure}. It is identical to the grammar for
  2952. external representation for data written and read with @code{write} and
  2953. @code{read} given in section 7 of R5RS, except that the single
  2954. production
  2955. @example
  2956. <datum> --> <simple datum> | <compound datum>
  2957. @end example
  2958. is replaced by the following five productions:
  2959. @example
  2960. <datum> --> <defining datum> | <nondefining datum> | <defined datum>
  2961. <defining datum> --> #<indexnum>=<nondefining datum>
  2962. <defined datum> --> #<indexnum>#
  2963. <nondefining datum> --> <simple datum> | <compound datum>
  2964. <indexnum> --> <digit 10>+
  2965. @end example
  2966. @deffn {Scheme procedure} write-with-shared-structure obj
  2967. @deffnx {Scheme procedure} write-with-shared-structure obj port
  2968. @deffnx {Scheme procedure} write-with-shared-structure obj port optarg
  2969. Writes an external representation of @var{obj} to the given port.
  2970. Strings that appear in the written representation are enclosed in
  2971. doublequotes, and within those strings backslash and doublequote
  2972. characters are escaped by backslashes. Character objects are written
  2973. using the @code{#\} notation.
  2974. Objects which denote locations rather than values (cons cells, vectors,
  2975. and non-zero-length strings in R5RS scheme; also Guile's structs,
  2976. bytevectors and ports and hash-tables), if they appear at more than one
  2977. point in the data being written, are preceded by @samp{#@var{N}=} the
  2978. first time they are written and replaced by @samp{#@var{N}#} all
  2979. subsequent times they are written, where @var{N} is a natural number
  2980. used to identify that particular object. If objects which denote
  2981. locations occur only once in the structure, then
  2982. @code{write-with-shared-structure} must produce the same external
  2983. representation for those objects as @code{write}.
  2984. @code{write-with-shared-structure} terminates in finite time and
  2985. produces a finite representation when writing finite data.
  2986. @code{write-with-shared-structure} returns an unspecified value. The
  2987. @var{port} argument may be omitted, in which case it defaults to the
  2988. value returned by @code{(current-output-port)}. The @var{optarg}
  2989. argument may also be omitted. If present, its effects on the output and
  2990. return value are unspecified but @code{write-with-shared-structure} must
  2991. still write a representation that can be read by
  2992. @code{read-with-shared-structure}. Some implementations may wish to use
  2993. @var{optarg} to specify formatting conventions, numeric radixes, or
  2994. return values. Guile's implementation ignores @var{optarg}.
  2995. For example, the code
  2996. @lisp
  2997. (begin (define a (cons 'val1 'val2))
  2998. (set-cdr! a a)
  2999. (write-with-shared-structure a))
  3000. @end lisp
  3001. should produce the output @code{#1=(val1 . #1#)}. This shows a cons
  3002. cell whose @code{cdr} contains itself.
  3003. @end deffn
  3004. @deffn {Scheme procedure} read-with-shared-structure
  3005. @deffnx {Scheme procedure} read-with-shared-structure port
  3006. @code{read-with-shared-structure} converts the external representations
  3007. of Scheme objects produced by @code{write-with-shared-structure} into
  3008. Scheme objects. That is, it is a parser for the nonterminal
  3009. @samp{<datum>} in the augmented external representation grammar defined
  3010. above. @code{read-with-shared-structure} returns the next object
  3011. parsable from the given input port, updating @var{port} to point to the
  3012. first character past the end of the external representation of the
  3013. object.
  3014. If an end-of-file is encountered in the input before any characters are
  3015. found that can begin an object, then an end-of-file object is returned.
  3016. The port remains open, and further attempts to read it (by
  3017. @code{read-with-shared-structure} or @code{read} will also return an
  3018. end-of-file object. If an end of file is encountered after the
  3019. beginning of an object's external representation, but the external
  3020. representation is incomplete and therefore not parsable, an error is
  3021. signalled.
  3022. The @var{port} argument may be omitted, in which case it defaults to the
  3023. value returned by @code{(current-input-port)}. It is an error to read
  3024. from a closed port.
  3025. @end deffn
  3026. @node SRFI-39
  3027. @subsection SRFI-39 - Parameters
  3028. @cindex SRFI-39
  3029. This SRFI adds support for dynamically-scoped parameters. SRFI 39 is
  3030. implemented in the Guile core; there's no module needed to get SRFI-39
  3031. itself. Parameters are documented in @ref{Parameters}.
  3032. This module does export one extra function: @code{with-parameters*}.
  3033. This is a Guile-specific addition to the SRFI, similar to the core
  3034. @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
  3035. @defun with-parameters* param-list value-list thunk
  3036. Establish a new dynamic scope, as per @code{parameterize} above,
  3037. taking parameters from @var{param-list} and corresponding values from
  3038. @var{value-list}. A call @code{(@var{thunk})} is made in the new
  3039. scope and the result from that @var{thunk} is the return from
  3040. @code{with-parameters*}.
  3041. @end defun
  3042. @node SRFI-41
  3043. @subsection SRFI-41 - Streams
  3044. @cindex SRFI-41
  3045. This subsection is based on the
  3046. @uref{http://srfi.schemers.org/srfi-41/srfi-41.html, specification of
  3047. SRFI-41} by Philip L.@: Bewig.
  3048. @c The copyright notice and license text of the SRFI-41 specification is
  3049. @c reproduced below:
  3050. @c Copyright (C) Philip L. Bewig (2007). All Rights Reserved.
  3051. @c Permission is hereby granted, free of charge, to any person obtaining a
  3052. @c copy of this software and associated documentation files (the
  3053. @c "Software"), to deal in the Software without restriction, including
  3054. @c without limitation the rights to use, copy, modify, merge, publish,
  3055. @c distribute, sublicense, and/or sell copies of the Software, and to
  3056. @c permit persons to whom the Software is furnished to do so, subject to
  3057. @c the following conditions:
  3058. @c The above copyright notice and this permission notice shall be included
  3059. @c in all copies or substantial portions of the Software.
  3060. @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  3061. @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  3062. @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  3063. @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  3064. @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  3065. @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  3066. @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  3067. @noindent
  3068. This SRFI implements streams, sometimes called lazy lists, a sequential
  3069. data structure containing elements computed only on demand. A stream is
  3070. either null or is a pair with a stream in its cdr. Since elements of a
  3071. stream are computed only when accessed, streams can be infinite. Once
  3072. computed, the value of a stream element is cached in case it is needed
  3073. again. SRFI-41 can be made available with:
  3074. @example
  3075. (use-modules (srfi srfi-41))
  3076. @end example
  3077. @menu
  3078. * SRFI-41 Stream Fundamentals::
  3079. * SRFI-41 Stream Primitives::
  3080. * SRFI-41 Stream Library::
  3081. @end menu
  3082. @node SRFI-41 Stream Fundamentals
  3083. @subsubsection SRFI-41 Stream Fundamentals
  3084. SRFI-41 Streams are based on two mutually-recursive abstract data types:
  3085. An object of the @code{stream} abstract data type is a promise that,
  3086. when forced, is either @code{stream-null} or is an object of type
  3087. @code{stream-pair}. An object of the @code{stream-pair} abstract data
  3088. type contains a @code{stream-car} and a @code{stream-cdr}, which must be
  3089. a @code{stream}. The essential feature of streams is the systematic
  3090. suspensions of the recursive promises between the two data types.
  3091. The object stored in the @code{stream-car} of a @code{stream-pair} is a
  3092. promise that is forced the first time the @code{stream-car} is accessed;
  3093. its value is cached in case it is needed again. The object may have any
  3094. type, and different stream elements may have different types. If the
  3095. @code{stream-car} is never accessed, the object stored there is never
  3096. evaluated. Likewise, the @code{stream-cdr} is a promise to return a
  3097. stream, and is only forced on demand.
  3098. @node SRFI-41 Stream Primitives
  3099. @subsubsection SRFI-41 Stream Primitives
  3100. This library provides eight operators: constructors for
  3101. @code{stream-null} and @code{stream-pair}s, type predicates for streams
  3102. and the two kinds of streams, accessors for both fields of a
  3103. @code{stream-pair}, and a lambda that creates procedures that return
  3104. streams.
  3105. @defvr {Scheme Variable} stream-null
  3106. A promise that, when forced, is a single object, distinguishable from
  3107. all other objects, that represents the null stream. @code{stream-null}
  3108. is immutable and unique.
  3109. @end defvr
  3110. @deffn {Scheme Syntax} stream-cons object-expr stream-expr
  3111. Creates a newly-allocated stream containing a promise that, when forced,
  3112. is a @code{stream-pair} with @var{object-expr} in its @code{stream-car}
  3113. and @var{stream-expr} in its @code{stream-cdr}. Neither
  3114. @var{object-expr} nor @var{stream-expr} is evaluated when
  3115. @code{stream-cons} is called.
  3116. Once created, a @code{stream-pair} is immutable; there is no
  3117. @code{stream-set-car!} or @code{stream-set-cdr!} that modifies an
  3118. existing stream-pair. There is no dotted-pair or improper stream as
  3119. with lists.
  3120. @end deffn
  3121. @deffn {Scheme Procedure} stream? object
  3122. Returns true if @var{object} is a stream, otherwise returns false. If
  3123. @var{object} is a stream, its promise will not be forced. If
  3124. @code{(stream? obj)} returns true, then one of @code{(stream-null? obj)}
  3125. or @code{(stream-pair? obj)} will return true and the other will return
  3126. false.
  3127. @end deffn
  3128. @deffn {Scheme Procedure} stream-null? object
  3129. Returns true if @var{object} is the distinguished null stream, otherwise
  3130. returns false. If @var{object} is a stream, its promise will be forced.
  3131. @end deffn
  3132. @deffn {Scheme Procedure} stream-pair? object
  3133. Returns true if @var{object} is a @code{stream-pair} constructed by
  3134. @code{stream-cons}, otherwise returns false. If @var{object} is a
  3135. stream, its promise will be forced.
  3136. @end deffn
  3137. @deffn {Scheme Procedure} stream-car stream
  3138. Returns the object stored in the @code{stream-car} of @var{stream}. An
  3139. error is signalled if the argument is not a @code{stream-pair}. This
  3140. causes the @var{object-expr} passed to @code{stream-cons} to be
  3141. evaluated if it had not yet been; the value is cached in case it is
  3142. needed again.
  3143. @end deffn
  3144. @deffn {Scheme Procedure} stream-cdr stream
  3145. Returns the stream stored in the @code{stream-cdr} of @var{stream}. An
  3146. error is signalled if the argument is not a @code{stream-pair}.
  3147. @end deffn
  3148. @deffn {Scheme Syntax} stream-lambda formals body @dots{}
  3149. Creates a procedure that returns a promise to evaluate the @var{body} of
  3150. the procedure. The last @var{body} expression to be evaluated must
  3151. yield a stream. As with normal @code{lambda}, @var{formals} may be a
  3152. single variable name, in which case all the formal arguments are
  3153. collected into a single list, or a list of variable names, which may be
  3154. null if there are no arguments, proper if there are an exact number of
  3155. arguments, or dotted if a fixed number of arguments is to be followed by
  3156. zero or more arguments collected into a list. @var{Body} must contain
  3157. at least one expression, and may contain internal definitions preceding
  3158. any expressions to be evaluated.
  3159. @end deffn
  3160. @example
  3161. (define strm123
  3162. (stream-cons 1
  3163. (stream-cons 2
  3164. (stream-cons 3
  3165. stream-null))))
  3166. (stream-car strm123) @result{} 1
  3167. (stream-car (stream-cdr strm123) @result{} 2
  3168. (stream-pair?
  3169. (stream-cdr
  3170. (stream-cons (/ 1 0) stream-null))) @result{} #f
  3171. (stream? (list 1 2 3)) @result{} #f
  3172. (define iter
  3173. (stream-lambda (f x)
  3174. (stream-cons x (iter f (f x)))))
  3175. (define nats (iter (lambda (x) (+ x 1)) 0))
  3176. (stream-car (stream-cdr nats)) @result{} 1
  3177. (define stream-add
  3178. (stream-lambda (s1 s2)
  3179. (stream-cons
  3180. (+ (stream-car s1) (stream-car s2))
  3181. (stream-add (stream-cdr s1)
  3182. (stream-cdr s2)))))
  3183. (define evens (stream-add nats nats))
  3184. (stream-car evens) @result{} 0
  3185. (stream-car (stream-cdr evens)) @result{} 2
  3186. (stream-car (stream-cdr (stream-cdr evens))) @result{} 4
  3187. @end example
  3188. @node SRFI-41 Stream Library
  3189. @subsubsection SRFI-41 Stream Library
  3190. @deffn {Scheme Syntax} define-stream (name args @dots{}) body @dots{}
  3191. Creates a procedure that returns a stream, and may appear anywhere a
  3192. normal @code{define} may appear, including as an internal definition.
  3193. It may contain internal definitions of its own. The defined procedure
  3194. takes arguments in the same way as @code{stream-lambda}.
  3195. @code{define-stream} is syntactic sugar on @code{stream-lambda}; see
  3196. also @code{stream-let}, which is also a sugaring of
  3197. @code{stream-lambda}.
  3198. A simple version of @code{stream-map} that takes only a single input
  3199. stream calls itself recursively:
  3200. @example
  3201. (define-stream (stream-map proc strm)
  3202. (if (stream-null? strm)
  3203. stream-null
  3204. (stream-cons
  3205. (proc (stream-car strm))
  3206. (stream-map proc (stream-cdr strm))))))
  3207. @end example
  3208. @end deffn
  3209. @deffn {Scheme Procedure} list->stream list
  3210. Returns a newly-allocated stream containing the elements from
  3211. @var{list}.
  3212. @end deffn
  3213. @deffn {Scheme Procedure} port->stream [port]
  3214. Returns a newly-allocated stream containing in its elements the
  3215. characters on the port. If @var{port} is not given it defaults to the
  3216. current input port. The returned stream has finite length and is
  3217. terminated by @code{stream-null}.
  3218. It looks like one use of @code{port->stream} would be this:
  3219. @example
  3220. (define s ;wrong!
  3221. (with-input-from-file filename
  3222. (lambda () (port->stream))))
  3223. @end example
  3224. But that fails, because @code{with-input-from-file} is eager, and closes
  3225. the input port prematurely, before the first character is read. To read
  3226. a file into a stream, say:
  3227. @example
  3228. (define-stream (file->stream filename)
  3229. (let ((p (open-input-file filename)))
  3230. (stream-let loop ((c (read-char p)))
  3231. (if (eof-object? c)
  3232. (begin (close-input-port p)
  3233. stream-null)
  3234. (stream-cons c
  3235. (loop (read-char p)))))))
  3236. @end example
  3237. @end deffn
  3238. @deffn {Scheme Syntax} stream object-expr @dots{}
  3239. Creates a newly-allocated stream containing in its elements the objects,
  3240. in order. The @var{object-expr}s are evaluated when they are accessed,
  3241. not when the stream is created. If no objects are given, as in
  3242. (stream), the null stream is returned. See also @code{list->stream}.
  3243. @example
  3244. (define strm123 (stream 1 2 3))
  3245. ; (/ 1 0) not evaluated when stream is created
  3246. (define s (stream 1 (/ 1 0) -1))
  3247. @end example
  3248. @end deffn
  3249. @deffn {Scheme Procedure} stream->list [n] stream
  3250. Returns a newly-allocated list containing in its elements the first
  3251. @var{n} items in @var{stream}. If @var{stream} has less than @var{n}
  3252. items, all the items in the stream will be included in the returned
  3253. list. If @var{n} is not given it defaults to infinity, which means that
  3254. unless @var{stream} is finite @code{stream->list} will never return.
  3255. @example
  3256. (stream->list 10
  3257. (stream-map (lambda (x) (* x x))
  3258. (stream-from 0)))
  3259. @result{} (0 1 4 9 16 25 36 49 64 81)
  3260. @end example
  3261. @end deffn
  3262. @deffn {Scheme Procedure} stream-append stream @dots{}
  3263. Returns a newly-allocated stream containing in its elements those
  3264. elements contained in its input @var{stream}s, in order of input. If
  3265. any of the input streams is infinite, no elements of any of the
  3266. succeeding input streams will appear in the output stream. See also
  3267. @code{stream-concat}.
  3268. @end deffn
  3269. @deffn {Scheme Procedure} stream-concat stream
  3270. Takes a @var{stream} consisting of one or more streams and returns a
  3271. newly-allocated stream containing all the elements of the input streams.
  3272. If any of the streams in the input @var{stream} is infinite, any
  3273. remaining streams in the input stream will never appear in the output
  3274. stream. See also @code{stream-append}.
  3275. @end deffn
  3276. @deffn {Scheme Procedure} stream-constant object @dots{}
  3277. Returns a newly-allocated stream containing in its elements the
  3278. @var{object}s, repeating in succession forever.
  3279. @example
  3280. (stream-constant 1) @result{} 1 1 1 @dots{}
  3281. (stream-constant #t #f) @result{} #t #f #t #f #t #f @dots{}
  3282. @end example
  3283. @end deffn
  3284. @deffn {Scheme Procedure} stream-drop n stream
  3285. Returns the suffix of the input @var{stream} that starts at the next
  3286. element after the first @var{n} elements. The output stream shares
  3287. structure with the input @var{stream}; thus, promises forced in one
  3288. instance of the stream are also forced in the other instance of the
  3289. stream. If the input @var{stream} has less than @var{n} elements,
  3290. @code{stream-drop} returns the null stream. See also
  3291. @code{stream-take}.
  3292. @end deffn
  3293. @deffn {Scheme Procedure} stream-drop-while pred stream
  3294. Returns the suffix of the input @var{stream} that starts at the first
  3295. element @var{x} for which @code{(pred x)} returns false. The output
  3296. stream shares structure with the input @var{stream}. See also
  3297. @code{stream-take-while}.
  3298. @end deffn
  3299. @deffn {Scheme Procedure} stream-filter pred stream
  3300. Returns a newly-allocated stream that contains only those elements
  3301. @var{x} of the input @var{stream} which satisfy the predicate
  3302. @code{pred}.
  3303. @example
  3304. (stream-filter odd? (stream-from 0))
  3305. @result{} 1 3 5 7 9 @dots{}
  3306. @end example
  3307. @end deffn
  3308. @deffn {Scheme Procedure} stream-fold proc base stream
  3309. Applies a binary procedure @var{proc} to @var{base} and the first
  3310. element of @var{stream} to compute a new @var{base}, then applies the
  3311. procedure to the new @var{base} and the next element of @var{stream} to
  3312. compute a succeeding @var{base}, and so on, accumulating a value that is
  3313. finally returned as the value of @code{stream-fold} when the end of the
  3314. stream is reached. @var{stream} must be finite, or @code{stream-fold}
  3315. will enter an infinite loop. See also @code{stream-scan}, which is
  3316. similar to @code{stream-fold}, but useful for infinite streams. For
  3317. readers familiar with other functional languages, this is a left-fold;
  3318. there is no corresponding right-fold, since right-fold relies on finite
  3319. streams that are fully-evaluated, in which case they may as well be
  3320. converted to a list.
  3321. @end deffn
  3322. @deffn {Scheme Procedure} stream-for-each proc stream @dots{}
  3323. Applies @var{proc} element-wise to corresponding elements of the input
  3324. @var{stream}s for side-effects; it returns nothing.
  3325. @code{stream-for-each} stops as soon as any of its input streams is
  3326. exhausted.
  3327. @end deffn
  3328. @deffn {Scheme Procedure} stream-from first [step]
  3329. Creates a newly-allocated stream that contains @var{first} as its first
  3330. element and increments each succeeding element by @var{step}. If
  3331. @var{step} is not given it defaults to 1. @var{first} and @var{step}
  3332. may be of any numeric type. @code{stream-from} is frequently useful as
  3333. a generator in @code{stream-of} expressions. See also
  3334. @code{stream-range} for a similar procedure that creates finite streams.
  3335. @end deffn
  3336. @deffn {Scheme Procedure} stream-iterate proc base
  3337. Creates a newly-allocated stream containing @var{base} in its first
  3338. element and applies @var{proc} to each element in turn to determine the
  3339. succeeding element. See also @code{stream-unfold} and
  3340. @code{stream-unfolds}.
  3341. @end deffn
  3342. @deffn {Scheme Procedure} stream-length stream
  3343. Returns the number of elements in the @var{stream}; it does not evaluate
  3344. its elements. @code{stream-length} may only be used on finite streams;
  3345. it enters an infinite loop with infinite streams.
  3346. @end deffn
  3347. @deffn {Scheme Syntax} stream-let tag ((var expr) @dots{}) body @dots{}
  3348. Creates a local scope that binds each variable to the value of its
  3349. corresponding expression. It additionally binds @var{tag} to a
  3350. procedure which takes the bound variables as arguments and @var{body} as
  3351. its defining expressions, binding the @var{tag} with
  3352. @code{stream-lambda}. @var{tag} is in scope within body, and may be
  3353. called recursively. When the expanded expression defined by the
  3354. @code{stream-let} is evaluated, @code{stream-let} evaluates the
  3355. expressions in its @var{body} in an environment containing the
  3356. newly-bound variables, returning the value of the last expression
  3357. evaluated, which must yield a stream.
  3358. @code{stream-let} provides syntactic sugar on @code{stream-lambda}, in
  3359. the same manner as normal @code{let} provides syntactic sugar on normal
  3360. @code{lambda}. However, unlike normal @code{let}, the @var{tag} is
  3361. required, not optional, because unnamed @code{stream-let} is
  3362. meaningless.
  3363. For example, @code{stream-member} returns the first @code{stream-pair}
  3364. of the input @var{strm} with a @code{stream-car} @var{x} that satisfies
  3365. @code{(eql? obj x)}, or the null stream if @var{x} is not present in
  3366. @var{strm}.
  3367. @example
  3368. (define-stream (stream-member eql? obj strm)
  3369. (stream-let loop ((strm strm))
  3370. (cond ((stream-null? strm) strm)
  3371. ((eql? obj (stream-car strm)) strm)
  3372. (else (loop (stream-cdr strm))))))
  3373. @end example
  3374. @end deffn
  3375. @deffn {Scheme Procedure} stream-map proc stream @dots{}
  3376. Applies @var{proc} element-wise to corresponding elements of the input
  3377. @var{stream}s, returning a newly-allocated stream containing elements
  3378. that are the results of those procedure applications. The output stream
  3379. has as many elements as the minimum-length input stream, and may be
  3380. infinite.
  3381. @end deffn
  3382. @deffn {Scheme Syntax} stream-match stream clause @dots{}
  3383. Provides pattern-matching for streams. The input @var{stream} is an
  3384. expression that evaluates to a stream. Clauses are of the form
  3385. @code{(pattern [fender] expression)}, consisting of a @var{pattern} that
  3386. matches a stream of a particular shape, an optional @var{fender} that
  3387. must succeed if the pattern is to match, and an @var{expression} that is
  3388. evaluated if the pattern matches. There are four types of patterns:
  3389. @itemize @bullet
  3390. @item
  3391. () matches the null stream.
  3392. @item
  3393. (@var{pat0} @var{pat1} @dots{}) matches a finite stream with length
  3394. exactly equal to the number of pattern elements.
  3395. @item
  3396. (@var{pat0} @var{pat1} @dots{} @code{.} @var{pat-rest}) matches an
  3397. infinite stream, or a finite stream with length at least as great as the
  3398. number of pattern elements before the literal dot.
  3399. @item
  3400. @var{pat} matches an entire stream. Should always appear last in the
  3401. list of clauses; it's not an error to appear elsewhere, but subsequent
  3402. clauses could never match.
  3403. @end itemize
  3404. Each pattern element may be either:
  3405. @itemize @bullet
  3406. @item
  3407. An identifier, which matches any stream element. Additionally, the
  3408. value of the stream element is bound to the variable named by the
  3409. identifier, which is in scope in the @var{fender} and @var{expression}
  3410. of the corresponding @var{clause}. Each identifier in a single pattern
  3411. must be unique.
  3412. @item
  3413. A literal underscore (@code{_}), which matches any stream element but
  3414. creates no bindings.
  3415. @end itemize
  3416. The @var{pattern}s are tested in order, left-to-right, until a matching
  3417. pattern is found; if @var{fender} is present, it must evaluate to a true
  3418. value for the match to be successful. Pattern variables are bound in
  3419. the corresponding @var{fender} and @var{expression}. Once the matching
  3420. @var{pattern} is found, the corresponding @var{expression} is evaluated
  3421. and returned as the result of the match. An error is signaled if no
  3422. pattern matches the input @var{stream}.
  3423. @code{stream-match} is often used to distinguish null streams from
  3424. non-null streams, binding @var{head} and @var{tail}:
  3425. @example
  3426. (define (len strm)
  3427. (stream-match strm
  3428. (() 0)
  3429. ((head . tail) (+ 1 (len tail)))))
  3430. @end example
  3431. Fenders can test the common case where two stream elements must be
  3432. identical; the @code{else} pattern is an identifier bound to the entire
  3433. stream, not a keyword as in @code{cond}.
  3434. @example
  3435. (stream-match strm
  3436. ((x y . _) (equal? x y) 'ok)
  3437. (else 'error))
  3438. @end example
  3439. A more complex example uses two nested matchers to match two different
  3440. stream arguments; @code{(stream-merge lt? . strms)} stably merges two or
  3441. more streams ordered by the @code{lt?} predicate:
  3442. @example
  3443. (define-stream (stream-merge lt? . strms)
  3444. (define-stream (merge xx yy)
  3445. (stream-match xx (() yy) ((x . xs)
  3446. (stream-match yy (() xx) ((y . ys)
  3447. (if (lt? y x)
  3448. (stream-cons y (merge xx ys))
  3449. (stream-cons x (merge xs yy))))))))
  3450. (stream-let loop ((strms strms))
  3451. (cond ((null? strms) stream-null)
  3452. ((null? (cdr strms)) (car strms))
  3453. (else (merge (car strms)
  3454. (apply stream-merge lt?
  3455. (cdr strms)))))))
  3456. @end example
  3457. @end deffn
  3458. @deffn {Scheme Syntax} stream-of expr clause @dots{}
  3459. Provides the syntax of stream comprehensions, which generate streams by
  3460. means of looping expressions. The result is a stream of objects of the
  3461. type returned by @var{expr}. There are four types of clauses:
  3462. @itemize @bullet
  3463. @item
  3464. (@var{var} @code{in} @var{stream-expr}) loops over the elements of
  3465. @var{stream-expr}, in order from the start of the stream, binding each
  3466. element of the stream in turn to @var{var}. @code{stream-from} and
  3467. @code{stream-range} are frequently useful as generators for
  3468. @var{stream-expr}.
  3469. @item
  3470. (@var{var} @code{is} @var{expr}) binds @var{var} to the value obtained
  3471. by evaluating @var{expr}.
  3472. @item
  3473. (@var{pred} @var{expr}) includes in the output stream only those
  3474. elements @var{x} which satisfy the predicate @var{pred}.
  3475. @end itemize
  3476. The scope of variables bound in the stream comprehension is the clauses
  3477. to the right of the binding clause (but not the binding clause itself)
  3478. plus the result expression.
  3479. When two or more generators are present, the loops are processed as if
  3480. they are nested from left to right; that is, the rightmost generator
  3481. varies fastest. A consequence of this is that only the first generator
  3482. may be infinite and all subsequent generators must be finite. If no
  3483. generators are present, the result of a stream comprehension is a stream
  3484. containing the result expression; thus, @samp{(stream-of 1)} produces a
  3485. finite stream containing only the element 1.
  3486. @example
  3487. (stream-of (* x x)
  3488. (x in (stream-range 0 10))
  3489. (even? x))
  3490. @result{} 0 4 16 36 64
  3491. (stream-of (list a b)
  3492. (a in (stream-range 1 4))
  3493. (b in (stream-range 1 3)))
  3494. @result{} (1 1) (1 2) (2 1) (2 2) (3 1) (3 2)
  3495. (stream-of (list i j)
  3496. (i in (stream-range 1 5))
  3497. (j in (stream-range (+ i 1) 5)))
  3498. @result{} (1 2) (1 3) (1 4) (2 3) (2 4) (3 4)
  3499. @end example
  3500. @end deffn
  3501. @deffn {Scheme Procedure} stream-range first past [step]
  3502. Creates a newly-allocated stream that contains @var{first} as its first
  3503. element and increments each succeeding element by @var{step}. The
  3504. stream is finite and ends before @var{past}, which is not an element of
  3505. the stream. If @var{step} is not given it defaults to 1 if @var{first}
  3506. is less than past and -1 otherwise. @var{first}, @var{past} and
  3507. @var{step} may be of any real numeric type. @code{stream-range} is
  3508. frequently useful as a generator in @code{stream-of} expressions. See
  3509. also @code{stream-from} for a similar procedure that creates infinite
  3510. streams.
  3511. @example
  3512. (stream-range 0 10) @result{} 0 1 2 3 4 5 6 7 8 9
  3513. (stream-range 0 10 2) @result{} 0 2 4 6 8
  3514. @end example
  3515. Successive elements of the stream are calculated by adding @var{step} to
  3516. @var{first}, so if any of @var{first}, @var{past} or @var{step} are
  3517. inexact, the length of the output stream may differ from
  3518. @code{(ceiling (- (/ (- past first) step) 1)}.
  3519. @end deffn
  3520. @deffn {Scheme Procedure} stream-ref stream n
  3521. Returns the @var{n}th element of stream, counting from zero. An error
  3522. is signaled if @var{n} is greater than or equal to the length of stream.
  3523. @example
  3524. (define (fact n)
  3525. (stream-ref
  3526. (stream-scan * 1 (stream-from 1))
  3527. n))
  3528. @end example
  3529. @end deffn
  3530. @deffn {Scheme Procedure} stream-reverse stream
  3531. Returns a newly-allocated stream containing the elements of the input
  3532. @var{stream} but in reverse order. @code{stream-reverse} may only be
  3533. used with finite streams; it enters an infinite loop with infinite
  3534. streams. @code{stream-reverse} does not force evaluation of the
  3535. elements of the stream.
  3536. @end deffn
  3537. @deffn {Scheme Procedure} stream-scan proc base stream
  3538. Accumulates the partial folds of an input @var{stream} into a
  3539. newly-allocated output stream. The output stream is the @var{base}
  3540. followed by @code{(stream-fold proc base (stream-take i stream))} for
  3541. each of the first @var{i} elements of @var{stream}.
  3542. @example
  3543. (stream-scan + 0 (stream-from 1))
  3544. @result{} (stream 0 1 3 6 10 15 @dots{})
  3545. (stream-scan * 1 (stream-from 1))
  3546. @result{} (stream 1 1 2 6 24 120 @dots{})
  3547. @end example
  3548. @end deffn
  3549. @deffn {Scheme Procedure} stream-take n stream
  3550. Returns a newly-allocated stream containing the first @var{n} elements
  3551. of the input @var{stream}. If the input @var{stream} has less than
  3552. @var{n} elements, so does the output stream. See also
  3553. @code{stream-drop}.
  3554. @end deffn
  3555. @deffn {Scheme Procedure} stream-take-while pred stream
  3556. Takes a predicate and a @code{stream} and returns a newly-allocated
  3557. stream containing those elements @code{x} that form the maximal prefix
  3558. of the input stream which satisfy @var{pred}. See also
  3559. @code{stream-drop-while}.
  3560. @end deffn
  3561. @deffn {Scheme Procedure} stream-unfold map pred gen base
  3562. The fundamental recursive stream constructor. It constructs a stream by
  3563. repeatedly applying @var{gen} to successive values of @var{base}, in the
  3564. manner of @code{stream-iterate}, then applying @var{map} to each of the
  3565. values so generated, appending each of the mapped values to the output
  3566. stream as long as @code{(pred? base)} returns a true value. See also
  3567. @code{stream-iterate} and @code{stream-unfolds}.
  3568. The expression below creates the finite stream @samp{0 1 4 9 16 25 36 49
  3569. 64 81}. Initially the @var{base} is 0, which is less than 10, so
  3570. @var{map} squares the @var{base} and the mapped value becomes the first
  3571. element of the output stream. Then @var{gen} increments the @var{base}
  3572. by 1, so it becomes 1; this is less than 10, so @var{map} squares the
  3573. new @var{base} and 1 becomes the second element of the output stream.
  3574. And so on, until the base becomes 10, when @var{pred} stops the
  3575. recursion and stream-null ends the output stream.
  3576. @example
  3577. (stream-unfold
  3578. (lambda (x) (expt x 2)) ; map
  3579. (lambda (x) (< x 10)) ; pred?
  3580. (lambda (x) (+ x 1)) ; gen
  3581. 0) ; base
  3582. @end example
  3583. @end deffn
  3584. @deffn {Scheme Procedure} stream-unfolds proc seed
  3585. Returns @var{n} newly-allocated streams containing those elements
  3586. produced by successive calls to the generator @var{proc}, which takes
  3587. the current @var{seed} as its argument and returns @var{n}+1 values
  3588. (@var{proc} @var{seed}) @result{} @var{seed} @var{result_0} @dots{} @var{result_n-1}
  3589. where the returned @var{seed} is the input @var{seed} to the next call
  3590. to the generator and @var{result_i} indicates how to produce the next
  3591. element of the @var{i}th result stream:
  3592. @itemize @bullet
  3593. @item
  3594. (@var{value}): @var{value} is the next car of the result stream.
  3595. @item
  3596. @code{#f}: no value produced by this iteration of the generator
  3597. @var{proc} for the result stream.
  3598. @item
  3599. (): the end of the result stream.
  3600. @end itemize
  3601. It may require multiple calls of @var{proc} to produce the next element
  3602. of any particular result stream. See also @code{stream-iterate} and
  3603. @code{stream-unfold}.
  3604. @example
  3605. (define (stream-partition pred? strm)
  3606. (stream-unfolds
  3607. (lambda (s)
  3608. (if (stream-null? s)
  3609. (values s '() '())
  3610. (let ((a (stream-car s))
  3611. (d (stream-cdr s)))
  3612. (if (pred? a)
  3613. (values d (list a) #f)
  3614. (values d #f (list a))))))
  3615. strm))
  3616. (call-with-values
  3617. (lambda ()
  3618. (stream-partition odd?
  3619. (stream-range 1 6)))
  3620. (lambda (odds evens)
  3621. (list (stream->list odds)
  3622. (stream->list evens))))
  3623. @result{} ((1 3 5) (2 4))
  3624. @end example
  3625. @end deffn
  3626. @deffn {Scheme Procedure} stream-zip stream @dots{}
  3627. Returns a newly-allocated stream in which each element is a list (not a
  3628. stream) of the corresponding elements of the input @var{stream}s. The
  3629. output stream is as long as the shortest input @var{stream}, if any of
  3630. the input @var{stream}s is finite, or is infinite if all the input
  3631. @var{stream}s are infinite.
  3632. @end deffn
  3633. @node SRFI-42
  3634. @subsection SRFI-42 - Eager Comprehensions
  3635. @cindex SRFI-42
  3636. See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
  3637. specification of SRFI-42}.
  3638. @node SRFI-43
  3639. @subsection SRFI-43 - Vector Library
  3640. @cindex SRFI-43
  3641. This subsection is based on the
  3642. @uref{http://srfi.schemers.org/srfi-43/srfi-43.html, specification of
  3643. SRFI-43} by Taylor Campbell.
  3644. @c The copyright notice and license text of the SRFI-43 specification is
  3645. @c reproduced below:
  3646. @c Copyright (C) Taylor Campbell (2003). All Rights Reserved.
  3647. @c Permission is hereby granted, free of charge, to any person obtaining a
  3648. @c copy of this software and associated documentation files (the
  3649. @c "Software"), to deal in the Software without restriction, including
  3650. @c without limitation the rights to use, copy, modify, merge, publish,
  3651. @c distribute, sublicense, and/or sell copies of the Software, and to
  3652. @c permit persons to whom the Software is furnished to do so, subject to
  3653. @c the following conditions:
  3654. @c The above copyright notice and this permission notice shall be included
  3655. @c in all copies or substantial portions of the Software.
  3656. @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  3657. @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  3658. @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  3659. @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  3660. @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  3661. @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  3662. @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  3663. @noindent
  3664. SRFI-43 implements a comprehensive library of vector operations. It can
  3665. be made available with:
  3666. @example
  3667. (use-modules (srfi srfi-43))
  3668. @end example
  3669. @menu
  3670. * SRFI-43 Constructors::
  3671. * SRFI-43 Predicates::
  3672. * SRFI-43 Selectors::
  3673. * SRFI-43 Iteration::
  3674. * SRFI-43 Searching::
  3675. * SRFI-43 Mutators::
  3676. * SRFI-43 Conversion::
  3677. @end menu
  3678. @node SRFI-43 Constructors
  3679. @subsubsection SRFI-43 Constructors
  3680. @deffn {Scheme Procedure} make-vector size [fill]
  3681. Create and return a vector of size @var{size}, optionally filling it
  3682. with @var{fill}. The default value of @var{fill} is unspecified.
  3683. @example
  3684. (make-vector 5 3) @result{} #(3 3 3 3 3)
  3685. @end example
  3686. @end deffn
  3687. @deffn {Scheme Procedure} vector x @dots{}
  3688. Create and return a vector whose elements are @var{x} @enddots{}.
  3689. @example
  3690. (vector 0 1 2 3 4) @result{} #(0 1 2 3 4)
  3691. @end example
  3692. @end deffn
  3693. @deffn {Scheme Procedure} vector-unfold f length initial-seed @dots{}
  3694. The fundamental vector constructor. Create a vector whose length
  3695. is @var{length} and iterates across each index k from 0 up to
  3696. @var{length} - 1, applying @var{f} at each iteration to the current
  3697. index and current seeds, in that order, to receive n + 1 values: the
  3698. element to put in the kth slot of the new vector, and n new seeds for
  3699. the next iteration. It is an error for the number of seeds to vary
  3700. between iterations.
  3701. @example
  3702. (vector-unfold (lambda (i x) (values x (- x 1)))
  3703. 10 0)
  3704. @result{} #(0 -1 -2 -3 -4 -5 -6 -7 -8 -9)
  3705. (vector-unfold values 10)
  3706. @result{} #(0 1 2 3 4 5 6 7 8 9)
  3707. @end example
  3708. @end deffn
  3709. @deffn {Scheme Procedure} vector-unfold-right f length initial-seed @dots{}
  3710. Like @code{vector-unfold}, but it uses @var{f} to generate elements from
  3711. right-to-left, rather than left-to-right.
  3712. @example
  3713. (vector-unfold-right (lambda (i x) (values x (+ x 1)))
  3714. 10 0)
  3715. @result{} #(9 8 7 6 5 4 3 2 1 0)
  3716. @end example
  3717. @end deffn
  3718. @deffn {Scheme Procedure} vector-copy vec [start [end [fill]]]
  3719. Allocate a new vector whose length is @var{end} - @var{start} and fills
  3720. it with elements from @var{vec}, taking elements from @var{vec} starting
  3721. at index @var{start} and stopping at index @var{end}. @var{start}
  3722. defaults to 0 and @var{end} defaults to the value of
  3723. @code{(vector-length vec)}. If @var{end} extends beyond the length of
  3724. @var{vec}, the slots in the new vector that obviously cannot be filled
  3725. by elements from @var{vec} are filled with @var{fill}, whose default
  3726. value is unspecified.
  3727. @example
  3728. (vector-copy '#(a b c d e f g h i))
  3729. @result{} #(a b c d e f g h i)
  3730. (vector-copy '#(a b c d e f g h i) 6)
  3731. @result{} #(g h i)
  3732. (vector-copy '#(a b c d e f g h i) 3 6)
  3733. @result{} #(d e f)
  3734. (vector-copy '#(a b c d e f g h i) 6 12 'x)
  3735. @result{} #(g h i x x x)
  3736. @end example
  3737. @end deffn
  3738. @deffn {Scheme Procedure} vector-reverse-copy vec [start [end]]
  3739. Like @code{vector-copy}, but it copies the elements in the reverse order
  3740. from @var{vec}.
  3741. @example
  3742. (vector-reverse-copy '#(5 4 3 2 1 0) 1 5)
  3743. @result{} #(1 2 3 4)
  3744. @end example
  3745. @end deffn
  3746. @deffn {Scheme Procedure} vector-append vec @dots{}
  3747. Return a newly allocated vector that contains all elements in order from
  3748. the subsequent locations in @var{vec} @enddots{}.
  3749. @example
  3750. (vector-append '#(a) '#(b c d))
  3751. @result{} #(a b c d)
  3752. @end example
  3753. @end deffn
  3754. @deffn {Scheme Procedure} vector-concatenate list-of-vectors
  3755. Append each vector in @var{list-of-vectors}. Equivalent to
  3756. @code{(apply vector-append list-of-vectors)}.
  3757. @example
  3758. (vector-concatenate '(#(a b) #(c d)))
  3759. @result{} #(a b c d)
  3760. @end example
  3761. @end deffn
  3762. @node SRFI-43 Predicates
  3763. @subsubsection SRFI-43 Predicates
  3764. @deffn {Scheme Procedure} vector? obj
  3765. Return true if @var{obj} is a vector, else return false.
  3766. @end deffn
  3767. @deffn {Scheme Procedure} vector-empty? vec
  3768. Return true if @var{vec} is empty, i.e. its length is 0, else return
  3769. false.
  3770. @end deffn
  3771. @deffn {Scheme Procedure} vector= elt=? vec @dots{}
  3772. Return true if the vectors @var{vec} @dots{} have equal lengths and
  3773. equal elements according to @var{elt=?}. @var{elt=?} is always applied
  3774. to two arguments. Element comparison must be consistent with @code{eq?}
  3775. in the following sense: if @code{(eq? a b)} returns true, then
  3776. @code{(elt=? a b)} must also return true. The order in which
  3777. comparisons are performed is unspecified.
  3778. @end deffn
  3779. @node SRFI-43 Selectors
  3780. @subsubsection SRFI-43 Selectors
  3781. @deffn {Scheme Procedure} vector-ref vec i
  3782. Return the element at index @var{i} in @var{vec}. Indexing is based on
  3783. zero.
  3784. @end deffn
  3785. @deffn {Scheme Procedure} vector-length vec
  3786. Return the length of @var{vec}.
  3787. @end deffn
  3788. @node SRFI-43 Iteration
  3789. @subsubsection SRFI-43 Iteration
  3790. @deffn {Scheme Procedure} vector-fold kons knil vec1 vec2 @dots{}
  3791. The fundamental vector iterator. @var{kons} is iterated over each index
  3792. in all of the vectors, stopping at the end of the shortest; @var{kons}
  3793. is applied as
  3794. @smalllisp
  3795. (kons i state (vector-ref vec1 i) (vector-ref vec2 i) ...)
  3796. @end smalllisp
  3797. where @var{state} is the current state value, and @var{i} is the current
  3798. index. The current state value begins with @var{knil}, and becomes
  3799. whatever @var{kons} returned at the respective iteration. The iteration
  3800. is strictly left-to-right.
  3801. @end deffn
  3802. @deffn {Scheme Procedure} vector-fold-right kons knil vec1 vec2 @dots{}
  3803. Similar to @code{vector-fold}, but it iterates right-to-left instead of
  3804. left-to-right.
  3805. @end deffn
  3806. @deffn {Scheme Procedure} vector-map f vec1 vec2 @dots{}
  3807. Return a new vector of the shortest size of the vector arguments. Each
  3808. element at index i of the new vector is mapped from the old vectors by
  3809. @smalllisp
  3810. (f i (vector-ref vec1 i) (vector-ref vec2 i) ...)
  3811. @end smalllisp
  3812. The dynamic order of application of @var{f} is unspecified.
  3813. @end deffn
  3814. @deffn {Scheme Procedure} vector-map! f vec1 vec2 @dots{}
  3815. Similar to @code{vector-map}, but rather than mapping the new elements
  3816. into a new vector, the new mapped elements are destructively inserted
  3817. into @var{vec1}. The dynamic order of application of @var{f} is
  3818. unspecified.
  3819. @end deffn
  3820. @deffn {Scheme Procedure} vector-for-each f vec1 vec2 @dots{}
  3821. Call @code{(f i (vector-ref vec1 i) (vector-ref vec2 i) ...)} for each
  3822. index i less than the length of the shortest vector passed. The
  3823. iteration is strictly left-to-right.
  3824. @end deffn
  3825. @deffn {Scheme Procedure} vector-count pred? vec1 vec2 @dots{}
  3826. Count the number of parallel elements in the vectors that satisfy
  3827. @var{pred?}, which is applied, for each index i less than the length of
  3828. the smallest vector, to i and each parallel element in the vectors at
  3829. that index, in order.
  3830. @example
  3831. (vector-count (lambda (i elt) (even? elt))
  3832. '#(3 1 4 1 5 9 2 5 6))
  3833. @result{} 3
  3834. (vector-count (lambda (i x y) (< x y))
  3835. '#(1 3 6 9) '#(2 4 6 8 10 12))
  3836. @result{} 2
  3837. @end example
  3838. @end deffn
  3839. @node SRFI-43 Searching
  3840. @subsubsection SRFI-43 Searching
  3841. @deffn {Scheme Procedure} vector-index pred? vec1 vec2 @dots{}
  3842. Find and return the index of the first elements in @var{vec1} @var{vec2}
  3843. @dots{} that satisfy @var{pred?}. If no matching element is found by
  3844. the end of the shortest vector, return @code{#f}.
  3845. @example
  3846. (vector-index even? '#(3 1 4 1 5 9))
  3847. @result{} 2
  3848. (vector-index < '#(3 1 4 1 5 9 2 5 6) '#(2 7 1 8 2))
  3849. @result{} 1
  3850. (vector-index = '#(3 1 4 1 5 9 2 5 6) '#(2 7 1 8 2))
  3851. @result{} #f
  3852. @end example
  3853. @end deffn
  3854. @deffn {Scheme Procedure} vector-index-right pred? vec1 vec2 @dots{}
  3855. Like @code{vector-index}, but it searches right-to-left, rather than
  3856. left-to-right. Note that the SRFI 43 specification requires that all
  3857. the vectors must have the same length, but both the SRFI 43 reference
  3858. implementation and Guile's implementation allow vectors with unequal
  3859. lengths, and start searching from the last index of the shortest vector.
  3860. @end deffn
  3861. @deffn {Scheme Procedure} vector-skip pred? vec1 vec2 @dots{}
  3862. Find and return the index of the first elements in @var{vec1} @var{vec2}
  3863. @dots{} that do not satisfy @var{pred?}. If no matching element is
  3864. found by the end of the shortest vector, return @code{#f}. Equivalent
  3865. to @code{vector-index} but with the predicate inverted.
  3866. @example
  3867. (vector-skip number? '#(1 2 a b 3 4 c d)) @result{} 2
  3868. @end example
  3869. @end deffn
  3870. @deffn {Scheme Procedure} vector-skip-right pred? vec1 vec2 @dots{}
  3871. Like @code{vector-skip}, but it searches for a non-matching element
  3872. right-to-left, rather than left-to-right. Note that the SRFI 43
  3873. specification requires that all the vectors must have the same length,
  3874. but both the SRFI 43 reference implementation and Guile's implementation
  3875. allow vectors with unequal lengths, and start searching from the last
  3876. index of the shortest vector.
  3877. @end deffn
  3878. @deffn {Scheme Procedure} vector-binary-search vec value cmp [start [end]]
  3879. Find and return an index of @var{vec} between @var{start} and @var{end}
  3880. whose value is @var{value} using a binary search. If no matching
  3881. element is found, return @code{#f}. The default @var{start} is 0 and
  3882. the default @var{end} is the length of @var{vec}.
  3883. @var{cmp} must be a procedure of two arguments such that @code{(cmp a
  3884. b)} returns a negative integer if @math{a < b}, a positive integer if
  3885. @math{a > b}, or zero if @math{a = b}. The elements of @var{vec} must
  3886. be sorted in non-decreasing order according to @var{cmp}.
  3887. Note that SRFI 43 does not document the @var{start} and @var{end}
  3888. arguments, but both its reference implementation and Guile's
  3889. implementation support them.
  3890. @example
  3891. (define (char-cmp c1 c2)
  3892. (cond ((char<? c1 c2) -1)
  3893. ((char>? c1 c2) 1)
  3894. (else 0)))
  3895. (vector-binary-search '#(#\a #\b #\c #\d #\e #\f #\g #\h)
  3896. #\g
  3897. char-cmp)
  3898. @result{} 6
  3899. @end example
  3900. @end deffn
  3901. @deffn {Scheme Procedure} vector-any pred? vec1 vec2 @dots{}
  3902. Find the first parallel set of elements from @var{vec1} @var{vec2}
  3903. @dots{} for which @var{pred?} returns a true value. If such a parallel
  3904. set of elements exists, @code{vector-any} returns the value that
  3905. @var{pred?} returned for that set of elements. The iteration is
  3906. strictly left-to-right.
  3907. @end deffn
  3908. @deffn {Scheme Procedure} vector-every pred? vec1 vec2 @dots{}
  3909. If, for every index i between 0 and the length of the shortest vector
  3910. argument, the set of elements @code{(vector-ref vec1 i)}
  3911. @code{(vector-ref vec2 i)} @dots{} satisfies @var{pred?},
  3912. @code{vector-every} returns the value that @var{pred?} returned for the
  3913. last set of elements, at the last index of the shortest vector.
  3914. Otherwise it returns @code{#f}. The iteration is strictly
  3915. left-to-right.
  3916. @end deffn
  3917. @node SRFI-43 Mutators
  3918. @subsubsection SRFI-43 Mutators
  3919. @deffn {Scheme Procedure} vector-set! vec i value
  3920. Assign the contents of the location at @var{i} in @var{vec} to
  3921. @var{value}.
  3922. @end deffn
  3923. @deffn {Scheme Procedure} vector-swap! vec i j
  3924. Swap the values of the locations in @var{vec} at @var{i} and @var{j}.
  3925. @end deffn
  3926. @deffn {Scheme Procedure} vector-fill! vec fill [start [end]]
  3927. Assign the value of every location in @var{vec} between @var{start} and
  3928. @var{end} to @var{fill}. @var{start} defaults to 0 and @var{end}
  3929. defaults to the length of @var{vec}.
  3930. @end deffn
  3931. @deffn {Scheme Procedure} vector-reverse! vec [start [end]]
  3932. Destructively reverse the contents of @var{vec} between @var{start} and
  3933. @var{end}. @var{start} defaults to 0 and @var{end} defaults to the
  3934. length of @var{vec}.
  3935. @end deffn
  3936. @deffn {Scheme Procedure} vector-copy! target tstart source [sstart [send]]
  3937. Copy a block of elements from @var{source} to @var{target}, both of
  3938. which must be vectors, starting in @var{target} at @var{tstart} and
  3939. starting in @var{source} at @var{sstart}, ending when (@var{send} -
  3940. @var{sstart}) elements have been copied. It is an error for
  3941. @var{target} to have a length less than (@var{tstart} + @var{send} -
  3942. @var{sstart}). @var{sstart} defaults to 0 and @var{send} defaults to
  3943. the length of @var{source}.
  3944. @end deffn
  3945. @deffn {Scheme Procedure} vector-reverse-copy! target tstart source [sstart [send]]
  3946. Like @code{vector-copy!}, but this copies the elements in the reverse
  3947. order. It is an error if @var{target} and @var{source} are identical
  3948. vectors and the @var{target} and @var{source} ranges overlap; however,
  3949. if @var{tstart} = @var{sstart}, @code{vector-reverse-copy!} behaves as
  3950. @code{(vector-reverse! target tstart send)} would.
  3951. @end deffn
  3952. @node SRFI-43 Conversion
  3953. @subsubsection SRFI-43 Conversion
  3954. @deffn {Scheme Procedure} vector->list vec [start [end]]
  3955. Return a newly allocated list containing the elements in @var{vec}
  3956. between @var{start} and @var{end}. @var{start} defaults to 0 and
  3957. @var{end} defaults to the length of @var{vec}.
  3958. @end deffn
  3959. @deffn {Scheme Procedure} reverse-vector->list vec [start [end]]
  3960. Like @code{vector->list}, but the resulting list contains the specified
  3961. range of elements of @var{vec} in reverse order.
  3962. @end deffn
  3963. @deffn {Scheme Procedure} list->vector proper-list [start [end]]
  3964. Return a newly allocated vector of the elements from @var{proper-list}
  3965. with indices between @var{start} and @var{end}. @var{start} defaults to
  3966. 0 and @var{end} defaults to the length of @var{proper-list}. Note that
  3967. SRFI 43 does not document the @var{start} and @var{end} arguments, but
  3968. both its reference implementation and Guile's implementation support
  3969. them.
  3970. @end deffn
  3971. @deffn {Scheme Procedure} reverse-list->vector proper-list [start [end]]
  3972. Like @code{list->vector}, but the resulting vector contains the specified
  3973. range of elements of @var{proper-list} in reverse order. Note that SRFI
  3974. 43 does not document the @var{start} and @var{end} arguments, but both
  3975. its reference implementation and Guile's implementation support them.
  3976. @end deffn
  3977. @node SRFI-45
  3978. @subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
  3979. @cindex SRFI-45
  3980. This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
  3981. specification of SRFI-45} written by Andr@'e van Tonder.
  3982. @c Copyright (C) André van Tonder (2003). All Rights Reserved.
  3983. @c Permission is hereby granted, free of charge, to any person obtaining a
  3984. @c copy of this software and associated documentation files (the
  3985. @c "Software"), to deal in the Software without restriction, including
  3986. @c without limitation the rights to use, copy, modify, merge, publish,
  3987. @c distribute, sublicense, and/or sell copies of the Software, and to
  3988. @c permit persons to whom the Software is furnished to do so, subject to
  3989. @c the following conditions:
  3990. @c The above copyright notice and this permission notice shall be included
  3991. @c in all copies or substantial portions of the Software.
  3992. @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  3993. @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  3994. @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  3995. @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  3996. @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  3997. @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  3998. @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  3999. Lazy evaluation is traditionally simulated in Scheme using @code{delay}
  4000. and @code{force}. However, these primitives are not powerful enough to
  4001. express a large class of lazy algorithms that are iterative. Indeed, it
  4002. is folklore in the Scheme community that typical iterative lazy
  4003. algorithms written using delay and force will often require unbounded
  4004. memory.
  4005. This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
  4006. @code{force}@}, which allow the programmer to succinctly express lazy
  4007. algorithms while retaining bounded space behavior in cases that are
  4008. properly tail-recursive. A general recipe for using these primitives is
  4009. provided. An additional procedure @code{eager} is provided for the
  4010. construction of eager promises in cases where efficiency is a concern.
  4011. Although this SRFI redefines @code{delay} and @code{force}, the
  4012. extension is conservative in the sense that the semantics of the subset
  4013. @{@code{delay}, @code{force}@} in isolation (i.e., as long as the
  4014. program does not use @code{lazy}) agrees with that in R5RS. In other
  4015. words, no program that uses the R5RS definitions of delay and force will
  4016. break if those definition are replaced by the SRFI-45 definitions of
  4017. delay and force.
  4018. Guile also adds @code{promise?} to the list of exports, which is not
  4019. part of the official SRFI-45.
  4020. @deffn {Scheme Procedure} promise? obj
  4021. Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
  4022. @end deffn
  4023. @deffn {Scheme Syntax} delay expression
  4024. Takes an expression of arbitrary type @var{a} and returns a promise of
  4025. type @code{(Promise @var{a})} which at some point in the future may be
  4026. asked (by the @code{force} procedure) to evaluate the expression and
  4027. deliver the resulting value.
  4028. @end deffn
  4029. @deffn {Scheme Syntax} lazy expression
  4030. Takes an expression of type @code{(Promise @var{a})} and returns a
  4031. promise of type @code{(Promise @var{a})} which at some point in the
  4032. future may be asked (by the @code{force} procedure) to evaluate the
  4033. expression and deliver the resulting promise.
  4034. @end deffn
  4035. @deffn {Scheme Procedure} force expression
  4036. Takes an argument of type @code{(Promise @var{a})} and returns a value
  4037. of type @var{a} as follows: If a value of type @var{a} has been computed
  4038. for the promise, this value is returned. Otherwise, the promise is
  4039. first evaluated, then overwritten by the obtained promise or value, and
  4040. then force is again applied (iteratively) to the promise.
  4041. @end deffn
  4042. @deffn {Scheme Procedure} eager expression
  4043. Takes an argument of type @var{a} and returns a value of type
  4044. @code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
  4045. evaluated eagerly. Semantically, writing @code{(eager expression)} is
  4046. equivalent to writing
  4047. @lisp
  4048. (let ((value expression)) (delay value)).
  4049. @end lisp
  4050. However, the former is more efficient since it does not require
  4051. unnecessary creation and evaluation of thunks. We also have the
  4052. equivalence
  4053. @lisp
  4054. (delay expression) = (lazy (eager expression))
  4055. @end lisp
  4056. @end deffn
  4057. The following reduction rules may be helpful for reasoning about these
  4058. primitives. However, they do not express the memoization and memory
  4059. usage semantics specified above:
  4060. @lisp
  4061. (force (delay expression)) -> expression
  4062. (force (lazy expression)) -> (force expression)
  4063. (force (eager value)) -> value
  4064. @end lisp
  4065. @subsubheading Correct usage
  4066. We now provide a general recipe for using the primitives @{@code{lazy},
  4067. @code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
  4068. transformation is best described by way of an example: Consider the
  4069. stream-filter algorithm, expressed in a hypothetical lazy language as
  4070. @lisp
  4071. (define (stream-filter p? s)
  4072. (if (null? s) '()
  4073. (let ((h (car s))
  4074. (t (cdr s)))
  4075. (if (p? h)
  4076. (cons h (stream-filter p? t))
  4077. (stream-filter p? t)))))
  4078. @end lisp
  4079. This algorithm can be expressed as follows in Scheme:
  4080. @lisp
  4081. (define (stream-filter p? s)
  4082. (lazy
  4083. (if (null? (force s)) (delay '())
  4084. (let ((h (car (force s)))
  4085. (t (cdr (force s))))
  4086. (if (p? h)
  4087. (delay (cons h (stream-filter p? t)))
  4088. (stream-filter p? t))))))
  4089. @end lisp
  4090. In other words, we
  4091. @itemize @bullet
  4092. @item
  4093. wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
  4094. @item
  4095. apply @code{force} to arguments of deconstructors (e.g., @code{car},
  4096. @code{cdr} and @code{null?}),
  4097. @item
  4098. wrap procedure bodies with @code{(lazy ...)}.
  4099. @end itemize
  4100. @node SRFI-46
  4101. @subsection SRFI-46 Basic syntax-rules Extensions
  4102. @cindex SRFI-46
  4103. Guile's core @code{syntax-rules} supports the extensions specified by
  4104. SRFI-46/R7RS. Tail patterns have been supported since at least Guile
  4105. 2.0, and custom ellipsis identifiers have been supported since Guile
  4106. 2.0.10. @xref{Syntax Rules}.
  4107. @node SRFI-55
  4108. @subsection SRFI-55 - Requiring Features
  4109. @cindex SRFI-55
  4110. SRFI-55 provides @code{require-extension} which is a portable
  4111. mechanism to load selected SRFI modules. This is implemented in the
  4112. Guile core, there's no module needed to get SRFI-55 itself.
  4113. @deffn {library syntax} require-extension clause1 clause2 @dots{}
  4114. Require the features of @var{clause1} @var{clause2} @dots{} , throwing
  4115. an error if any are unavailable.
  4116. A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
  4117. only @var{identifier} currently supported is @code{srfi} and the
  4118. arguments are SRFI numbers. For example to get SRFI-1 and SRFI-6,
  4119. @example
  4120. (require-extension (srfi 1 6))
  4121. @end example
  4122. @code{require-extension} can only be used at the top-level.
  4123. A Guile-specific program can simply @code{use-modules} to load SRFIs
  4124. not already in the core, @code{require-extension} is for programs
  4125. designed to be portable to other Scheme implementations.
  4126. @end deffn
  4127. @node SRFI-60
  4128. @subsection SRFI-60 - Integers as Bits
  4129. @cindex SRFI-60
  4130. @cindex integers as bits
  4131. @cindex bitwise logical
  4132. This SRFI provides various functions for treating integers as bits and
  4133. for bitwise manipulations. These functions can be obtained with,
  4134. @example
  4135. (use-modules (srfi srfi-60))
  4136. @end example
  4137. Integers are treated as infinite precision twos-complement, the same
  4138. as in the core logical functions (@pxref{Bitwise Operations}). And
  4139. likewise bit indexes start from 0 for the least significant bit. The
  4140. following functions in this SRFI are already in the Guile core,
  4141. @quotation
  4142. @code{logand},
  4143. @code{logior},
  4144. @code{logxor},
  4145. @code{lognot},
  4146. @code{logtest},
  4147. @code{logcount},
  4148. @code{integer-length},
  4149. @code{logbit?},
  4150. @code{ash}
  4151. @end quotation
  4152. @sp 1
  4153. @defun bitwise-and n1 ...
  4154. @defunx bitwise-ior n1 ...
  4155. @defunx bitwise-xor n1 ...
  4156. @defunx bitwise-not n
  4157. @defunx any-bits-set? j k
  4158. @defunx bit-set? index n
  4159. @defunx arithmetic-shift n count
  4160. @defunx bit-field n start end
  4161. @defunx bit-count n
  4162. Aliases for @code{logand}, @code{logior}, @code{logxor},
  4163. @code{lognot}, @code{logtest}, @code{logbit?}, @code{ash},
  4164. @code{bit-extract} and @code{logcount} respectively.
  4165. Note that the name @code{bit-count} conflicts with @code{bit-count} in
  4166. the core (@pxref{Bit Vectors}).
  4167. @end defun
  4168. @defun bitwise-if mask n1 n0
  4169. @defunx bitwise-merge mask n1 n0
  4170. Return an integer with bits selected from @var{n1} and @var{n0}
  4171. according to @var{mask}. Those bits where @var{mask} has 1s are taken
  4172. from @var{n1}, and those where @var{mask} has 0s are taken from
  4173. @var{n0}.
  4174. @example
  4175. (bitwise-if 3 #b0101 #b1010) @result{} 9
  4176. @end example
  4177. @end defun
  4178. @defun log2-binary-factors n
  4179. @defunx first-set-bit n
  4180. Return a count of how many factors of 2 are present in @var{n}. This
  4181. is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is
  4182. 0, the return is @math{-1}.
  4183. @example
  4184. (log2-binary-factors 6) @result{} 1
  4185. (log2-binary-factors -8) @result{} 3
  4186. @end example
  4187. @end defun
  4188. @defun copy-bit index n newbit
  4189. Return @var{n} with the bit at @var{index} set according to
  4190. @var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1,
  4191. or @code{#f} to set it to 0. Bits other than at @var{index} are
  4192. unchanged in the return.
  4193. @example
  4194. (copy-bit 1 #b0101 #t) @result{} 7
  4195. @end example
  4196. @end defun
  4197. @defun copy-bit-field n newbits start end
  4198. Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
  4199. (exclusive) changed to the value @var{newbits}.
  4200. The least significant bit in @var{newbits} goes to @var{start}, the
  4201. next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the
  4202. @var{end} given is ignored.
  4203. @example
  4204. (copy-bit-field #b10000 #b11 1 3) @result{} #b10110
  4205. @end example
  4206. @end defun
  4207. @defun rotate-bit-field n count start end
  4208. Return @var{n} with the bit field from @var{start} (inclusive) to
  4209. @var{end} (exclusive) rotated upwards by @var{count} bits.
  4210. @var{count} can be positive or negative, and it can be more than the
  4211. field width (it'll be reduced modulo the width).
  4212. @example
  4213. (rotate-bit-field #b0110 2 1 4) @result{} #b1010
  4214. @end example
  4215. @end defun
  4216. @defun reverse-bit-field n start end
  4217. Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
  4218. (exclusive) reversed.
  4219. @example
  4220. (reverse-bit-field #b101001 2 4) @result{} #b100101
  4221. @end example
  4222. @end defun
  4223. @defun integer->list n [len]
  4224. Return bits from @var{n} in the form of a list of @code{#t} for 1 and
  4225. @code{#f} for 0. The least significant @var{len} bits are returned,
  4226. and the first list element is the most significant of those bits. If
  4227. @var{len} is not given, the default is @code{(integer-length @var{n})}
  4228. (@pxref{Bitwise Operations}).
  4229. @example
  4230. (integer->list 6) @result{} (#t #t #f)
  4231. (integer->list 1 4) @result{} (#f #f #f #t)
  4232. @end example
  4233. @end defun
  4234. @defun list->integer lst
  4235. @defunx booleans->integer bool@dots{}
  4236. Return an integer formed bitwise from the given @var{lst} list of
  4237. booleans, or for @code{booleans->integer} from the @var{bool}
  4238. arguments.
  4239. Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first
  4240. element becomes the most significant bit in the return.
  4241. @example
  4242. (list->integer '(#t #f #t #f)) @result{} 10
  4243. @end example
  4244. @end defun
  4245. @node SRFI-61
  4246. @subsection SRFI-61 - A more general @code{cond} clause
  4247. This SRFI extends RnRS @code{cond} to support test expressions that
  4248. return multiple values, as well as arbitrary definitions of test
  4249. success. SRFI 61 is implemented in the Guile core; there's no module
  4250. needed to get SRFI-61 itself. Extended @code{cond} is documented in
  4251. @ref{Conditionals,, Simple Conditional Evaluation}.
  4252. @node SRFI-62
  4253. @subsection SRFI-62 - S-expression comments.
  4254. @cindex SRFI-62
  4255. Starting from version 2.0, Guile's @code{read} supports SRFI-62/R7RS
  4256. S-expression comments by default.
  4257. @node SRFI-64
  4258. @subsection SRFI-64 - A Scheme API for test suites.
  4259. @cindex SRFI-64
  4260. See @uref{http://srfi.schemers.org/srfi-64/srfi-64.html, the
  4261. specification of SRFI-64}.
  4262. @node SRFI-67
  4263. @subsection SRFI-67 - Compare procedures
  4264. @cindex SRFI-67
  4265. See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
  4266. specification of SRFI-67}.
  4267. @node SRFI-69
  4268. @subsection SRFI-69 - Basic hash tables
  4269. @cindex SRFI-69
  4270. This is a portable wrapper around Guile's built-in hash table and weak
  4271. table support. @xref{Hash Tables}, for information on that built-in
  4272. support. Above that, this hash-table interface provides association
  4273. of equality and hash functions with tables at creation time, so
  4274. variants of each function are not required, as well as a procedure
  4275. that takes care of most uses for Guile hash table handles, which this
  4276. SRFI does not provide as such.
  4277. Access it with:
  4278. @lisp
  4279. (use-modules (srfi srfi-69))
  4280. @end lisp
  4281. @menu
  4282. * SRFI-69 Creating hash tables::
  4283. * SRFI-69 Accessing table items::
  4284. * SRFI-69 Table properties::
  4285. * SRFI-69 Hash table algorithms::
  4286. @end menu
  4287. @node SRFI-69 Creating hash tables
  4288. @subsubsection Creating hash tables
  4289. @deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size]
  4290. Create and answer a new hash table with @var{equal-proc} as the
  4291. equality function and @var{hash-proc} as the hashing function.
  4292. By default, @var{equal-proc} is @code{equal?}. It can be any
  4293. two-argument procedure, and should answer whether two keys are the
  4294. same for this table's purposes.
  4295. My default @var{hash-proc} assumes that @code{equal-proc} is no
  4296. coarser than @code{equal?} unless it is literally @code{string-ci=?}.
  4297. If provided, @var{hash-proc} should be a two-argument procedure that
  4298. takes a key and the current table size, and answers a reasonably good
  4299. hash integer between 0 (inclusive) and the size (exclusive).
  4300. @var{weakness} should be @code{#f} or a symbol indicating how ``weak''
  4301. the hash table is:
  4302. @table @code
  4303. @item #f
  4304. An ordinary non-weak hash table. This is the default.
  4305. @item key
  4306. When the key has no more non-weak references at GC, remove that entry.
  4307. @item value
  4308. When the value has no more non-weak references at GC, remove that
  4309. entry.
  4310. @item key-or-value
  4311. When either has no more non-weak references at GC, remove the
  4312. association.
  4313. @end table
  4314. As a legacy of the time when Guile couldn't grow hash tables,
  4315. @var{start-size} is an optional integer argument that specifies the
  4316. approximate starting size for the hash table, which will be rounded to
  4317. an algorithmically-sounder number.
  4318. @end deffn
  4319. By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and
  4320. @var{y} values where @code{(@var{equal-proc} @var{x} @var{y})},
  4321. @code{(equal? @var{x} @var{y})} as well. If that does not hold for
  4322. your @var{equal-proc}, you must provide a @var{hash-proc}.
  4323. In the case of weak tables, remember that @dfn{references} above
  4324. always refers to @code{eq?}-wise references. Just because you have a
  4325. reference to some string @code{"foo"} doesn't mean that an association
  4326. with key @code{"foo"} in a weak-key table @emph{won't} be collected;
  4327. it only counts as a reference if the two @code{"foo"}s are @code{eq?},
  4328. regardless of @var{equal-proc}. As such, it is usually only sensible
  4329. to use @code{eq?} and @code{hashq} as the equivalence and hash
  4330. functions for a weak table. @xref{Weak References}, for more
  4331. information on Guile's built-in weak table support.
  4332. @deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size]
  4333. As with @code{make-hash-table}, but initialize it with the
  4334. associations in @var{alist}. Where keys are repeated in @var{alist},
  4335. the leftmost association takes precedence.
  4336. @end deffn
  4337. @node SRFI-69 Accessing table items
  4338. @subsubsection Accessing table items
  4339. @deffn {Scheme Procedure} hash-table-ref table key [default-thunk]
  4340. @deffnx {Scheme Procedure} hash-table-ref/default table key default
  4341. Answer the value associated with @var{key} in @var{table}. If
  4342. @var{key} is not present, answer the result of invoking the thunk
  4343. @var{default-thunk}, which signals an error instead by default.
  4344. @code{hash-table-ref/default} is a variant that requires a third
  4345. argument, @var{default}, and answers @var{default} itself instead of
  4346. invoking it.
  4347. @end deffn
  4348. @deffn {Scheme Procedure} hash-table-set! table key new-value
  4349. Set @var{key} to @var{new-value} in @var{table}.
  4350. @end deffn
  4351. @deffn {Scheme Procedure} hash-table-delete! table key
  4352. Remove the association of @var{key} in @var{table}, if present. If
  4353. absent, do nothing.
  4354. @end deffn
  4355. @deffn {Scheme Procedure} hash-table-exists? table key
  4356. Answer whether @var{key} has an association in @var{table}.
  4357. @end deffn
  4358. @deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk]
  4359. @deffnx {Scheme Procedure} hash-table-update!/default table key modifier default
  4360. Replace @var{key}'s associated value in @var{table} by invoking
  4361. @var{modifier} with one argument, the old value.
  4362. If @var{key} is not present, and @var{default-thunk} is provided,
  4363. invoke it with no arguments to get the ``old value'' to be passed to
  4364. @var{modifier} as above. If @var{default-thunk} is not provided in
  4365. such a case, signal an error.
  4366. @code{hash-table-update!/default} is a variant that requires the
  4367. fourth argument, which is used directly as the ``old value'' rather
  4368. than as a thunk to be invoked to retrieve the ``old value''.
  4369. @end deffn
  4370. @node SRFI-69 Table properties
  4371. @subsubsection Table properties
  4372. @deffn {Scheme Procedure} hash-table-size table
  4373. Answer the number of associations in @var{table}. This is guaranteed
  4374. to run in constant time for non-weak tables.
  4375. @end deffn
  4376. @deffn {Scheme Procedure} hash-table-keys table
  4377. Answer an unordered list of the keys in @var{table}.
  4378. @end deffn
  4379. @deffn {Scheme Procedure} hash-table-values table
  4380. Answer an unordered list of the values in @var{table}.
  4381. @end deffn
  4382. @deffn {Scheme Procedure} hash-table-walk table proc
  4383. Invoke @var{proc} once for each association in @var{table}, passing
  4384. the key and value as arguments.
  4385. @end deffn
  4386. @deffn {Scheme Procedure} hash-table-fold table proc init
  4387. Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for
  4388. each @var{key} and @var{value} in @var{table}, where @var{previous} is
  4389. the result of the previous invocation, using @var{init} as the first
  4390. @var{previous} value. Answer the final @var{proc} result.
  4391. @end deffn
  4392. @deffn {Scheme Procedure} hash-table->alist table
  4393. Answer an alist where each association in @var{table} is an
  4394. association in the result.
  4395. @end deffn
  4396. @node SRFI-69 Hash table algorithms
  4397. @subsubsection Hash table algorithms
  4398. Each hash table carries an @dfn{equivalence function} and a @dfn{hash
  4399. function}, used to implement key lookups. Beginning users should
  4400. follow the rules for consistency of the default @var{hash-proc}
  4401. specified above. Advanced users can use these to implement their own
  4402. equivalence and hash functions for specialized lookup semantics.
  4403. @deffn {Scheme Procedure} hash-table-equivalence-function hash-table
  4404. @deffnx {Scheme Procedure} hash-table-hash-function hash-table
  4405. Answer the equivalence and hash function of @var{hash-table}, respectively.
  4406. @end deffn
  4407. @deffn {Scheme Procedure} hash obj [size]
  4408. @deffnx {Scheme Procedure} string-hash obj [size]
  4409. @deffnx {Scheme Procedure} string-ci-hash obj [size]
  4410. @deffnx {Scheme Procedure} hash-by-identity obj [size]
  4411. Answer a hash value appropriate for equality predicate @code{equal?},
  4412. @code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively.
  4413. @end deffn
  4414. @code{hash} is a backwards-compatible replacement for Guile's built-in
  4415. @code{hash}.
  4416. @node SRFI-71
  4417. @subsection SRFI-71 - Extended let-syntax for multiple values
  4418. @cindex SRFI-71
  4419. This SRFI shadows the forms for @code{let}, @code{let*}, and @code{letrec}
  4420. so that they may accept multiple values. For example:
  4421. @example
  4422. (use-modules (srfi srfi-71))
  4423. (let* ((x y (values 1 2))
  4424. (z (+ x y)))
  4425. (* z 2))
  4426. @result{} 6
  4427. @end example
  4428. See @uref{http://srfi.schemers.org/srfi-71/srfi-71.html, the
  4429. specification of SRFI-71}.
  4430. @node SRFI-87
  4431. @subsection SRFI-87 => in case clauses
  4432. @cindex SRFI-87
  4433. Starting from version 2.0.6, Guile's core @code{case} syntax supports
  4434. @code{=>} in clauses, as specified by SRFI-87/R7RS.
  4435. @xref{Conditionals}.
  4436. @node SRFI-88
  4437. @subsection SRFI-88 Keyword Objects
  4438. @cindex SRFI-88
  4439. @cindex keyword objects
  4440. @uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides
  4441. @dfn{keyword objects}, which are equivalent to Guile's keywords
  4442. (@pxref{Keywords}). SRFI-88 keywords can be entered using the
  4443. @dfn{postfix keyword syntax}, which consists of an identifier followed
  4444. by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
  4445. SRFI-88 can be made available with:
  4446. @example
  4447. (use-modules (srfi srfi-88))
  4448. @end example
  4449. Doing so installs the right reader option for keyword syntax, using
  4450. @code{(read-set! keywords 'postfix)}. It also provides the procedures
  4451. described below.
  4452. @deffn {Scheme Procedure} keyword? obj
  4453. Return @code{#t} if @var{obj} is a keyword. This is the same procedure
  4454. as the same-named built-in procedure (@pxref{Keyword Procedures,
  4455. @code{keyword?}}).
  4456. @example
  4457. (keyword? foo:) @result{} #t
  4458. (keyword? 'foo:) @result{} #t
  4459. (keyword? "foo") @result{} #f
  4460. @end example
  4461. @end deffn
  4462. @deffn {Scheme Procedure} keyword->string kw
  4463. Return the name of @var{kw} as a string, i.e., without the trailing
  4464. colon. The returned string may not be modified, e.g., with
  4465. @code{string-set!}.
  4466. @example
  4467. (keyword->string foo:) @result{} "foo"
  4468. @end example
  4469. @end deffn
  4470. @deffn {Scheme Procedure} string->keyword str
  4471. Return the keyword object whose name is @var{str}.
  4472. @example
  4473. (keyword->string (string->keyword "a b c")) @result{} "a b c"
  4474. @end example
  4475. @end deffn
  4476. @node SRFI-98
  4477. @subsection SRFI-98 Accessing environment variables.
  4478. @cindex SRFI-98
  4479. @cindex environment variables
  4480. This is a portable wrapper around Guile's built-in support for
  4481. interacting with the current environment, @xref{Runtime Environment}.
  4482. @deffn {Scheme Procedure} get-environment-variable name
  4483. Returns a string containing the value of the environment variable
  4484. given by the string @code{name}, or @code{#f} if the named
  4485. environment variable is not found. This is equivalent to
  4486. @code{(getenv name)}.
  4487. @end deffn
  4488. @deffn {Scheme Procedure} get-environment-variables
  4489. Returns the names and values of all the environment variables as an
  4490. association list in which both the keys and the values are strings.
  4491. @end deffn
  4492. @node SRFI-105
  4493. @subsection SRFI-105 Curly-infix expressions.
  4494. @cindex SRFI-105
  4495. @cindex curly-infix
  4496. @cindex curly-infix-and-bracket-lists
  4497. Guile's built-in reader includes support for SRFI-105 curly-infix
  4498. expressions. See @uref{http://srfi.schemers.org/srfi-105/srfi-105.html,
  4499. the specification of SRFI-105}. Some examples:
  4500. @example
  4501. @{n <= 5@} @result{} (<= n 5)
  4502. @{a + b + c@} @result{} (+ a b c)
  4503. @{a * @{b + c@}@} @result{} (* a (+ b c))
  4504. @{(- a) / b@} @result{} (/ (- a) b)
  4505. @{-(a) / b@} @result{} (/ (- a) b) as well
  4506. @{(f a b) + (g h)@} @result{} (+ (f a b) (g h))
  4507. @{f(a b) + g(h)@} @result{} (+ (f a b) (g h)) as well
  4508. @{f[a b] + g(h)@} @result{} (+ ($bracket-apply$ f a b) (g h))
  4509. '@{a + f(b) + x@} @result{} '(+ a (f b) x)
  4510. @{length(x) >= 6@} @result{} (>= (length x) 6)
  4511. @{n-1 + n-2@} @result{} (+ n-1 n-2)
  4512. @{n * factorial@{n - 1@}@} @result{} (* n (factorial (- n 1)))
  4513. @{@{a > 0@} and @{b >= 1@}@} @result{} (and (> a 0) (>= b 1))
  4514. @{f@{n - 1@}(x)@} @result{} ((f (- n 1)) x)
  4515. @{a . z@} @result{} ($nfx$ a . z)
  4516. @{a + b - c@} @result{} ($nfx$ a + b - c)
  4517. @end example
  4518. To enable curly-infix expressions within a file, place the reader
  4519. directive @code{#!curly-infix} before the first use of curly-infix
  4520. notation. To globally enable curly-infix expressions in Guile's reader,
  4521. set the @code{curly-infix} read option.
  4522. Guile also implements the following non-standard extension to SRFI-105:
  4523. if @code{curly-infix} is enabled and there is no other meaning assigned
  4524. to square brackets (i.e. the @code{square-brackets} read option is
  4525. turned off), then lists within square brackets are read as normal lists
  4526. but with the special symbol @code{$bracket-list$} added to the front.
  4527. To enable this combination of read options within a file, use the reader
  4528. directive @code{#!curly-infix-and-bracket-lists}. For example:
  4529. @example
  4530. [a b] @result{} ($bracket-list$ a b)
  4531. [a . b] @result{} ($bracket-list$ a . b)
  4532. @end example
  4533. For more information on reader options, @xref{Scheme Read}.
  4534. @node SRFI-111
  4535. @subsection SRFI-111 Boxes.
  4536. @cindex SRFI-111
  4537. @uref{http://srfi.schemers.org/srfi-111/srfi-111.html, SRFI-111}
  4538. provides boxes: objects with a single mutable cell.
  4539. @deffn {Scheme Procedure} box value
  4540. Return a newly allocated box whose contents is initialized to
  4541. @var{value}.
  4542. @end deffn
  4543. @deffn {Scheme Procedure} box? obj
  4544. Return true if @var{obj} is a box, otherwise return false.
  4545. @end deffn
  4546. @deffn {Scheme Procedure} unbox box
  4547. Return the current contents of @var{box}.
  4548. @end deffn
  4549. @deffn {Scheme Procedure} set-box! box value
  4550. Set the contents of @var{box} to @var{value}.
  4551. @end deffn
  4552. @c srfi-modules.texi ends here
  4553. @c Local Variables:
  4554. @c TeX-master: "guile.texi"
  4555. @c End: