dict-numbers.tex 158 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831
  1. % -*- Mode: TeX -*-
  2. \def\realtypespec#1{
  3. \label Compound Type Specifier Kind::
  4. Abbreviating.
  5. \label Compound Type Specifier Syntax::
  6. \Deftype{#1}{\ttbrac{lower-limit \brac{upper-limit}}}
  7. \label Compound Type Specifier Arguments::
  8. \param{lower-limit}, \param{upper-limit}---\term{interval designators}
  9. for \term{type} \typeref{#1}.
  10. \DefaultEach{\param{lower-limit} and \param{upper-limit}}{the \term{symbol} \misc{*}}
  11. \label Compound Type Specifier Description::
  12. This denotes the \term{#1s} on the interval described by
  13. \param{lower-limit} and \param{upper-limit}.
  14. }
  15. % Numbers
  16. % Numeric Comparison
  17. % Rounding
  18. % Trig
  19. % Hyperbolic Trig
  20. % Arithmetic
  21. % Random Numbers
  22. % Numeric Types
  23. % Complex
  24. % Real
  25. % Rational
  26. % Integer
  27. % Integer Bits
  28. % Integer Bytes
  29. % Fixnum
  30. % Ratio
  31. % Float
  32. % Float Subtypes
  33. %-------------------- Numeric Types --------------------
  34. \begincom{number}\ftype{System Class}
  35. \label Class Precedence List::
  36. \typeref{number},
  37. \typeref{t}
  38. \label Description::
  39. %%The following seems to fluffy to me. Besides you can find the same info elsewhere
  40. %%in more rigorous form. -kmp 13-Nov-90
  41. % There are \term{real} and \term{complex} \term{numbers}.
  42. % \term{Real} numbers are further divided into \term{floats},
  43. % \term{rationals}, and \term{integers}.
  44. %%Replaced by:
  45. \Thetype{number} contains \term{objects} which represent
  46. mathematical numbers.
  47. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  48. The \term{types} \typeref{real} and \typeref{complex} are \term{disjoint}
  49. \term{subtypes} of \typeref{number}.
  50. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  51. %I added this: -kmp 15-Nov-90
  52. \Thefunction{=} tests for numerical equality.
  53. \Thefunction{eql}, when its arguments are both \term{numbers},
  54. tests that they have both the same \term{type} and numerical value.
  55. %% 12.0.0 4
  56. Two \term{numbers} that are the \term{same} under \funref{eql} or \funref{=}
  57. are not necessarily the \term{same} under \funref{eq}.
  58. %% 2.1.4 1
  59. %% 2.1.4 4
  60. \label Notes::
  61. \clisp\ differs from mathematics on some naming issues. In mathematics,
  62. the set of real numbers is traditionally described as a subset of the
  63. complex numbers, but in \clisp, \thetype{real} and \thetype{complex} are
  64. disjoint. The \clisp\ type which includes all mathematical complex
  65. numbers is called \typeref{number}. The reasons for these differences
  66. include historical precedent, compatibility with most other popular
  67. computer languages, and various issues of time and space efficiency.
  68. %RWK notes:
  69. % Another way of describing this is that fundamental number types
  70. % fixnum, bignum, xxx-float, ratio, complex, ... all name representations
  71. % and are names for finite subsets of the corresponding mathematical concepts.
  72. % Thus, complex is a type which can represent complex numbers.
  73. % The extra capability of this type means that even if the imaginary part is 0.0,
  74. % it is not a member of the more restrictive representation real.
  75. %
  76. %Ultimately I didn't buy this because it presumes that types are only about
  77. %how a number is represented. But 1.0 is not represented as a real. In fact,
  78. %no number is. Rather, they are represented as subtypes of reals, and so real
  79. %is available only for categorization. Anyway, I decided to just let things stand
  80. %as they are for brevity and let others intuit other explanations that make them happy.
  81. \endcom%{number}\ftype{System Class}
  82. \begincom{complex}\ftype{System Class}
  83. \label Class Precedence List::
  84. \typeref{complex},
  85. \typeref{number},
  86. \typeref{t}
  87. \label Description::
  88. %RWK: Again, describe it as a representation which is -capable- of representing
  89. % complex numbers. 1.0 has a different, more restricted representation.
  90. \Thetype{complex} includes all mathematical complex numbers
  91. other than those included in \thetype{rational}.
  92. \term{Complexes} are
  93. %"represented" -> "expressed". Some reviewer had problems with "represented". -kmp
  94. expressed
  95. in Cartesian form with a
  96. real part and an imaginary part, each of which is a \term{real}.
  97. The real part and imaginary part are either both
  98. \term{rational} or both of the same \term{float} \term{type}.
  99. The imaginary part can be a \term{float} zero, but can never
  100. be a \term{rational} zero, for such a number is always represented
  101. by \clisp\ as a \term{rational} rather than a \term{complex}.
  102. \label Compound Type Specifier Kind::
  103. Specializing.
  104. \label Compound Type Specifier Syntax::
  105. %% 4.5.0 11
  106. \Deftype{complex}{\ttbrac{typespec | \misc{*}}}
  107. \label Compound Type Specifier Arguments::
  108. \param{typespec}---a \term{type specifier} that denotes a \subtypeof{real}.
  109. \label Compound Type Specifier Description::
  110. \editornote{KMP: If you ask me, this definition is a complete mess. Looking at
  111. issue ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING does not help me figure
  112. it out, either. Anyone got any suggestions?}
  113. Every element of this \term{type} is a \term{complex} whose
  114. real part and imaginary part are each of type
  115. \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  116. \f{(upgraded-complex-part-type \param{typespec})}.
  117. %The following will be left out:
  118. %\param{type}.
  119. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  120. This \term{type} encompasses those \term{complexes}
  121. that can result by giving numbers of \term{type} \param{typespec}
  122. to \funref{complex}.
  123. \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  124. %The following will be deleted:
  125. %
  126. %This might be different
  127. %from what the \term{type} means for discrimination purposes.
  128. %For example, Gaussian integers might be
  129. %described as the type {\tt (complex integer)}, even in implementations
  130. %where giving two \term{integers} to \funref{complex} results
  131. %in an \term{object} of type {\tt (complex rational)}.
  132. %
  133. %%%% 2.1.4 3
  134. %%The type of a specific \term{complex} is indicated by a list
  135. %%of the word \misc{complex} and the type of the components; for example,
  136. %%a specialized representation for \typeref{complex}
  137. %%numbers with \term{short float}
  138. %%parts would be of type {\tt (complex short-float)}. \Thetype{complex}
  139. %%encompasses all complex representations.
  140. %
  141. %End of deletion.
  142. {\tt (complex \param{type-specifier})}
  143. refers to all \term{complexes} that can result from giving
  144. \term{numbers} of \param{type} \param{type-specifier} to \thefunction{complex},
  145. plus all other \term{complexes} of the same specialized representation.
  146. %% Must fix the following according to Moon's 7-jul mail
  147. %% will fix for next edition.
  148. %Both the real and the imaginary parts of any such
  149. %\term{complex} must satisfy:
  150. %
  151. %{\tt (typep \lbracket \param{realpart} $\vert$ \param{imagpart}
  152. %\rbracket\ '\param{type-specifier})}
  153. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  154. \label See Also::
  155. {\secref\RuleOfCanonRepForComplexRationals},
  156. {\secref\NumsFromTokens},
  157. {\secref\PrintingComplexes}
  158. \label Notes::
  159. The input syntax for a \term{complex} with real part $r$ and
  160. imaginary part $i$ is \f{\#C($r$ $i$)}.
  161. For further details, \seesection\StandardMacroChars.
  162. For every \term{float}, $n$, there is a \term{complex}
  163. which represents the same mathematical number
  164. and which can be obtained by {\tt (COERCE $n$ 'COMPLEX)}.
  165. \endcom%{complex}\ftype{System Class}
  166. \begincom{real}\ftype{System Class}
  167. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  168. \label Class Precedence List::
  169. \typeref{real},
  170. \typeref{number},
  171. \typeref{t}
  172. \label Description::
  173. \Thetype{real} includes all \term{numbers} that
  174. represent mathematical real numbers, though there are mathematical real
  175. numbers (\eg irrational numbers) that do not have an exact representation
  176. in \clisp. Only \term{reals} can be ordered using the
  177. \funref{<}, \funref{>}, \funref{<=}, and \funref{>=} functions.
  178. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  179. The \term{types} \typeref{rational} and \typeref{float} are \term{disjoint}
  180. \subtypesof{real}.
  181. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  182. \realtypespec{real}
  183. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  184. \endcom%{real}\ftype{System Class}
  185. \begincom{float}\ftype{System Class}
  186. \label Class Precedence List::
  187. \typeref{float},
  188. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  189. \typeref{real},
  190. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  191. \typeref{number},
  192. \typeref{t}
  193. \label Description::
  194. A \term{float}
  195. is a mathematical rational (but \i{not} a \clisp\ \term{rational})
  196. of the form
  197. $s\cdot f\cdot b^{e-p}$,
  198. where $s$ is $+1$ or $-1$, the \i{sign};
  199. $b$ is an \term{integer}
  200. greater than~1, the \i{base} or \i{radix} of the representation;
  201. $p$ is a positive \term{integer},
  202. the \i{precision} (in base-$b$ digits) of the \term{float};
  203. $f$ is a positive \term{integer}
  204. between $b^{p-1}$ and
  205. $b^p-1$ (inclusive), the significand;
  206. and $e$ is an \term{integer}, the exponent.
  207. The value of $p$ and the range of~$e$
  208. depends on the implementation and on the type of \term{float}
  209. within that implementation. In addition, there is a floating-point zero;
  210. depending on the implementation, there can also be a ``minus zero''. If there
  211. is no minus zero, then $0.0$ and~$-0.0$ are both interpreted as simply a
  212. floating-point zero.
  213. {\tt (= 0.0 -0.0)} is always true.
  214. If there is a minus zero, {\tt (eql -0.0 0.0)} is \term{false},
  215. otherwise it is \term{true}.
  216. %!!!
  217. \reviewer{Barmar: What about IEEE NaNs and infinities?}
  218. %!!!
  219. \reviewer{RWK: In the following, what is the ``ordering''? precision? range?
  220. Can there be additional subtypes of float or does ``others'' in the
  221. list of four?}
  222. %% 2.15.0 12
  223. The \term{types} \typeref{short-float}, \typeref{single-float}, \typeref{double-float},
  224. and \typeref{long-float} are \subtypesof{float}. Any two of them must be
  225. either \term{disjoint} \term{types} or the \term{same} \term{type};
  226. if the \term{same} \term{type}, then any other \term{types} between them in the
  227. above ordering must also be the \term{same} \term{type}. For example,
  228. if \thetype{single-float} and \thetype{long-float} are the \term{same} \term{type},
  229. then \thetype{double-float} must be the \term{same} \term{type} also.
  230. \realtypespec{float}
  231. \label See Also::
  232. {\figref\SyntaxForNumericTokens},
  233. {\secref\NumsFromTokens},
  234. {\secref\PrintingFloats}
  235. \label Notes::
  236. Note that all mathematical integers are representable not only as
  237. \clisp\ \term{reals}, but also as \term{complex floats}. For example,
  238. possible representations of the mathematical number $1$
  239. include the \term{integer} \f{1},
  240. the \term{float} \f{1.0},
  241. or the \term{complex} \f{\#C(1.0 0.0)}.
  242. \endcom%{float}\ftype{System Class}
  243. \begincom{short-float, single-float, double-float, long-float}\ftype{Type}
  244. \label Supertypes::
  245. \typeref{short-float}:
  246. \typeref{short-float},
  247. \typeref{float},
  248. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  249. \typeref{real},
  250. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  251. \typeref{number},
  252. \typeref{t}
  253. \typeref{single-float}:
  254. \typeref{single-float},
  255. \typeref{float},
  256. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  257. \typeref{real},
  258. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  259. \typeref{number},
  260. \typeref{t}
  261. \typeref{double-float}:
  262. \typeref{double-float},
  263. \typeref{float},
  264. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  265. \typeref{real},
  266. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  267. \typeref{number},
  268. \typeref{t}
  269. \typeref{long-float}:
  270. \typeref{long-float},
  271. \typeref{float},
  272. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  273. \typeref{real},
  274. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  275. \typeref{number},
  276. \typeref{t}
  277. \label Description::
  278. For the four defined \subtypesof{float}, it is true that
  279. %% 2.1.3 6
  280. intermediate between \thetype{short-float} and \thetype{long-float} are
  281. \thetype{single-float} and \thetype{double-float}.
  282. The precise definition of these categories is
  283. %Changed from CLtL "\term{implementation-dependent}" by KMP per suggestion of Barmar.
  284. %Every implementation has to implement all the float-xxx inspection functions
  285. %anyway, so it's not really possible for an implementation to be wishy-washy
  286. %on this issue.
  287. \term{implementation-defined}.
  288. The precision (measured in ``bits'', computed as $p\log\sub{2}b$)
  289. and the exponent size (also measured in ``bits,'' computed as
  290. $\log\sub{2}(n+1)$, where $n$ is the maximum exponent value) is recommended
  291. to be at least as great
  292. as the values in \thenextfigure.
  293. Each of the defined \subtypesof{float} might or might not have a minus zero.
  294. \showthree{Recommended Minimum Floating-Point Precision and Exponent Size}{
  295. \hfil\b{Format}&
  296. \b{Minimum Precision}&
  297. \b{Minimum Exponent Size}\cr
  298. \noalign{\vskip 2pt\hrule\vskip 2pt}
  299. Short & 13 bits & 5 bits\cr
  300. Single & 24 bits & 8 bits\cr
  301. Double & 50 bits & 8 bits\cr
  302. Long & 50 bits & 8 bits\cr
  303. }
  304. %% 2.1.3 10
  305. %% 2.1.3 11
  306. %% 2.1.3 18
  307. There can be fewer than four internal
  308. representations for \term{floats}.
  309. If there are fewer distinct representations, the following rules apply:
  310. \beginlist
  311. \itemitem{--} If there is only one, it is
  312. %"of" removed -kmp 6-Jan-91
  313. \thetype{single-float}.
  314. In this representation, an \term{object} is simultaneously of \term{types}
  315. \typeref{single-float}, \typeref{double-float}, \typeref{short-float},
  316. and \typeref{long-float}.
  317. \itemitem{--} Two internal representations can be arranged in either of the
  318. following ways:
  319. \beginlist
  320. \itemitem{\bull} Two \term{types} are provided: \typeref{single-float} and
  321. \typeref{short-float}. An \term{object} is simultaneously
  322. of \term{types} \typeref{single-float}, \typeref{double-float}, and \typeref{long-float}.
  323. \itemitem{\bull} Two \term{types} are provided: \typeref{single-float} and
  324. \typeref{double-float}. An \term{object} is simultaneously of \term{types}
  325. \typeref{single-float} and \typeref{short-float}, or
  326. \typeref{double-float} and \typeref{long-float}.
  327. \endlist
  328. \itemitem{--} Three internal representations can be arranged in either
  329. of the following ways:
  330. \beginlist
  331. \itemitem{\bull} Three \term{types} are provided: \typeref{short-float},
  332. \typeref{single-float}, and \typeref{double-float}.
  333. An \term{object} can simultaneously be of \term{type} \typeref{double-float}
  334. and \typeref{long-float}.
  335. \itemitem{\bull} Three \term{types} are provided:
  336. \typeref{single-float}, \typeref{double-float},
  337. and \typeref{long-float}. An \term{object} can simultaneously
  338. be of \term{types} \typeref{single-float} and \typeref{short-float}.
  339. \endlist
  340. \endlist
  341. \label Compound Type Specifier Kind::
  342. Abbreviating.
  343. \label Compound Type Specifier Syntax::
  344. %% 4.6.0 8
  345. %% 4.6.0 9
  346. \Deftype{short-float}{\ttbrac{short-lower-limit \brac{short-upper-limit}}}
  347. \Deftype{single-float}{\ttbrac{single-lower-limit \brac{single-upper-limit}}}
  348. \Deftype{double-float}{\ttbrac{double-lower-limit \brac{double-upper-limit}}}
  349. \Deftype{long-float}{\ttbrac{long-lower-limit \brac{long-upper-limit}}}
  350. \label Compound Type Specifier Arguments::
  351. \param{short-lower-limit}, \param{short-upper-limit}---\term{interval designators}
  352. for \term{type} \typeref{short-float}.
  353. \DefaultEach{\param{lower-limit} and \param{upper-limit}}{the \term{symbol} \misc{*}}
  354. \param{single-lower-limit}, \param{single-upper-limit}---\term{interval designators}
  355. for \term{type} \typeref{single-float}.
  356. \DefaultEach{\param{lower-limit} and \param{upper-limit}}{the \term{symbol} \misc{*}}
  357. \param{double-lower-limit}, \param{double-upper-limit}---\term{interval designators}
  358. for \term{type} \typeref{double-float}.
  359. \DefaultEach{\param{lower-limit} and \param{upper-limit}}{the \term{symbol} \misc{*}}
  360. \param{long-lower-limit}, \param{long-upper-limit}---\term{interval designators}
  361. for \term{type} \typeref{long-float}.
  362. \DefaultEach{\param{lower-limit} and \param{upper-limit}}{the \term{symbol} \misc{*}}
  363. \label Compound Type Specifier Description::
  364. Each of these denotes the set of \term{floats} of the indicated \term{type}
  365. that are on the interval specified by the \term{interval designators}.
  366. \endcom%{short-float, single-float, double-float, long-float}\ftype{Type}
  367. \begincom{rational}\ftype{System Class}
  368. \label Class Precedence List::
  369. \typeref{rational},
  370. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  371. \typeref{real},
  372. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  373. \typeref{number},
  374. \typeref{t}
  375. \label Description::
  376. The canonical representation of a \term{rational}
  377. is as an \term{integer} if its value is integral,
  378. and otherwise as a \term{ratio}.
  379. %% 2.15.0 8
  380. The \term{types} \typeref{integer} and \typeref{ratio}
  381. are \term{disjoint} \subtypesof{rational}.
  382. \realtypespec{rational}
  383. \endcom%{rational}\ftype{System Class}
  384. \begincom{ratio}\ftype{System Class}
  385. \label Class Precedence List::
  386. \typeref{ratio},
  387. \typeref{rational},
  388. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  389. \typeref{real},
  390. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  391. \typeref{number},
  392. \typeref{t}
  393. \label Description::
  394. A \term{ratio} is a \term{number}
  395. representing the mathematical ratio of two non-zero integers,
  396. the numerator and denominator,
  397. whose greatest common divisor is one,
  398. and of which the denominator is positive and greater than one.
  399. \label See Also::
  400. {\figref\SyntaxForNumericTokens},
  401. {\secref\NumsFromTokens},
  402. {\secref\PrintingRatios}
  403. %% 2.1.1 1
  404. \endcom%{ratio}\ftype{System Class}
  405. \begincom{integer}\ftype{System Class}
  406. \label Class Precedence List::
  407. \typeref{integer},
  408. \typeref{rational},
  409. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  410. \typeref{real},
  411. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  412. \typeref{number},
  413. \typeref{t}
  414. \label Description::
  415. An \term{integer} is a mathematical integer. There is no limit on the
  416. magnitude of an \term{integer}.
  417. \issue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  418. %% 2.15.0 10
  419. The \term{types} \typeref{fixnum} and \typeref{bignum}
  420. form an \term{exhaustive partition} of \term{type} \typeref{integer}.
  421. %are \term{disjoint} \subtypesof{integer}.
  422. \endissue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  423. %% 2.1.1 2
  424. \realtypespec{integer}
  425. \label See Also::
  426. {\figref\SyntaxForNumericTokens},
  427. {\secref\NumsFromTokens},
  428. {\secref\PrintingIntegers}
  429. \label Notes::
  430. The \term{type} \f{(integer \i{lower} \i{upper})},
  431. where \i{lower} and \i{upper}
  432. are \funref{most-negative-fixnum} and \funref{most-positive-fixnum}, respectively,
  433. is also called \typeref{fixnum}.
  434. The \term{type} \f{(integer 0 1)} is also called \typeref{bit}.
  435. The \term{type} \f{(integer 0 *)} is also called \typeref{unsigned-byte}.
  436. \endcom%{integer}\ftype{System Class}
  437. \begincom{signed-byte}\ftype{Type}
  438. %Added per Barrett's suggestion. -kmp 23-Oct-90
  439. \label Supertypes::
  440. \typeref{signed-byte},
  441. \typeref{integer},
  442. \typeref{rational},
  443. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  444. \typeref{real},
  445. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  446. \typeref{number},
  447. \typeref{t}
  448. \label Description::
  449. The atomic \term{type specifier} \typeref{signed-byte} denotes the same
  450. type as is denoted by the \term{type specifier} \typeref{integer};
  451. however, the list forms of these two \term{type specifiers} have different semantics.
  452. %!!! Barrett thinks this syntax spec needs work.
  453. \label Compound Type Specifier Kind::
  454. Abbreviating.
  455. \label Compound Type Specifier Syntax::
  456. \Deftype{signed-byte}{\ttbrac{s | \misc{*}}}
  457. \label Compound Type Specifier Arguments::
  458. \param{s}---a positive \term{integer}.
  459. \label Compound Type Specifier Description::
  460. %% 4.6.0 5
  461. %\itemitem{\f{(signed-byte \param{s})}}
  462. This denotes the set of \term{integers} that can be represented
  463. in two's-complement form in a \term{byte} of \param{s} bits. This is
  464. equivalent to \f{(integer $-2^{s-1}$ $2^{s-1}-1$)}. The type
  465. \typeref{signed-byte} or the type \f{(signed-byte *)} is the same
  466. as \thetype{integer}.
  467. \endcom%{signed-byte}\ftype{Type}
  468. \begincom{unsigned-byte}\ftype{Type}
  469. %Added per Barrett's suggestion. -kmp 23-Oct-90
  470. \label Supertypes::
  471. \typeref{unsigned-byte},
  472. \typeref{signed-byte},
  473. \typeref{integer},
  474. \typeref{rational},
  475. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  476. \typeref{real},
  477. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  478. \typeref{number},
  479. \typeref{t}
  480. \label Description::
  481. %!!! Barrett thinks this should be more consistent with presentation of signed-byte.
  482. %!!! Barrett thinks we should be more careful about whitespace in the exponents here.
  483. The atomic \term{type specifier} \typeref{unsigned-byte} denotes the same
  484. type as is denoted by the \term{type specifier} \f{(integer 0 *)}.
  485. %% Barmar notes that this is redundant with what's said below.
  486. % The \term{type specifier} {\tt (unsigned-byte \param{s})} is equivalent to
  487. % {\tt (integer 0 $2^s-1$)}.
  488. \label Compound Type Specifier Kind::
  489. Abbreviating.
  490. \label Compound Type Specifier Syntax::
  491. %% 4.6.0 6
  492. \Deftype{unsigned-byte}{\ttbrac{\param{s} | \misc{*}}}
  493. \label Compound Type Specifier Arguments::
  494. % The "positive" was suggested by Barmar, and seems consistent with signed-byte.
  495. % -kmp 20-Oct-91
  496. \param{s}---a positive \term{integer}.
  497. \label Compound Type Specifier Description::
  498. This denotes the set of non-negative \term{integers} that can be
  499. represented in a byte of size \param{s} (bits).
  500. This is equivalent
  501. to \f{(mod \param{m})} for $\hbox{\param{m}}=2^s$, or
  502. to \f{(integer 0 \param{n})} for $\hbox{\param{n}}=2^s-1$.
  503. \Thetype{unsigned-byte} or
  504. the type \f{(unsigned-byte *)} is the same as
  505. the type \f{(integer 0 *)}, the set of non-negative \term{integers}.
  506. \label Notes::
  507. The \term{type} \f{(unsigned-byte 1)} is also called \typeref{bit}.
  508. \endcom%{unsigned-byte}\ftype{Type}
  509. %%% ========== MOD
  510. \begincom{mod}\ftype{Type Specifier}
  511. \label Compound Type Specifier Kind::
  512. Abbreviating.
  513. \label Compound Type Specifier Syntax::
  514. %% 4.6.0 4
  515. \Deftype{mod}{n}
  516. \label Compound Type Specifier Arguments::
  517. \param{n}---a positive \term{integer}.
  518. \label Compound Type Specifier Description::
  519. This denotes the set of non-negative \term{integers} less than \param{n}.
  520. This is equivalent to
  521. \f{(integer 0 (\param{n}))}
  522. or to
  523. \f{(integer 0 \param{m})},
  524. where $\hbox{\param{m}}=\hbox{\param{n}}-1$.
  525. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS}
  526. The argument is required, and cannot be \misc{*}.
  527. The symbol \typeref{mod} is not valid as a \term{type specifier}.
  528. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS}
  529. \endcom%{mod}\ftype{Type Specifier}
  530. %%% ========== BIT
  531. \begincom{bit}\ftype{Type}
  532. %Added per Barrett's suggestion. -kmp 23-Oct-90
  533. \label Supertypes::
  534. \typeref{bit},
  535. \typeref{unsigned-byte},
  536. \typeref{signed-byte},
  537. \typeref{integer},
  538. \typeref{rational},
  539. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  540. \typeref{real},
  541. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  542. \typeref{number},
  543. \typeref{t}
  544. \label Description::
  545. \Thetype{bit} is equivalent to the \term{type} \f{(integer 0 1)}
  546. and \f{(unsigned-byte 1)}.
  547. \endcom%{bit}\ftype{Type}
  548. %%% ========== FIXNUM
  549. \begincom{fixnum}\ftype{Type}
  550. \label Supertypes::
  551. \typeref{fixnum},
  552. \typeref{integer},
  553. \typeref{rational},
  554. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  555. \typeref{real},
  556. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  557. \typeref{number},
  558. \typeref{t}
  559. \label Description::
  560. A \term{fixnum} is an \term{integer} whose value is between
  561. \conref{most-negative-fixnum} and \conref{most-positive-fixnum} inclusive.
  562. Exactly which \term{integers} are \term{fixnums} is
  563. % CLtL said "\term{implementation-dependent}" but Barmar suggested (and I agree)
  564. % that implementations should say. -kmp 10-Oct-90
  565. \term{implementation-defined}.
  566. \issue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  567. The \term{type} \typeref{fixnum} is required to be a supertype of
  568. \f{(signed-byte 16)}.
  569. \endissue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  570. %Barrett thinks maybe some intentional information about fixnums
  571. %(e.g., about efficiency) might belong here. I don't that kind of thing is
  572. %appropriate so I haven't added it. -kmp 23-Oct-90
  573. \endcom%{fixnum}\ftype{Type}
  574. %%% ========== BIGNUM
  575. \begincom{bignum}\ftype{Type}
  576. \label Supertypes::
  577. \typeref{bignum},
  578. \typeref{integer},
  579. \typeref{rational},
  580. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  581. \typeref{real},
  582. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  583. \typeref{number},
  584. \typeref{t}
  585. \label Description::
  586. \issue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  587. \Thetype{bignum} is defined to be exactly \f{(and integer (not fixnum))}.
  588. \endissue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  589. %% 2.2.4 1
  590. \endcom%{bignum}\ftype{Type}
  591. %-------------------- Numeric Comparison --------------------
  592. %%% ========== =
  593. %%% ========== /=
  594. %%% ========== <
  595. %%% ========== >
  596. %%% ========== >=
  597. %%% ========== <=
  598. \begincom{=, /=, <, >, <=, >=}\ftype{Function}
  599. \label Syntax::
  600. \DefunWithValues = {{\rest} \plus{numbers}} {generalized-boolean}
  601. \DefunWithValues /= {{\rest} \plus{numbers}} {generalized-boolean}
  602. \DefunWithValues < {{\rest} \plus{numbers}} {generalized-boolean}
  603. \DefunWithValues > {{\rest} \plus{numbers}} {generalized-boolean}
  604. \DefunWithValues <= {{\rest} \plus{numbers}} {generalized-boolean}
  605. \DefunWithValues >= {{\rest} \plus{numbers}} {generalized-boolean}
  606. %!!! Issue CONTAGION-ON-NUMERICAL-COMPARISONS still needs to be merged? -kmp 9-Aug-91
  607. \label Arguments and Values::
  608. \param{number}---for \funref{<}, \funref{>}, \funref{<=}, \funref{>=}: a \term{real};
  609. for \funref{=}, \funref{/=}: a \term{number}.
  610. \param{generalized-boolean}---a \term{generalized boolean}.
  611. \label Description::
  612. \funref{=}, \funref{/=}, \funref{<}, \funref{>}, \funref{<=}, and \funref{>=}
  613. perform arithmetic comparisons on their arguments as follows:
  614. \beginlist
  615. \itemitem{\funref{=}}
  616. The value of \funref{=} is \term{true} if all \param{numbers} are the same in value;
  617. otherwise it is \term{false}.
  618. Two \term{complexes} are considered equal by \funref{=}
  619. if their real and imaginary parts are equal according to \funref{=}.
  620. \itemitem{\funref{/=}}
  621. The value of \funref{/=} is \term{true} if no two \param{numbers} are the same in value;
  622. otherwise it is \term{false}.
  623. \itemitem{\funref{<}}
  624. The value of \funref{<} is \term{true} if the \param{numbers} are in monotonically increasing order;
  625. otherwise it is \term{false}.
  626. \itemitem{\funref{>}}
  627. The value of \funref{>} is \term{true} if the \param{numbers} are in monotonically decreasing order;
  628. otherwise it is \term{false}.
  629. \itemitem{\funref{<=}}
  630. The value of \funref{<=} is \term{true} if the \param{numbers} are in monotonically
  631. nondecreasing order;
  632. otherwise it is \term{false}.
  633. \itemitem{\funref{>=}}
  634. The value of \funref{>=} is \term{true} if the \param{numbers} are in monotonically
  635. nonincreasing order;
  636. otherwise it is \term{false}.
  637. \endlist
  638. \funref{=}, \funref{/=}, \funref{<}, \funref{>}, \funref{<=}, and \funref{>=}
  639. perform necessary type conversions.
  640. \label Examples::
  641. The uses of these functions are illustrated in \thenextfigure.
  642. %% 12.3.0 4
  643. \showtwo{Uses of /=, =, <, >, <=, and >=}{
  644. \f{(= 3 3)} is \term{true}. & \f{(/= 3 3)} is \term{false}. \cr
  645. \f{(= 3 5)} is \term{false}. & \f{(/= 3 5)} is \term{true}. \cr
  646. \f{(= 3 3 3 3)} is \term{true}. & \f{(/= 3 3 3 3)} is \term{false}. \cr
  647. \f{(= 3 3 5 3)} is \term{false}. & \f{(/= 3 3 5 3)} is \term{false}. \cr
  648. \f{(= 3 6 5 2)} is \term{false}. & \f{(/= 3 6 5 2)} is \term{true}. \cr
  649. \f{(= 3 2 3)} is \term{false}. & \f{(/= 3 2 3)} is \term{false}. \cr
  650. \f{(< 3 5)} is \term{true}. & \f{(<= 3 5)} is \term{true}. \cr
  651. \f{(< 3 -5)} is \term{false}. & \f{(<= 3 -5)} is \term{false}. \cr
  652. \f{(< 3 3)} is \term{false}. & \f{(<= 3 3)} is \term{true}. \cr
  653. \f{(< 0 3 4 6 7)} is \term{true}. & \f{(<= 0 3 4 6 7)} is \term{true}. \cr
  654. \f{(< 0 3 4 4 6)} is \term{false}. & \f{(<= 0 3 4 4 6)} is \term{true}. \cr
  655. \f{(> 4 3)} is \term{true}. & \f{(>= 4 3)} is \term{true}. \cr
  656. \f{(> 4 3 2 1 0)} is \term{true}. & \f{(>= 4 3 2 1 0)} is \term{true}. \cr
  657. \f{(> 4 3 3 2 0)} is \term{false}. & \f{(>= 4 3 3 2 0)} is \term{true}. \cr
  658. \f{(> 4 3 1 2 0)} is \term{false}. & \f{(>= 4 3 1 2 0)} is \term{false}. \cr
  659. \f{(= 3)} is \term{true}. & \f{(/= 3)} is \term{true}. \cr
  660. \f{(< 3)} is \term{true}. & \f{(<= 3)} is \term{true}. \cr
  661. \f{(= 3.0 \#c(3.0 0.0))} is \term{true}. & \f{(/= 3.0 \#c(3.0 1.0))} is \term{true}.\cr
  662. \f{(= 3 3.0)} is \term{true}. & \f{(= 3.0s0 3.0d0)} is \term{true}. \cr
  663. \f{(= 0.0 -0.0)} is \term{true}. & \f{(= 5/2 2.5)} is \term{true}. \cr
  664. \f{(> 0.0 -0.0)} is \term{false}. & \f{(= 0 -0.0)} is \term{true}. \cr
  665. \f{(<= 0 x 9)} is \term{true} if \f{x} is between \f{0} and \f{9},
  666. inclusive\span\cr
  667. \f{(< 0.0 x 1.0)} is \term{true} if \f{x} is between \f{0.0} and \f{1.0},
  668. exclusive\span\cr
  669. \f{(< -1 j (length v))} is \term{true} if \f{j} is a \term{valid array index} for
  670. a \term{vector} \f{v}\span\cr
  671. }
  672. \label Affected By:\None.
  673. \label Exceptional Situations::
  674. Might signal \typeref{type-error} if some \term{argument} is not a \term{real}.
  675. Might signal \typeref{arithmetic-error} if otherwise unable to fulfill its contract.
  676. \label See Also:\None.
  677. \label Notes::
  678. \funref{=} differs from \funref{eql} in that
  679. \f{(= 0.0 -0.0)} is always true,
  680. because \funref{=} compares the mathematical values of its operands,
  681. whereas \funref{eql} compares the representational values, so to speak.
  682. \endcom
  683. %%% ========== MAX
  684. %%% ========== MIN
  685. \begincom{max, min}\ftype{Function}
  686. \label Syntax::
  687. \DefunWithValues max {{\rest} \plus{reals}} {max-real}
  688. \DefunWithValues min {{\rest} \plus{reals}} {min-real}
  689. \label Arguments and Values::
  690. \param{real}---a \term{real}.
  691. \param{max-real}, \param{min-real}---a \term{real}.
  692. \label Description::
  693. %% 12.3.0 8
  694. \funref{max} returns the \param{real} that is greatest (closest to positive infinity).
  695. \funref{min} returns the \param{real} that is least (closest to negative infinity).
  696. For \funref{max},
  697. the implementation has the choice of returning the largest
  698. argument as is or applying the rules of floating-point \term{contagion},
  699. taking all the arguments into consideration for \term{contagion} purposes.
  700. Also, if one or more of the arguments are \funref{=}, then any one
  701. of them may be chosen as the value to return.
  702. For example, if the \param{reals} are a mixture of \term{rationals} and \term{floats},
  703. and the largest argument is a \term{rational},
  704. then the implementation is free to
  705. produce either that \term{rational}
  706. or its \term{float} approximation;
  707. if the largest argument is a
  708. \term{float} of a smaller format
  709. than the largest format of any \term{float} argument,
  710. then the implementation is free to
  711. return the argument in its given format or expanded to the larger format.
  712. Similar remarks apply to \funref{min}
  713. (replacing ``largest argument'' by ``smallest argument'').
  714. \label Examples::
  715. %% 12.3.0 9
  716. \code
  717. (max 3) \EV 3
  718. (min 3) \EV 3
  719. (max 6 12) \EV 12
  720. (min 6 12) \EV 6
  721. (max -6 -12) \EV -6
  722. (min -6 -12) \EV -12
  723. (max 1 3 2 -7) \EV 3
  724. (min 1 3 2 -7) \EV -7
  725. (max -2 3 0 7) \EV 7
  726. (min -2 3 0 7) \EV -2
  727. (max 5.0 2) \EV 5.0
  728. (min 5.0 2)
  729. \EV 2
  730. \OV 2.0
  731. (max 3.0 7 1)
  732. \EV 7
  733. \OV 7.0
  734. (min 3.0 7 1)
  735. \EV 1
  736. \OV 1.0
  737. (max 1.0s0 7.0d0) \EV 7.0d0
  738. (min 1.0s0 7.0d0)
  739. \EV 1.0s0
  740. \OV 1.0d0
  741. (max 3 1 1.0s0 1.0d0)
  742. \EV 3
  743. \OV 3.0d0
  744. (min 3 1 1.0s0 1.0d0)
  745. \EV 1
  746. \OV 1.0s0
  747. \OV 1.0d0
  748. \endcode
  749. \label Side Effects:\None.
  750. \label Affected By:\None.
  751. \label Exceptional Situations::
  752. \Shouldcheckanytype{number}{a \term{real}}
  753. \label See Also:\None.
  754. \label Notes:\None.
  755. \endcom
  756. %%% ========== MINUSP
  757. %%% ========== PLUSP
  758. \begincom{minusp, plusp}\ftype{Function}
  759. \label Syntax::
  760. \DefunWithValues minusp {real} {generalized-boolean}
  761. \DefunWithValues plusp {real} {generalized-boolean}
  762. \label Arguments and Values::
  763. \param{real}---a \term{real}.
  764. \param{generalized-boolean}---a \term{generalized boolean}.
  765. \label Description::
  766. %% 12.2.0 4
  767. %% 12.2.0 5
  768. \NamedPredicate{minusp}{real}{less than zero}
  769. \NamedPredicate{plusp}{real}{greater than zero}
  770. Regardless of whether an \term{implementation} provides distinct
  771. representations for positive and negative \term{float} zeros,
  772. \f{(minusp -0.0)} always returns \term{false}.
  773. \label Examples::
  774. \code
  775. (minusp -1) \EV \term{true}
  776. (plusp 0) \EV \term{false}
  777. (plusp least-positive-single-float) \EV \term{true}
  778. \endcode
  779. \label Side Effects:\None.
  780. \label Affected By:\None.
  781. \label Exceptional Situations::
  782. \Shouldchecktype{real}{a \term{real}}
  783. \label See Also:\None.
  784. \label Notes:\None.
  785. \endcom
  786. %%% ========== ZEROP
  787. \begincom{zerop}\ftype{Function}
  788. \label Syntax::
  789. \DefunWithValues zerop {number} {generalized-boolean}
  790. \label Pronunciation::
  791. \pronounced{\Stress{z\harde}(\stress{})r\hardo{}(\stress{})p\harde}
  792. \label Arguments and Values::
  793. \param{number}---a \term{number}.
  794. \param{generalized-boolean}---a \term{generalized boolean}.
  795. \label Description::
  796. %% 12.2.0 3
  797. \Predicate{number}{zero (\term{integer}, \term{float}, or \term{complex})}
  798. Regardless of whether an \term{implementation} provides distinct representations
  799. for positive and negative floating-point zeros, \f{(zerop -0.0)}
  800. always returns \term{true}.
  801. \label Examples::
  802. \code
  803. (zerop 0) \EV \term{true}
  804. (zerop 1) \EV \term{false}
  805. (zerop -0.0) \EV \term{true}
  806. (zerop 0/100) \EV \term{true}
  807. (zerop #c(0 0.0)) \EV \term{true}
  808. \endcode
  809. \label Side Effects:\None.
  810. \label Affected By:\None.
  811. \label Exceptional Situations::
  812. \Shouldchecktype{number}{a \term{number}}
  813. \label See Also:\None.
  814. \label Notes::
  815. \code
  816. (zerop \param{number}) \EQ (= \param{number} 0)
  817. \endcode
  818. \endcom
  819. %-------------------- Rounding --------------------
  820. %%% ========== FLOOR
  821. %%% ========== CEILING
  822. %%% ========== TRUNCATE
  823. %%% ========== ROUND
  824. %%% ========== FFLOOR
  825. %%% ========== FCEILING
  826. %%% ========== FTRUNCATE
  827. %%% ========== FROUND
  828. \begincom{floor, ffloor, ceiling, fceiling,
  829. truncate, ftruncate, round, fround}\ftype{Function}
  830. \label Syntax::
  831. \DefunMultiWithValues {number {\opt} divisor} {quotient, remainder}
  832. {\entry{floor}
  833. \entry{ffloor}
  834. \entry{ceiling}
  835. \entry{fceiling}
  836. \entry{truncate}
  837. \entry{ftruncate}
  838. \entry{round}
  839. \entry{fround}}
  840. \label Arguments and Values::
  841. \param{number}---a \term{real}.
  842. \param{divisor}---a non-zero \term{real}.
  843. \Default{the \term{integer} \f{1}}
  844. \param{quotient}---for \funref{floor}, \funref{ceiling},
  845. \funref{truncate}, and \funref{round}: an \term{integer};
  846. for \funref{ffloor}, \funref{fceiling},
  847. \funref{ftruncate}, and \funref{fround}: a \term{float}.
  848. \param{remainder}---a \term{real}.
  849. \label Description::
  850. %% 12.6.0 16
  851. These functions divide \param{number} by \param{divisor},
  852. returning a \param{quotient} and \param{remainder}, such that
  853. \quad\param{quotient}\centerdot \param{divisor}+\param{remainder}=\param{number}
  854. The \param{quotient} always represents a mathematical integer.
  855. % For \funref{floor}, \funref{ceiling}, \funref{truncate}, and \funref{floor},
  856. % the \param{quotient} is represented as an \term{integer}.
  857. % For \funref{ffloor}, \funref{fceiling}, \funref{ftruncate}, and \funref{ffloor},
  858. % the \param{quotient} is represented as a \term{float}.
  859. When more than one mathematical integer might be possible
  860. (\ie when the remainder is not zero),
  861. the kind of rounding or truncation depends on the \term{operator}:
  862. \beginlist
  863. \itemitem{\funref{floor}, \funref{ffloor}}
  864. %% 12.6.0 11
  865. \funref{floor} and \funref{ffloor} produce a \param{quotient}
  866. that has been truncated toward negative infinity;
  867. that is, the \param{quotient} represents the largest mathematical integer
  868. that is not larger than the mathematical quotient.
  869. \itemitem{\funref{ceiling}, \funref{fceiling}}
  870. %% 12.6.0 12
  871. \funref{ceiling} and \funref{fceiling} produce a \param{quotient}
  872. that has been truncated toward positive infinity;
  873. that is, the \param{quotient} represents the smallest mathematical integer
  874. that is not smaller than the mathematical result.
  875. \itemitem{\funref{truncate}, \funref{ftruncate}}
  876. %% 12.6.0 13
  877. \funref{truncate} and \funref{ftruncate} produce a \param{quotient}
  878. that has been truncated towards zero;
  879. that is, the \param{quotient} represents the mathematical integer
  880. of the same sign as the mathematical quotient, and
  881. that has the greatest integral magnitude not greater than that of the mathematical quotient.
  882. \itemitem{\funref{round}, \funref{fround}}
  883. %% 12.6.0 14
  884. \funref{round} and \funref{fround} produce a \param{quotient}
  885. that has been rounded to the nearest mathematical integer;
  886. if the mathematical quotient is exactly halfway between two integers,
  887. (that is, it has the form \i{integer}+$1\over2$),
  888. then the \param{quotient} has been rounded to the even (divisible by two) integer.
  889. \endlist
  890. %!!! Cross reference
  891. All of these functions perform type conversion operations on \param{numbers}.
  892. The \param{remainder}
  893. is an \term{integer} if both \f{x} and \f{y} are \term{integers},
  894. is a \term{rational} if both \f{x} and \f{y} are \term{rationals}, and
  895. is a \term{float} if either \f{x} or \f{y} is a \term{float}.
  896. \funref{ffloor}, \funref{fceiling}, \funref{ftruncate}, and \funref{fround}
  897. handle arguments of different \term{types} in the following way:
  898. If \param{number} is a \term{float},
  899. and \param{divisor} is not a \term{float} of longer format,
  900. then the first result is a \term{float} of the same \term{type} as \param{number}.
  901. Otherwise, the first result is of the \term{type} determined by \term{contagion} rules;
  902. \seesection\NumericContagionRules.
  903. \label Examples::
  904. \code
  905. (floor 3/2) \EV 1, 1/2
  906. (ceiling 3 2) \EV 2, -1
  907. (ffloor 3 2) \EV 1.0, 1
  908. (ffloor -4.7) \EV -5.0, 0.3
  909. (ffloor 3.5d0) \EV 3.0d0, 0.5d0
  910. (fceiling 3/2) \EV 2.0, -1/2
  911. (truncate 1) \EV 1, 0
  912. (truncate .5) \EV 0, 0.5
  913. (round .5) \EV 0, 0.5
  914. (ftruncate -7 2) \EV -3.0, -1
  915. (fround -7 2) \EV -4.0, 1
  916. (dolist (n '(2.6 2.5 2.4 0.7 0.3 -0.3 -0.7 -2.4 -2.5 -2.6))
  917. (format t "~&~4,1@F ~2,' D ~2,' D ~2,' D ~2,' D"
  918. n (floor n) (ceiling n) (truncate n) (round n)))
  919. \OUT +2.6 2 3 2 3
  920. \OUT +2.5 2 3 2 2
  921. \OUT +2.4 2 3 2 2
  922. \OUT +0.7 0 1 0 1
  923. \OUT +0.3 0 1 0 0
  924. \OUT -0.3 -1 0 0 0
  925. \OUT -0.7 -1 0 0 -1
  926. \OUT -2.4 -3 -2 -2 -2
  927. \OUT -2.5 -3 -2 -2 -2
  928. \OUT -2.6 -3 -2 -2 -3
  929. \EV NIL
  930. \endcode
  931. %% ^-- 12.6.0 15
  932. \label Side Effects:\None.
  933. \label Affected By:\None.
  934. \label Exceptional Situations:\None.
  935. \label See Also:\None.
  936. \label Notes::
  937. %% 12.6.0 18
  938. When only \param{number} is given, the two results are exact;
  939. the mathematical sum of the two results is always equal to the
  940. mathematical value of \param{number}.
  941. %% 12.6.0 17
  942. \f{(\i{function} \param{number} \param{divisor})}
  943. and \f{(\i{function} (/ \param{number} \param{divisor}))}
  944. (where \i{function} is any of one
  945. of \funref{floor}, \funref{ceiling}, \funref{ffloor},
  946. \funref{fceiling}, \funref{truncate},
  947. \funref{round}, \funref{ftruncate}, and \funref{fround})
  948. return the same first value, but
  949. they return different remainders as the second value. For example:
  950. \code
  951. (floor 5 2) \EV 2, 1
  952. (floor (/ 5 2)) \EV 2, 1/2
  953. \endcode
  954. If an effect is desired that is similar to \funref{round},
  955. but that always rounds up or down (rather than toward the nearest even integer)
  956. if the mathematical quotient is exactly halfway between two integers,
  957. the programmer should consider a construction such as
  958. \f{(floor (+ x 1/2))}
  959. or \f{(ceiling (- x 1/2))}.
  960. \endcom
  961. %-------------------- Trig --------------------
  962. %%% ========== SIN
  963. %%% ========== COS
  964. %%% ========== TAN
  965. \begincom{sin, cos, tan}\ftype{Function}
  966. \label Syntax::
  967. \DefunWithValues sin {radians} {number}
  968. \DefunWithValues cos {radians} {number}
  969. \DefunWithValues tan {radians} {number}
  970. \label Arguments and Values::
  971. \param{radians}---a \term{number} given in radians.
  972. \param{number}---a \term{number}.
  973. \label Description::
  974. %% 12.5.2 14
  975. \funref{sin}, \funref{cos}, and \funref{tan}
  976. return the sine, cosine, and tangent, respectively, of \param{radians}.
  977. \label Examples::
  978. \code
  979. (sin 0) \EV 0.0
  980. (cos 0.7853982) \EV 0.707107
  981. (tan #c(0 1)) \EV #C(0.0 0.761594)
  982. \endcode
  983. \label Side Effects:\None.
  984. \label Affected By:\None.
  985. \label Exceptional Situations::
  986. \Shouldchecktype{radians}{a \term{number}}
  987. Might signal \typeref{arithmetic-error}.
  988. \label See Also::
  989. \funref{asin},
  990. \funref{acos},
  991. \funref{atan},
  992. {\secref\FloatSubstitutability}
  993. \label Notes:\None.
  994. \endcom
  995. %%% ========== ACOS
  996. %%% ========== ASIN
  997. %%% ========== ATAN
  998. \begincom{asin, acos, atan}\ftype{Function}
  999. \label Syntax::
  1000. \DefunWithValues asin {number} {radians}
  1001. \DefunWithValues acos {number} {radians}
  1002. \DefunWithValues atan {number1 {\opt} number2} {radians}
  1003. \label Arguments and Values::
  1004. \param{number}---a \term{number}.
  1005. \param{number1}---a \term{number} if \param{number2} is not supplied,
  1006. or a \term{real} if \param{number2} is supplied.
  1007. \param{number2}---a \term{real}.
  1008. \param{radians}---a \term{number} (of radians).
  1009. \label Description::
  1010. %% 12.5.2 17
  1011. \funref{asin}, \funref{acos}, and \funref{atan}
  1012. compute the arc sine, arc cosine, and arc tangent respectively.
  1013. %% 12.5.2 18
  1014. The arc sine, arc cosine, and arc tangent (with only \param{number1} supplied)
  1015. functions can be defined mathematically for
  1016. \param{number} or \param{number1} specified as \i{x} as in \thenextfigure.
  1017. \issue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1018. \tablefigtwo{Mathematical definition of arc sine, arc cosine, and arc tangent}%
  1019. {Function}{Definition}{
  1020. Arc sine & $ -i\ \ff{log} \bigl(ix+ \sqrt{1-x^2} \bigr) $ \cr
  1021. % --sjl 4 Mar 92
  1022. %Arc cosine & $ -i\ \ff{log} \bigl(x+i\ \sqrt{1-x^2} \bigr) $ \cr
  1023. Arc cosine & $ (\pi/2) - \ff{arcsin} x $ \cr
  1024. Arc tangent & $ -i\ \ff{log} \bigl((1+ix)\ \sqrt{1/(1+x^2)} \bigr) $ \cr
  1025. }
  1026. \endissue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1027. %% Barmar points out that these definitions are already given in the definitions
  1028. % of log and sqrt, so there's no need to repeat them here. -kmp 19-Dec-90
  1029. % where
  1030. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1031. % \f{(log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))} and
  1032. % \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}.
  1033. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1034. %% 12.5.2 19
  1035. These formulae are mathematically correct, assuming
  1036. completely accurate computation. They are not necessarily
  1037. the simplest ones for real-valued computations.
  1038. %% 12.5.2 21
  1039. %% 12.5.2 23
  1040. If both \param{number1} and \param{number2} are supplied
  1041. for \funref{atan}, the result is the arc tangent
  1042. of \hbox{\param{number1}/\param{number2}}.
  1043. The value of \funref{atan} is always between
  1044. $-\pi$ (exclusive) and~$\pi$ (inclusive)
  1045. \issue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1046. when minus zero is not supported.
  1047. The range of the two-argument arc tangent when minus zero is supported
  1048. includes $-\pi$.
  1049. \endissue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1050. For a
  1051. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1052. \term{real}
  1053. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1054. \param{number1},
  1055. the result is
  1056. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1057. a \term{real}
  1058. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1059. and lies between
  1060. $-\pi/2$ and~$\pi/2$ (both exclusive).
  1061. \param{number1} can be a \term{complex} if \param{number2}
  1062. is not supplied. If both are supplied, \param{number2} can be zero provided
  1063. \param{number1} is not zero.
  1064. \reviewer{Barmar: Should add ``However, if the implementation distinguishes
  1065. positive and negative zero, both may be signed zeros,
  1066. and limits are used to define the result.''}
  1067. %% 12.5.3 11
  1068. The following definition for arc sine determines the range and
  1069. branch cuts:
  1070. $$ \ff{arcsin} z = -i\ \ff{log} \Bigl(iz+\sqrt{1-z^2}\Bigr) $$
  1071. The branch cut for the arc sine function is in two pieces:
  1072. one along the negative real axis to the left of~$-1$
  1073. (inclusive), continuous with quadrant II, and one along the positive real
  1074. axis to the right of~$1$ (inclusive), continuous with quadrant IV. The
  1075. range is that strip of the complex plane containing numbers whose real
  1076. part is between $-\pi/2$ and~$\pi/2$. A number with real
  1077. part equal to $-\pi/2$ is in the range if and only if its imaginary
  1078. part is non-negative; a number with real part equal to $\pi/2$ is in
  1079. the range if and only if its imaginary part is non-positive.
  1080. %% 12.5.3 12
  1081. The following definition for arc cosine determines the range and
  1082. branch cuts:
  1083. % --sjl 4 Mar 92
  1084. \issue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1085. % $$ \ff{arccos} z = -i\ \ff{log} \Bigl(z+i\ \sqrt{1-z^2}\Bigr) $$
  1086. %
  1087. %or, which is equivalent,
  1088. %
  1089. % $$ \ff{arccos} z = {\pi\over2}- \ff{arcsin} z.$$
  1090. $$ \ff{arccos} z = {\pi\over2}- \ff{arcsin} z$$
  1091. or, which are equivalent,
  1092. $$ \ff{arccos} z = -i\ \ff{log} \Bigl(z+i\ \sqrt{1-z^2}\Bigr) $$
  1093. $$ \ff{arccos} z = {{2\ \ff{log} \bigl(\sqrt{(1+z)/2} + i\ \sqrt{(1-z)/2}\bigr)}\over{i}}$$
  1094. \endissue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1095. The branch cut for the arc cosine function is in two pieces:
  1096. one along the negative real axis to the left of~$-1$
  1097. (inclusive), continuous with quadrant II, and one along the positive real
  1098. axis to the right of~$1$ (inclusive), continuous with quadrant IV.
  1099. This is the same branch cut as for arc sine.
  1100. The range is that strip of the complex plane containing numbers whose real
  1101. part is between 0 and~$\pi$. A number with real
  1102. part equal to 0 is in the range if and only if its imaginary
  1103. part is non-negative; a number with real part equal to $\pi$ is in
  1104. the range if and only if its imaginary part is non-positive.
  1105. %% 12.5.3 13
  1106. The following definition for (one-argument) arc tangent determines the
  1107. range and branch cuts:
  1108. \issue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1109. $$ \ff{arctan} z = {{\ff{log} (1+iz) - \ff{log} (1-iz)}\over{2i}} $$
  1110. \endissue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1111. Beware of simplifying this formula; ``obvious'' simplifications are likely
  1112. to alter the branch cuts or the values on the branch cuts incorrectly.
  1113. The branch cut for the arc tangent function is in two pieces:
  1114. one along the positive imaginary axis above $i$
  1115. (exclusive), continuous with quadrant II, and one along the negative imaginary
  1116. axis below $-i$ (exclusive), continuous with quadrant IV.
  1117. The points $i$ and~$-i$ are excluded from the domain.
  1118. The range is that strip of the complex plane containing numbers whose real
  1119. part is between $-\pi/2$ and~$\pi/2$. A number with real
  1120. part equal to $-\pi/2$ is in the range if and only if its imaginary
  1121. part is strictly positive; a number with real part equal to $\pi/2$ is in
  1122. the range if and only if its imaginary part is strictly negative. Thus the range of
  1123. arc tangent is identical to that of arc sine with the points
  1124. $-\pi/2$ and~$\pi/2$ excluded.
  1125. For \funref{atan},
  1126. the signs of \param{number1} (indicated as \i{x})
  1127. and \param{number2} (indicated as \i{y}) are used to derive quadrant
  1128. information. \Thenextfigure\ details various special cases.
  1129. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1130. The asterisk (*) indicates that the entry in the figure applies to
  1131. implementations that support minus zero.
  1132. \def\Result{\hbox{result}}
  1133. \def\starY{\hbox to 1pc{*\hfil}}
  1134. \def\starN{\hbox to 1pc{\hfil}}
  1135. \tablefigfour{Quadrant information for arc tangent}%
  1136. {\starN\i{y} Condition}{\i{x} Condition}{Cartesian locus}{Range of result}{
  1137. \starN$ y = 0 $ & $ x > 0 $ & Positive x-axis & $ 0$ \cr
  1138. \starY$ y = +0 $ & $ x > 0 $ & Positive x-axis & $+0$ \cr
  1139. \starY$ y = -0 $ & $ x > 0 $ & Positive x-axis & $-0$ \cr
  1140. \starN$ y > 0 $ & $ x > 0 $ & Quadrant I & $0 < \Result < \pi/2 $ \cr
  1141. \starN$ y > 0 $ & $ x = 0 $ & Positive y-axis & $\pi/2$ \cr
  1142. \starN$ y > 0 $ & $ x < 0 $ & Quadrant II & $\pi/2 < \Result < \pi$ \cr
  1143. \starN$ y = 0 $ & $ x < 0 $ & Negative x-axis & $ \pi$ \cr
  1144. \starY$ y = +0 $ & $ x < 0 $ & Negative x-axis & $+\pi$ \cr
  1145. \starY$ y = -0 $ & $ x < 0 $ & Negative x-axis & $-\pi$ \cr
  1146. \starN$ y < 0 $ & $ x < 0 $ & Quadrant III & $-\pi < \Result < -\pi/2$ \cr
  1147. \starN$ y < 0 $ & $ x = 0 $ & Negative y-axis & $-\pi/2$ \cr
  1148. \starN$ y < 0 $ & $ x > 0 $ & Quadrant IV & $-\pi/2 < \Result < 0 $ \cr
  1149. \starN$ y = 0 $ & $ x = 0 $ & Origin & undefined consequences \cr
  1150. \starY$ y = +0 $ & $ x = +0 $ & Origin & $+0$ \cr
  1151. \starY$ y = -0 $ & $ x = +0 $ & Origin & $-0$ \cr
  1152. \starY$ y = +0 $ & $ x = -0 $ & Origin & $+\pi$ \cr
  1153. \starY$ y = -0 $ & $ x = -0 $ & Origin & $-\pi$ \cr
  1154. }
  1155. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1156. \label Examples::
  1157. \issue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1158. \code
  1159. (asin 0) \EV 0.0
  1160. (acos #c(0 1)) \EV #C(1.5707963267948966 -0.8813735870195432)
  1161. (/ (atan 1 (sqrt 3)) 6) \EV 0.087266
  1162. (atan #c(0 2)) \EV #C(-1.5707964 0.54930615)
  1163. \endcode
  1164. \endissue{COMPLEX-ATAN-BRANCH-CUT:TWEAK}
  1165. \label Affected By:\None.
  1166. \label Exceptional Situations::
  1167. \funref{acos} and \funref{asin} \shouldchecktype{number}{a \term{number}}
  1168. \funref{atan} should signal \typeref{type-error} if
  1169. one argument is supplied and that argument is not a \term{number},
  1170. or if two arguments are supplied and both of those arguments are not \term{reals}.
  1171. \funref{acos}, \funref{asin}, and \funref{atan} might signal \typeref{arithmetic-error}.
  1172. \label See Also::
  1173. \funref{log},
  1174. \funref{sqrt},
  1175. {\secref\FloatSubstitutability}
  1176. \label Notes::
  1177. The result of either \funref{asin} or \funref{acos} can be a \term{complex}
  1178. even if \param{number} is not a \term{complex}; this occurs when the
  1179. absolute value of \param{number} is greater than one.
  1180. \endcom
  1181. %%% ========== PI
  1182. \begincom{pi}\ftype{Constant Variable}
  1183. \label Value::
  1184. an \term{implementation-dependent} \term{long float}.
  1185. \label Description::
  1186. %% 12.5.2 28
  1187. The best \term{long float} approximation to the mathematical constant $\pi$.
  1188. \label Examples::
  1189. \code
  1190. ;; In each of the following computations, the precision depends
  1191. ;; on the implementation. Also, if `long float' is treated by
  1192. ;; the implementation as equivalent to some other float format
  1193. ;; (e.g., `double float') the exponent marker might be the marker
  1194. ;; for that equivalent (e.g., `D' instead of `L').
  1195. pi \EV 3.141592653589793L0
  1196. (cos pi) \EV -1.0L0
  1197. (defun sin-of-degrees (degrees)
  1198. (let ((x (if (floatp degrees) degrees (float degrees pi))))
  1199. (sin (* x (/ (float pi x) 180)))))
  1200. \endcode
  1201. \label See Also:\None.
  1202. \label Notes::
  1203. An approximation to $\pi$ in some other precision can be obtained
  1204. by writing \f{(float pi x)}, where \f{x} is a \term{float} of the
  1205. desired precision, or by writing \f{(coerce pi \i{type})},
  1206. where \i{type} is the desired type, such as \typeref{short-float}.
  1207. \endcom
  1208. %-------------------- Hyperbolic Trig --------------------
  1209. %%% ========== SINH
  1210. %%% ========== COSH
  1211. %%% ========== TANH
  1212. %%% ========== ASINH
  1213. %%% ========== ACOSH
  1214. %%% ========== ATANH
  1215. \begincom{sinh, cosh, tanh, asinh, acosh, atanh}\ftype{Function}
  1216. \label Syntax::
  1217. \DefunWithValues sinh {number} {result}
  1218. \DefunWithValues cosh {number} {result}
  1219. \DefunWithValues tanh {number} {result}
  1220. \DefunWithValues asinh {number} {result}
  1221. \DefunWithValues acosh {number} {result}
  1222. \DefunWithValues atanh {number} {result}
  1223. \label Arguments and Values::
  1224. \param{number}---a \term{number}.
  1225. \param{result}---a \term{number}.
  1226. \label Description::
  1227. These functions compute the hyperbolic sine, cosine, tangent,
  1228. arc sine, arc cosine, and arc tangent functions,
  1229. which are mathematically defined for an argument \i{x}
  1230. as given in \thenextfigure.
  1231. \issue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1232. \tablefigtwo{Mathematical definitions for hyperbolic functions}%
  1233. {Function}{Definition}{
  1234. Hyperbolic sine & $ (e^x-e^{-x})/2 $ \cr
  1235. Hyperbolic cosine & $ (e^x+e^{-x})/2 $ \cr
  1236. Hyperbolic tangent & $ (e^x-e^{-x})/(e^x+e^{-x}) $ \cr
  1237. Hyperbolic arc sine & $ \ff{log} (x+\sqrt{1+x^2}) $ \cr
  1238. % --sjl 4 Mar 92
  1239. %Hyperbolic arc cosine & $ \ff{log} (x+(x+1)\sqrt{(x-1)/(x+1)}) $ \cr
  1240. Hyperbolic arc cosine & $ 2\ \ff{log} (\sqrt{(x+1)/2} + \sqrt{(x-1)/2}) $ \cr
  1241. % --sjl 4 Mar 92
  1242. %Hyperbolic arc tangent & $ \ff{log} ((1+x)\sqrt{1-1/x^2}) $ \cr
  1243. Hyperbolic arc tangent & $ (\ff{log} (1+x) - \ff{log}(1-x))/2 $ \cr
  1244. }
  1245. \endissue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1246. %% Not needed. These are defined in the LOG and SQRT functions. -kmp 22-Jan-92
  1247. % where
  1248. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1249. % \f{(log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))} and
  1250. % \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}.
  1251. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1252. %% 12.5.3 15
  1253. The following definition for the inverse hyperbolic cosine
  1254. determines the range and branch cuts:
  1255. % --sjl 4 mar 92
  1256. \issue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1257. %$$ \ff{arccosh} z = \ff{log} \Bigl(z+(z+1)\sqrt{{{(z-1)}/{(z+1)}}}\Bigr). $$
  1258. $$ \ff{arccosh} z = 2\ \ff{log} \Bigl(\sqrt{(z+1)/2} + \sqrt{(z-1)/2}\Bigr). $$
  1259. \endissue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1260. %% This is said in the definitions of LOG and SQRT. -kmp 19-Jan-92
  1261. % where
  1262. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1263. % \f{(log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))} and
  1264. % \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}.
  1265. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1266. The branch cut for the inverse hyperbolic cosine function
  1267. lies along the real axis to the left of~$1$ (inclusive), extending
  1268. indefinitely along the negative real axis, continuous with quadrant II
  1269. and (between $0$ and~$1$) with quadrant I.
  1270. The range is that half-strip of the complex plane containing numbers whose
  1271. real part is non-negative and whose imaginary
  1272. part is between $-\pi$ (exclusive) and~$\pi$ (inclusive).
  1273. A number with real part zero is in the range
  1274. if its imaginary part is between zero (inclusive) and~$\pi$ (inclusive).
  1275. %% 12.5.3 14
  1276. The following definition for the inverse hyperbolic sine determines
  1277. the range and branch cuts:
  1278. %{\tt arcsinh \i{z}=log (\i{z}+$\sqrt{1+\i{z}^2}$)\/}
  1279. $$ \ff{arcsinh} z = \ff{log} \Bigl(z+\sqrt{1+z^2}\Bigr). $$
  1280. %% This is said in the definitions of LOG and SQRT. -kmp 19-Jan-92
  1281. % where
  1282. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1283. % {\tt (log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))\/} and
  1284. % {\tt (sqrt \i{x}) = (exp (/ (log \i{x}) 2))\/}.
  1285. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1286. The branch cut for the inverse hyperbolic sine function is in two pieces:
  1287. one along the positive imaginary axis above $i$
  1288. (inclusive), continuous with quadrant I, and one along the negative imaginary
  1289. axis below $-i$ (inclusive), continuous with quadrant III.
  1290. The range is that strip of the complex plane containing numbers whose imaginary
  1291. part is between $-\pi/2$ and~$\pi/2$. A number with imaginary
  1292. part equal to $-\pi/2$ is in the range if and only if its real
  1293. part is non-positive; a number with imaginary part equal to $\pi/2$ is in
  1294. the range if and only if its imaginary part is non-negative.
  1295. %% 12.5.3 16
  1296. The following definition for the inverse hyperbolic tangent
  1297. determines the range and branch cuts:
  1298. % --sjl 4 mar 92
  1299. \issue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1300. %$$ \ff{arctanh} z = \ff{log} \Bigl((1+z) \sqrt{1-1/z^2}\Bigr). $$
  1301. $$ \ff{arctanh} z = {{\ff{log} (1+z) - \ff{log} (1-z)}\over{2}}. $$
  1302. Note that:
  1303. $$ i\ \ff{arctan} z = \ff{arctanh} iz. $$
  1304. \endissue{COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE}
  1305. %% This is said in the definitions of LOG and SQRT. -kmp 19-Jan-92
  1306. % where
  1307. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1308. % \f{(log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))} and
  1309. % \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}.
  1310. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1311. % I believe this first sentence applied to the old, bogus formula.
  1312. % -- sjl 4 mar 92
  1313. %Beware of simplifying this formula; ``obvious'' simplifications are
  1314. %likely to alter the branch cuts or the values on the branch cuts
  1315. %incorrectly.
  1316. The branch cut for the inverse hyperbolic tangent function
  1317. is in two pieces: one along the negative real axis to the left of
  1318. $-1$ (inclusive), continuous with quadrant III, and one along
  1319. the positive real axis to the right of~$1$ (inclusive), continuous with
  1320. quadrant I. The points $-1$ and~$1$ are excluded from the
  1321. domain.
  1322. The range is that strip of the complex plane containing
  1323. numbers whose imaginary part is between $-\pi/2$ and
  1324. $\pi/2$. A number with imaginary part equal to $-\pi/2$
  1325. is in the range if and only if its real part is strictly negative; a number with
  1326. imaginary part equal to $\pi/2$ is in the range if and only if its imaginary
  1327. part is strictly positive.
  1328. Thus the range of the inverse hyperbolic tangent function is identical to
  1329. that of the inverse hyperbolic sine function with the points
  1330. $-\pi i/2$ and~$\pi i/2$ excluded.
  1331. \label Examples::
  1332. \code
  1333. (sinh 0) \EV 0.0
  1334. (cosh (complex 0 -1)) \EV #C(0.540302 -0.0)
  1335. \endcode
  1336. \label Side Effects:\None.
  1337. \label Affected By:\None.
  1338. \label Exceptional Situations::
  1339. \Shouldchecktype{number}{a \term{number}}
  1340. Might signal \typeref{arithmetic-error}.
  1341. \label See Also::
  1342. \funref{log},
  1343. \funref{sqrt},
  1344. {\secref\FloatSubstitutability}
  1345. \label Notes::
  1346. The result of \funref{acosh} may be a \term{complex} even if \param{number}
  1347. is not a \term{complex}; this occurs when \param{number} is less than one.
  1348. Also, the result of \funref{atanh} may be a \term{complex} even if \param{number}
  1349. is not a \term{complex}; this occurs when the absolute value of \param{number}
  1350. is greater than one.
  1351. %% 12.5.2 29
  1352. The branch cut formulae are mathematically correct, assuming
  1353. completely accurate computation.
  1354. Implementors should consult a good text on
  1355. numerical analysis. The formulae given above are not necessarily
  1356. the simplest ones for real-valued computations; they are chosen
  1357. to define the branch cuts in desirable ways for the complex case.
  1358. \endcom
  1359. %-------------------- Arithmetic --------------------
  1360. %%% ========== * (Function)
  1361. \begincom{*}\ftype{Function}
  1362. %% 12.4.0 8
  1363. \label Syntax::
  1364. \DefunWithValues * {{\rest} numbers} {product}
  1365. \label Arguments and Values::
  1366. \param{number}---a \term{number}.
  1367. \param{product}---a \term{number}.
  1368. \label Description::
  1369. Returns the product of \param{numbers},
  1370. performing any necessary type conversions in the process.
  1371. If no \param{numbers} are supplied, \f{1} is returned.
  1372. \label Examples::
  1373. \code
  1374. (*) \EV 1
  1375. (* 3 5) \EV 15
  1376. (* 1.0 #c(22 33) 55/98) \EV #C(12.346938775510203 18.520408163265305)
  1377. \endcode
  1378. \label Affected By:\None.
  1379. \label Exceptional Situations::
  1380. Might signal \typeref{type-error} if some \term{argument} is not a \term{number}.
  1381. Might signal \typeref{arithmetic-error}.
  1382. \label See Also::
  1383. {\secref\NumericOperations},
  1384. {\secref\RationalComputations},
  1385. {\secref\FloatingPointComputations},
  1386. {\secref\ComplexComputations}
  1387. \label Notes:\None.
  1388. \endcom
  1389. %%% ========== + (Function)
  1390. \begincom{+}\ftype{Function}
  1391. \label Syntax::
  1392. \DefunWithValues + {{\rest} numbers} {sum}
  1393. \label Arguments and Values::
  1394. \param{number}---a \term{number}.
  1395. \param{sum}---a \term{number}.
  1396. \label Description::
  1397. %% 12.4.0 3
  1398. Returns the sum of \param{numbers},
  1399. performing any necessary type conversions in the process.
  1400. If no \param{numbers} are supplied, \f{0} is returned.
  1401. \label Examples::
  1402. \code
  1403. (+) \EV 0
  1404. (+ 1) \EV 1
  1405. (+ 31/100 69/100) \EV 1
  1406. (+ 1/5 0.8) \EV 1.0
  1407. \endcode
  1408. \label Affected By:\None.
  1409. \label Exceptional Situations::
  1410. Might signal \typeref{type-error} if some \term{argument} is not a \term{number}.
  1411. Might signal \typeref{arithmetic-error}.
  1412. \label See Also::
  1413. {\secref\NumericOperations},
  1414. {\secref\RationalComputations},
  1415. {\secref\FloatingPointComputations},
  1416. {\secref\ComplexComputations}
  1417. \label Notes:\None.
  1418. \endcom
  1419. %%% ========== - (Function)
  1420. \begincom{$-$}\ftype{Function}
  1421. \label Syntax::
  1422. \DefunWithValues {$-$} {number} {negation}
  1423. \DefunWithValues {$-$} {minuend {\rest} \plus{subtrahends}} {difference}
  1424. \label Arguments and Values::
  1425. \param{number}, \param{minuend}, \param{subtrahend}---a \term{number}.
  1426. \param{negation}, \param{difference}---a \term{number}.
  1427. \label Description::
  1428. \Thefunction{-} performs arithmetic subtraction and negation.
  1429. %% 12.4.0 5
  1430. If only one \param{number} is supplied,
  1431. the negation of that \param{number} is returned.
  1432. %% 12.4.0 6
  1433. If more than one \term{argument} is given,
  1434. it subtracts all of the \param{subtrahends} from the \param{minuend}
  1435. and returns the result.
  1436. \Thefunction{-} performs necessary type conversions.
  1437. \label Examples::
  1438. \code
  1439. (- 55.55) \EV -55.55
  1440. (- #c(3 -5)) \EV #C(-3 5)
  1441. (- 0) \EV 0
  1442. (eql (- 0.0) -0.0) \EV \term{true}
  1443. (- #c(100 45) #c(0 45)) \EV 100
  1444. (- 10 1 2 3 4) \EV 0
  1445. \endcode
  1446. \label Affected By:\None.
  1447. \label Exceptional Situations::
  1448. Might signal \typeref{type-error} if some \term{argument} is not a \term{number}.
  1449. Might signal \typeref{arithmetic-error}.
  1450. \label See Also::
  1451. {\secref\NumericOperations},
  1452. {\secref\RationalComputations},
  1453. {\secref\FloatingPointComputations},
  1454. {\secref\ComplexComputations}
  1455. \label Notes:\None.
  1456. \endcom
  1457. %%% ========== / (Function)
  1458. \begincom{/}\ftype{Function}
  1459. \label Syntax::
  1460. \DefunWithValues / {number} {reciprocal}
  1461. \DefunWithValues / {numerator {\rest} \plus{denominators}} {quotient}
  1462. \label Arguments and Values::
  1463. \param{number}, \param{denominator}---a non-zero \term{number}.
  1464. \param{numerator}, \param{quotient}, \param{reciprocal}---a \term{number}.
  1465. \label Description::
  1466. %% 12.4.0 10
  1467. \Thefunction{/} performs division or reciprocation.
  1468. %% 12.4.0 11
  1469. If no \param{denominators} are supplied,
  1470. \thefunction{/} returns the reciprocal of \param{number}.
  1471. If at least one \param{denominator} is supplied,
  1472. \thefunction{/} divides the \param{numerator} by all of the \param{denominators}
  1473. and returns the resulting \param{quotient}.
  1474. %% 12.4.0 12
  1475. If each \term{argument} is either an \term{integer} or a \term{ratio},
  1476. and the result is not an \term{integer}, then it is a \term{ratio}.
  1477. \Thefunction{/} performs necessary type conversions.
  1478. %% 12.4.0 14
  1479. If any \param{argument} is a \term{float} then
  1480. the rules of floating-point contagion apply;
  1481. \seesection\FloatingPointComputations.
  1482. \label Examples::
  1483. \code
  1484. (/ 12 4) \EV 3
  1485. (/ 13 4) \EV 13/4
  1486. (/ -8) \EV -1/8
  1487. (/ 3 4 5) \EV 3/20
  1488. (/ 0.5) \EV 2.0
  1489. (/ 20 5) \EV 4
  1490. (/ 5 20) \EV 1/4
  1491. (/ 60 -2 3 5.0) \EV -2.0
  1492. (/ 2 #c(2 2)) \EV #C(1/2 -1/2)
  1493. \endcode
  1494. \label Affected By:\None.
  1495. \label Exceptional Situations::
  1496. The consequences are unspecified if any \term{argument} other than the first is zero.
  1497. If there is only one \term{argument}, the consequences are unspecified if it is zero.
  1498. Might signal \typeref{type-error} if some \term{argument} is not a \term{number}.
  1499. Might signal \typeref{division-by-zero} if division by zero is attempted.
  1500. Might signal \typeref{arithmetic-error}.
  1501. \label See Also::
  1502. \funref{floor}, \funref{ceiling}, \funref{truncate}, \funref{round}
  1503. \label Notes:\None.
  1504. \endcom
  1505. %%% ========== 1+
  1506. %%% ========== 1-
  1507. \begincom{1+, 1$-$}\ftype{Function}
  1508. \label Syntax::
  1509. \DefunWithValues 1+ {number} {successor}
  1510. \DefunWithValues 1$-$ {number} {predecessor}
  1511. \label Arguments and Values::
  1512. \param{number}---a \term{number}.
  1513. \param{successor}, \param{predecessor}---a \term{number}.
  1514. \label Description::
  1515. %%12.4.0 17
  1516. \funref{1+} returns a \term{number} that is one more than its argument \param{number}.
  1517. \funref{1-} returns a \term{number} that is one less than its argument \param{number}.
  1518. \label Examples::
  1519. \code
  1520. (1+ 99) \EV 100
  1521. (1- 100) \EV 99
  1522. (1+ (complex 0.0)) \EV #C(1.0 0.0)
  1523. (1- 5/3) \EV 2/3
  1524. \endcode
  1525. \label Affected By:\None.
  1526. \label Exceptional Situations::
  1527. Might signal \typeref{type-error} if its \term{argument} is not a \term{number}.
  1528. Might signal \typeref{arithmetic-error}.
  1529. \label See Also::
  1530. \macref{incf}, \macref{decf}
  1531. \label Notes::
  1532. \code
  1533. (1+ \param{number}) \EQ (+ \param{number} 1)
  1534. (1- \param{number}) \EQ (- \param{number} 1)
  1535. \endcode
  1536. Implementors are encouraged to make the performance of both the previous
  1537. expressions be the same.
  1538. \endcom
  1539. %%% ========== ABS
  1540. \begincom{abs}\ftype{Function}
  1541. \label Syntax::
  1542. \DefunWithValues abs {number} {absolute-value}
  1543. \label Arguments and Values::
  1544. \param{number}---a \term{number}.
  1545. \param{absolute-value}---a non-negative \term{real}.
  1546. \label Description::
  1547. %% 12.5.2 3
  1548. \funref{abs} returns the absolute value of \param{number}.
  1549. %% 12.5.2 4
  1550. If \param{number} is
  1551. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1552. a \term{real},
  1553. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1554. the result is of the same \term{type} as \param{number}.
  1555. If \param{number} is a \term{complex},
  1556. the result is a positive
  1557. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1558. \term{real}
  1559. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1560. with
  1561. the same magnitude as \param{number}.
  1562. The result can be a \term{float}
  1563. \reviewer{Barmar: Single-float.}%!!! What to do here? -kmp 17-Dec-90
  1564. even if \param{number}'s components are \term{rationals}
  1565. and an exact rational result
  1566. would have been possible.
  1567. %% 12.5.2 7
  1568. Thus the result of \f{(abs \#c(3 4))} can be either \f{5} or \f{5.0},
  1569. depending on the implementation.
  1570. \label Examples::
  1571. \issue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1572. \code
  1573. (abs 0) \EV 0
  1574. (abs 12/13) \EV 12/13
  1575. (abs -1.09) \EV 1.09
  1576. (abs #c(5.0 -5.0)) \EV 7.071068
  1577. (abs #c(5 5)) \EV 7.071068
  1578. (abs #c(3/5 4/5)) \EV 1 or approximately 1.0
  1579. (eql (abs -0.0) -0.0) \EV \term{true}
  1580. \endcode
  1581. \endissue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1582. \label Affected By:\None.
  1583. \label Exceptional Situations:\None.
  1584. \label See Also::
  1585. {\secref\FloatSubstitutability}
  1586. \label Notes::
  1587. %% 12.5.2 5
  1588. If \param{number} is a \term{complex},
  1589. the result is equivalent to the following:
  1590. %\hfil\break
  1591. \f{(sqrt (+ (expt (realpart \param{number}) 2) (expt (imagpart \param{number}) 2)))}
  1592. %%Barmar says ``SQRT is a defined name, so there's no need to redefine it here.''
  1593. % -kmp 17-Dec-90
  1594. % , where
  1595. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1596. % \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}
  1597. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1598. %% 12.5.2 6
  1599. An implementation should not use this formula directly
  1600. for all \term{complexes}
  1601. but should handle very large or very small components specially
  1602. to avoid intermediate overflow or underflow.
  1603. \endcom
  1604. %%% ========== EVENP
  1605. %%% ========== ODDP
  1606. \begincom{evenp, oddp}\ftype{Function}
  1607. \label Syntax::
  1608. \DefunWithValues evenp {integer} {generalized-boolean}
  1609. \DefunWithValues oddp {integer} {generalized-boolean}
  1610. \label Arguments and Values::
  1611. \param{integer}---an \term{integer}.
  1612. \param{generalized-boolean}---a \term{generalized boolean}.
  1613. \label Description::
  1614. %% 12.2.0 7
  1615. \NamedPredicate{evenp}{integer}{even (divisible by two)}
  1616. %% 12.2.0 6
  1617. \NamedPredicate{oddp}{integer}{odd (not divisible by two)}
  1618. \label Examples::
  1619. \code
  1620. (evenp 0) \EV \term{true}
  1621. (oddp 10000000000000000000000) \EV \term{false}
  1622. (oddp -1) \EV \term{true}
  1623. \endcode
  1624. \label Side Effects:\None.
  1625. \label Affected By:\None.
  1626. \label Exceptional Situations::
  1627. \Shouldchecktype{integer}{an \term{integer}}
  1628. \label See Also:\None.
  1629. \label Notes::
  1630. \code
  1631. (evenp \param{integer}) \EQ (not (oddp \param{integer}))
  1632. (oddp \param{integer}) \EQ (not (evenp \param{integer}))
  1633. \endcode
  1634. \endcom
  1635. %%% ========== EXP
  1636. %%% ========== EXPT
  1637. \begincom{exp, expt}\ftype{Function}
  1638. \label Syntax::
  1639. \DefunWithValues exp {number} {result}
  1640. \DefunWithValues expt {base-number power-number} {result}
  1641. \label Arguments and Values::
  1642. \param{number}---a \term{number}.
  1643. \param{base-number}---a \term{number}.
  1644. \param{power-number}---a \term{number}.
  1645. \param{result}---a \term{number}.
  1646. \label Description::
  1647. \funref{exp} and \funref{expt} perform exponentiation.
  1648. %% 12.5.1 2
  1649. \funref{exp} returns \i{e} raised to the power \param{number},
  1650. where \i{e} is the base of the natural logarithms.
  1651. %% 12.5.3 9
  1652. \funref{exp} has no branch cut.
  1653. %% 12.5.0 5
  1654. %% 12.5.1 3
  1655. \funref{expt} returns \param{base-number}
  1656. raised to the power \param{power-number}.
  1657. If the \param{base-number} is a \term{rational}
  1658. and \param{power-number} is
  1659. an \term{integer},
  1660. the calculation is exact and the result will be \oftype{rational};
  1661. otherwise a floating-point approximation might result.
  1662. \issue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1663. For \funref{expt} of a \term{complex rational} to an \term{integer} power,
  1664. the calculation must be exact and the result is
  1665. of type \f{(or rational (complex rational))}.
  1666. \endissue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1667. %% 12.5.1 6
  1668. The result of \funref{expt} can be a \term{complex},
  1669. even when neither argument is a \term{complex},
  1670. if \param{base-number} is negative and \param{power-number}
  1671. is not an \term{integer}.
  1672. The result is always the \term{principal} \term{complex} \term{value}.
  1673. For example, \f{(expt -8 1/3)} is not permitted to return \f{-2},
  1674. even though \f{-2} is one of the cube roots of \f{-8}.
  1675. The \term{principal} cube root is a \term{complex}
  1676. approximately equal to \f{\#C(1.0 1.73205)}, not \f{-2}.
  1677. %% 12.5.3 10
  1678. \funref{expt} is defined
  1679. as \i{$b^x$ = $e^{x log b\/}$}.
  1680. %%Barmar thinks this should just cross-reference the LOG function. (I agree.) -kmp 22-Jan-92
  1681. %% This is defined in LOG.
  1682. % , where
  1683. % \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1684. % \f{(log \i{b}) = (complex (log (abs \i{b})) (phase \i{b}))}.
  1685. % \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1686. This defines the \term{principal} \term{values} precisely. The range of
  1687. \funref{expt} is the entire complex plane. Regarded
  1688. as a function of \i{x}, with \i{b} fixed, there is no branch cut.
  1689. Regarded as a function of \i{b}, with \i{x} fixed, there is in general
  1690. a branch cut along the negative real axis, continuous with quadrant II.
  1691. The domain excludes the origin.
  1692. By definition, $0^0$=1. If \i{b}=0 and the real part of \i{x} is strictly
  1693. positive, then
  1694. \i{$b^x$}=0. For all other values of \i{x}, $0^\i{x}$
  1695. is an error.
  1696. %% 12.5.1 4
  1697. When \param{power-number} is an \term{integer} \f{0},
  1698. then the result is always the value one in the \term{type}
  1699. of \param{base-number},
  1700. even if the \param{base-number} is zero (of any \term{type}). That is:
  1701. \code
  1702. (expt x 0) \EQ (coerce 1 (type-of x))
  1703. \endcode
  1704. If \param{power-number} is a zero of any other \term{type},
  1705. then the result is also the value one, in the \term{type} of the arguments
  1706. after the application of the contagion rules in \secref\NumericContagionRules,
  1707. with one exception:
  1708. the consequences are undefined if \param{base-number} is zero when \param{power-number}
  1709. is zero and not \oftype{integer}.
  1710. \label Examples::
  1711. \issue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1712. \code
  1713. (exp 0) \EV 1.0
  1714. (exp 1) \EV 2.718282
  1715. (exp (log 5)) \EV 5.0
  1716. (expt 2 8) \EV 256
  1717. (expt 4 .5) \EV 2.0
  1718. (expt #c(0 1) 2) \EV -1
  1719. (expt #c(2 2) 3) \EV #C(-16 16)
  1720. (expt #c(2 2) 4) \EV -64
  1721. \endcode
  1722. \endissue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1723. \label Affected By:\None.
  1724. \label Exceptional Situations:\None.
  1725. \label See Also::
  1726. \funref{log},
  1727. {\secref\FloatSubstitutability}
  1728. \label Notes::
  1729. %% 12.5.1 5
  1730. Implementations of \funref{expt} are permitted to use different algorithms
  1731. for the cases of a \param{power-number} \oftype{rational}
  1732. and a \param{power-number} \oftype{float}.
  1733. \issue{EXPT-RATIO:P.211}
  1734. Note that by the following logic,
  1735. \f{(sqrt (expt \i{x} 3))} is not equivalent to
  1736. \f{(expt \i{x} 3/2)}.
  1737. %!!! Figure out some way to notate these `precise approximations'
  1738. \code
  1739. (setq x (exp (/ (* 2 pi #c(0 1)) 3))) ;exp(2.pi.i/3)
  1740. (expt x 3) \EV 1 ;except for round-off error
  1741. (sqrt (expt x 3)) \EV 1 ;except for round-off error
  1742. (expt x 3/2) \EV -1 ;except for round-off error
  1743. \endcode
  1744. \endissue{EXPT-RATIO:P.211}
  1745. \endcom
  1746. %%% ========== GCD
  1747. \begincom{gcd}\ftype{Function}
  1748. \label Syntax::
  1749. \DefunWithValues gcd {{\rest} integers} {greatest-common-denominator}
  1750. \label Arguments and Values::
  1751. \param{integer}---an \term{integer}.
  1752. \param{greatest-common-denominator}---a non-negative \term{integer}.
  1753. \label Description::
  1754. %% 12.4.0 22
  1755. Returns the greatest common divisor of \param{integers}.
  1756. If only one \param{integer} is supplied, its absolute value is returned.
  1757. If no \param{integers} are given, \funref{gcd} returns \f{0},
  1758. which is an identity for this operation.
  1759. \label Examples::
  1760. %% 12.4.0 23
  1761. \code
  1762. (gcd) \EV 0
  1763. (gcd 60 42) \EV 6
  1764. (gcd 3333 -33 101) \EV 1
  1765. (gcd 3333 -33 1002001) \EV 11
  1766. (gcd 91 -49) \EV 7
  1767. (gcd 63 -42 35) \EV 7
  1768. (gcd 5) \EV 5
  1769. (gcd -4) \EV 4
  1770. \endcode
  1771. \label Side Effects:\None.
  1772. \label Affected By:\None.
  1773. \label Exceptional Situations::
  1774. \Shouldcheckanytype{integer}{an \term{integer}}
  1775. \label See Also::
  1776. \funref{lcm}
  1777. \label Notes::
  1778. For three or more arguments,
  1779. \code
  1780. (gcd b c ... z) \EQ (gcd (gcd a b) c ... z)
  1781. \endcode
  1782. \endcom
  1783. %%% ========== INCF
  1784. %%% ========== DECF
  1785. \begincom{incf, decf}\ftype{Macro}
  1786. \label Syntax::
  1787. \DefmacWithValues incf {place \brac{delta-form}} {new-value}
  1788. \DefmacWithValues decf {place \brac{delta-form}} {new-value}
  1789. \label Arguments and Values::
  1790. \param{place}---a \term{place}.
  1791. \param{delta-form}---a \term{form}; evaluated to produce a \param{delta}.
  1792. \Default{\f{1}}
  1793. \param{delta}---a \term{number}.
  1794. \param{new-value}---a \term{number}.
  1795. \label Description::
  1796. \macref{incf} and \macref{decf} are used for incrementing and
  1797. decrementing the \term{value} of \param{place}, respectively.
  1798. The \param{delta} is
  1799. added to (in the case of \macref{incf})
  1800. or subtracted from (in the case of \macref{decf})
  1801. the number in \param{place} and the result is stored in \param{place}.
  1802. Any necessary type conversions are performed automatically.
  1803. \issue{PUSH-EVALUATION-ORDER:FIRST-ITEM}
  1804. For information about the \term{evaluation} of \term{subforms} of \param{places},
  1805. \seesection\GenRefSubFormEval.
  1806. \endissue{PUSH-EVALUATION-ORDER:FIRST-ITEM}
  1807. \label Examples::
  1808. \code
  1809. (setq n 0)
  1810. (incf n) \EV 1
  1811. n \EV 1
  1812. (decf n 3) \EV -2
  1813. n \EV -2
  1814. (decf n -5) \EV 3
  1815. (decf n) \EV 2
  1816. (incf n 0.5) \EV 2.5
  1817. (decf n) \EV 1.5
  1818. n \EV 1.5
  1819. \endcode
  1820. \label Side Effects::
  1821. \param{Place} is modified.
  1822. \label Affected By:\None.
  1823. \label Exceptional Situations:\None.
  1824. \label See Also::
  1825. \funref{+}, \funref{-}, \funref{1+}, \funref{1-}, \macref{setf}
  1826. \label Notes:\None.
  1827. %% Removed in response to Kawabe's comment #, first public review.
  1828. %
  1829. % The effect of \f{(incf \param{place} \param{delta})} is roughly equivalent to
  1830. %
  1831. % \code
  1832. % (setf \param{place} (+ \param{place} \param{delta}))
  1833. % \endcode
  1834. % except that the latter would evaluate any \term{subforms} of \param{place}
  1835. % twice, whereas \macref{incf} takes care to evaluate them only once.
  1836. \endcom
  1837. %%% ========== LCM
  1838. \begincom{lcm}\ftype{Function}
  1839. \label Syntax::
  1840. \DefunWithValues lcm {{\rest} integers} {least-common-multiple}
  1841. \label Arguments and Values::
  1842. \param{integer}---an \term{integer}.
  1843. \param{least-common-multiple}---a non-negative \term{integer}.
  1844. \label Description::
  1845. %% 12.4.0 24
  1846. \funref{lcm} returns the least common multiple of the \param{integers}.
  1847. \issue{LCM-NO-ARGUMENTS:1}
  1848. %% 12.4.0 27
  1849. %\funref{lcm} requires at least one argument.
  1850. If no \param{integer} is supplied, the \term{integer} \f{1} is returned.
  1851. \endissue{LCM-NO-ARGUMENTS:1}
  1852. If only one \param{integer} is supplied,
  1853. the absolute value of that \param{integer} is returned.
  1854. For two arguments that are not both zero,
  1855. \code
  1856. (lcm a b) \EQ (/ (abs (* a b)) (gcd a b))
  1857. \endcode
  1858. If one or both arguments are zero,
  1859. \code
  1860. (lcm a 0) \EQ (lcm 0 a) \EQ 0
  1861. \endcode
  1862. %% 12.4.0 25
  1863. For three or more arguments,
  1864. \code
  1865. (lcm a b c ... z) \EQ (lcm (lcm a b) c ... z)
  1866. \endcode
  1867. \label Examples::
  1868. %% 12.4.0 26
  1869. \code
  1870. (lcm 10) \EV 10
  1871. (lcm 25 30) \EV 150
  1872. (lcm -24 18 10) \EV 360
  1873. (lcm 14 35) \EV 70
  1874. (lcm 0 5) \EV 0
  1875. (lcm 1 2 3 4 5 6) \EV 60
  1876. \endcode
  1877. \label Side Effects:\None.
  1878. \label Affected By:\None.
  1879. \label Exceptional Situations::
  1880. Should signal \typeref{type-error} if any argument is not an \term{integer}.
  1881. \label See Also::
  1882. \funref{gcd}
  1883. \label Notes:\None.
  1884. \endcom
  1885. %%% ========== LOG
  1886. \begincom{log}\ftype{Function}
  1887. \label Syntax::
  1888. \DefunWithValues log {number {\opt} base} {logarithm}
  1889. \label Arguments and Values::
  1890. \param{number}---a non-zero \term{number}.
  1891. \param{base}---a \term{number}.
  1892. \param{logarithm}---a \term{number}.
  1893. \label Description::
  1894. %% 12.5.1 7
  1895. \funref{log} returns the logarithm of \param{number} in base \param{base}.
  1896. If \param{base} is not supplied its value is \i{e},
  1897. the base of the natural logarithms.
  1898. %% 12.5.1 8
  1899. \funref{log} may return a \term{complex} when given a
  1900. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1901. \term{real}
  1902. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  1903. negative \param{number}.
  1904. \code
  1905. (log -1.0) \EQ (complex 0.0 (float pi 0.0))
  1906. \endcode
  1907. If \param{base} is zero,
  1908. %%Removed as unnecessary per Barmar since \param{number} is described above as non-zero.
  1909. %and \param{number} is non-zero
  1910. \funref{log} returns zero.
  1911. The result of \f{(log 8 2)} may be either \f{3} or \f{3.0}, depending on the
  1912. implementation. An implementation can use floating-point calculations
  1913. even if an exact integer result is possible.
  1914. %% 12.5.3 7
  1915. The branch cut for the logarithm function of one argument (natural
  1916. logarithm) lies along the negative real axis, continuous with quadrant II.
  1917. The domain excludes the origin.
  1918. %%Per Barmar, this is removed since the above note from IEEE-ATAN-BRANCH-CUT
  1919. %%already says the same thing.
  1920. % When \param{number} is a \term{complex},
  1921. %
  1922. % %{\tt log \param{number}
  1923. % % \EQ\ (log $\vert$\param{number}$\vert$)+\i{i} \i{phase}(\param{number})\/}.
  1924. % \code
  1925. % (log \param{complex})
  1926. % \EQ (+ (log (abs \param{complex})) (* (phase \param{complex}) #c(0 1)))
  1927. % \endcode
  1928. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1929. The mathematical definition of a complex logarithm
  1930. is as follows, whether or not minus zero is supported by the
  1931. implementation:
  1932. \code
  1933. (log \i{x}) \EQ (complex (log (abs \i{x})) (phase \i{x}))
  1934. \endcode
  1935. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1936. Therefore the range of the one-argument logarithm function is that strip
  1937. of the complex plane containing numbers with imaginary parts between
  1938. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1939. $-\pi$ (exclusive) and~$\pi$ (inclusive) if minus zero is not supported,
  1940. or $-\pi$ (inclusive) and~$\pi$ (inclusive) if minus zero is supported.
  1941. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  1942. %% 12.5.3 8
  1943. The two-argument logarithm function is defined as
  1944. \code
  1945. (log \param{base} \param{number})
  1946. \EQ (/ (log \param{number}) (log \param{base}))
  1947. \endcode
  1948. This defines the \term{principal} \term{values} precisely.
  1949. The range of the two-argument logarithm function is the entire complex plane.
  1950. \label Examples::
  1951. \code
  1952. (log 100 10)
  1953. \EV 2.0
  1954. \EV 2
  1955. (log 100.0 10) \EV 2.0
  1956. (log #c(0 1) #c(0 -1))
  1957. \EV #C(-1.0 0.0)
  1958. \OV #C(-1 0)
  1959. (log 8.0 2) \EV 3.0
  1960. \endcode
  1961. \issue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1962. %!!! Figure out some way to notate these `precise approximations'
  1963. \code
  1964. (log #c(-16 16) #c(2 2)) \EV 3 or approximately #c(3.0 0.0)
  1965. or approximately 3.0 (unlikely)
  1966. \endcode
  1967. \endissue{COMPLEX-RATIONAL-RESULT:EXTEND}
  1968. \label Affected By::
  1969. The implementation.
  1970. \label Exceptional Situations:\None.
  1971. \label See Also::
  1972. \funref{exp},
  1973. \funref{expt},
  1974. {\secref\FloatSubstitutability}
  1975. \label Notes:\None.
  1976. \endcom
  1977. %%% ========== MOD
  1978. %%% ========== REM
  1979. \begincom{mod, rem}\ftype{Function}
  1980. \label Syntax::
  1981. \DefunWithValues mod {number divisor} {modulus}
  1982. \DefunWithValues rem {number divisor} {remainder}
  1983. \label Arguments and Values::
  1984. \param{number}---a \term{real}.
  1985. \param{divisor}---a \term{real}.
  1986. \param{modulus}, \param{remainder}---a \term{real}.
  1987. \label Description::
  1988. %% 12.6.0 22
  1989. \funref{mod} and \funref{rem} are generalizations of the modulus
  1990. and remainder functions respectively.
  1991. \funref{mod} performs the operation \funref{floor}
  1992. on \param{number} and \param{divisor}
  1993. and returns the remainder of the \funref{floor} operation.
  1994. \funref{rem} performs the operation \funref{truncate}
  1995. on \param{number} and \param{divisor}
  1996. and returns the remainder of the \funref{truncate} operation.
  1997. \funref{mod} and \funref{rem} are
  1998. %!!! Is this something from mathematics?? -kmp 24-Apr-91
  1999. the modulus and remainder functions
  2000. when \param{number} and \param{divisor} are \term{integers}.
  2001. \label Examples::
  2002. \code
  2003. (rem -1 5) \EV -1
  2004. (mod -1 5) \EV 4
  2005. (mod 13 4) \EV 1
  2006. (rem 13 4) \EV 1
  2007. (mod -13 4) \EV 3
  2008. (rem -13 4) \EV -1
  2009. (mod 13 -4) \EV -3
  2010. (rem 13 -4) \EV 1
  2011. (mod -13 -4) \EV -1
  2012. (rem -13 -4) \EV -1
  2013. (mod 13.4 1) \EV 0.4
  2014. (rem 13.4 1) \EV 0.4
  2015. (mod -13.4 1) \EV 0.6
  2016. (rem -13.4 1) \EV -0.4
  2017. \endcode
  2018. \label Side Effects:\None.
  2019. \label Affected By:\None.
  2020. \label Exceptional Situations:\None.
  2021. \label See Also::
  2022. \funref{floor}, \funref{truncate}
  2023. \label Notes::
  2024. The result of \funref{mod} is either zero or a
  2025. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2026. \term{real}
  2027. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2028. with the same sign as \param{divisor}.
  2029. \endcom
  2030. %%% ========== SIGNUM
  2031. \begincom{signum}\ftype{Function}
  2032. \label Syntax::
  2033. \DefunWithValues signum {number} {signed-prototype}
  2034. \label Arguments and Values::
  2035. \param{number}---a \term{number}.
  2036. \param{signed-prototype}---a \term{number}.
  2037. \label Description::
  2038. \funref{signum} determines a numerical value that indicates whether
  2039. \param{number} is negative, zero, or positive.
  2040. %% 12.5.2 12
  2041. For a \term{rational},
  2042. \funref{signum} returns one of \f{-1}, \f{0}, or \f{1}
  2043. according to whether \param{number} is negative, zero, or positive.
  2044. For a \term{float},
  2045. the result is a \term{float} of the same format
  2046. whose value is minus one, zero, or one.
  2047. For a \term{complex} number \f{z},
  2048. \f{(signum \i{z})} is a complex number of the same phase but with unit magnitude,
  2049. unless \f{z} is a complex zero, in which case the result is \f{z}.
  2050. %% 12.5.2 13
  2051. %%Rewritten to avoid a suggestion that there might be complex rationals. -kmp 2-Jan-91
  2052. % For non-\term{complex} \term{rationals}, \funref{signum}
  2053. % is a rational function, but it may be irrational for \term{complex} arguments.
  2054. For \term{rational} \term{arguments}, \funref{signum} is a rational function,
  2055. but it may be irrational for \term{complex} \term{arguments}.
  2056. If \param{number} is a \term{float}, the result is a \term{float}.
  2057. If \param{number} is a \term{rational}, the result is a \term{rational}.
  2058. If \param{number} is a \term{complex float}, the result is a \term{complex float}.
  2059. If \param{number} is a \term{complex rational}, the result is a \term{complex},
  2060. but it is \term{implementation-dependent} whether that result is a
  2061. \term{complex rational} or a \term{complex float}.
  2062. \label Examples::
  2063. \code
  2064. (signum 0) \EV 0
  2065. (signum 99) \EV 1
  2066. (signum 4/5) \EV 1
  2067. (signum -99/100) \EV -1
  2068. (signum 0.0) \EV 0.0
  2069. (signum #c(0 33)) \EV #C(0.0 1.0)
  2070. (signum #c(7.5 10.0)) \EV #C(0.6 0.8)
  2071. (signum #c(0.0 -14.7)) \EV #C(0.0 -1.0)
  2072. (eql (signum -0.0) -0.0) \EV \term{true}
  2073. \endcode
  2074. \label Side Effects:\None.
  2075. \label Affected By:\None.
  2076. \label Exceptional Situations:\None.
  2077. \label See Also::
  2078. {\secref\FloatSubstitutability}
  2079. \label Notes::
  2080. %% 12.5.2 11
  2081. \code
  2082. (signum x) \EQ (if (zerop x) x (/ x (abs x)))
  2083. \endcode
  2084. \endcom
  2085. %%% ========== SQRT
  2086. %%% ========== ISQRT
  2087. \begincom{sqrt, isqrt}\ftype{Function}
  2088. \label Syntax::
  2089. \DefunWithValues sqrt {number} {root}
  2090. \DefunWithValues isqrt {natural} {natural-root}
  2091. \label Arguments and Values::
  2092. \param{number}, \param{root}---a \term{number}.
  2093. \param{natural}, \param{natural-root}---a non-negative \term{integer}.
  2094. \label Description::
  2095. %% 12.5.1 1
  2096. \funref{sqrt} and \funref{isqrt} compute square roots.
  2097. %% 12.5.1 9
  2098. \funref{sqrt} returns the \term{principal} square root of \param{number}.
  2099. If the \param{number} is not a \term{complex} but is negative,
  2100. then the result is a \term{complex}.
  2101. %% 12.5.1 10
  2102. \funref{isqrt} returns the greatest \term{integer}
  2103. less than or equal to the exact positive square root of \param{natural}.
  2104. If \param{number} is a positive \term{rational},
  2105. it is \term{implementation-dependent}
  2106. whether \param{root} is a \term{rational} or a \term{float}.
  2107. If \param{number} is a negative \term{rational},
  2108. it is \term{implementation-dependent}
  2109. whether \param{root} is a \term{complex rational} or a \term{complex float}.
  2110. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2111. The mathematical definition of complex square root (whether or not
  2112. minus zero is supported) follows:
  2113. \f{(sqrt \i{x}) = (exp (/ (log \i{x}) 2))}
  2114. %% This is said in the definition of LOG. -kmp 19-Jan-92
  2115. % where
  2116. % \f{(log \i{x}) = (complex (log (abs \i{x})) (phase \i{x}))}.
  2117. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2118. The branch cut for square root lies along the negative real axis,
  2119. continuous with quadrant II.
  2120. The range consists of the right half-plane, including the non-negative
  2121. imaginary axis and excluding the negative imaginary axis.
  2122. \label Examples::
  2123. \code
  2124. (sqrt 9.0) \EV 3.0
  2125. (sqrt -9.0) \EV #C(0.0 3.0)
  2126. (isqrt 9) \EV 3
  2127. (sqrt 12) \EV 3.4641016
  2128. (isqrt 12) \EV 3
  2129. (isqrt 300) \EV 17
  2130. (isqrt 325) \EV 18
  2131. (sqrt 25)
  2132. \EV 5
  2133. \OV 5.0
  2134. (isqrt 25) \EV 5
  2135. (sqrt -1) \EV #C(0.0 1.0)
  2136. (sqrt #c(0 2)) \EV #C(1.0 1.0)
  2137. \endcode
  2138. \label Side Effects:\None.
  2139. \label Affected By:\None.
  2140. \label Exceptional Situations::
  2141. \Thefunction{sqrt} should signal \typeref{type-error} if its argument
  2142. is not a \term{number}.
  2143. \Thefunction{isqrt} should signal \typeref{type-error} if its argument
  2144. is not a non-negative \term{integer}.
  2145. The functions \funref{sqrt} and \funref{isqrt} might signal \typeref{arithmetic-error}.
  2146. \label See Also::
  2147. \funref{exp},
  2148. \funref{log},
  2149. {\secref\FloatSubstitutability}
  2150. \label Notes::
  2151. \code
  2152. (isqrt x) \EQ (values (floor (sqrt x)))
  2153. \endcode
  2154. but it is potentially more efficient.
  2155. \endcom
  2156. %-------------------- Random Numbers --------------------
  2157. %% 2.11.0 1
  2158. \begincom{random-state}\ftype{System Class}
  2159. \label Class Precedence List::
  2160. \typeref{random-state},
  2161. \typeref{t}
  2162. \label Description::
  2163. A \term{random state} \term{object} contains state
  2164. information used by the pseudo-random number generator.
  2165. %% 12.9.0 1
  2166. %The pseudo-random numbers
  2167. %in a random number series are \term{implementation-dependent},
  2168. %but the distribution of the numbers should
  2169. %machine-independent.
  2170. The nature of a \term{random state} \term{object} is \term{implementation-dependent}.
  2171. It can be printed out and successfully read back in by the same \term{implementation},
  2172. but might not function correctly as a \term{random state} in another \term{implementation}.
  2173. %%% 12.9.0 20
  2174. %
  2175. %A recommended way to implement \thetype{random-state}
  2176. %is effectively to use the machinery for \macref{defstruct}.
  2177. %% 12.9.0 18
  2178. \term{Implementations} are required to provide a read syntax for
  2179. \term{objects} \oftype{random-state}, but the specific nature of that syntax
  2180. is \term{implementation-dependent}.
  2181. \label See Also::
  2182. \varref{*random-state*},
  2183. \funref{random},
  2184. {\secref\PrintingRandomStates}
  2185. \endcom%{random-state}\ftype{System Class}
  2186. %%% ========== MAKE-RANDOM-STATE
  2187. \begincom{make-random-state}\ftype{Function}
  2188. \label Syntax::
  2189. \DefunWithValues make-random-state {{\opt} state} {new-state}
  2190. \label Arguments and Values::
  2191. % This isn't quite susceptible to being called a designator, I think.
  2192. % The uses are too idiosyncratic to the fact that this is a creation operator.
  2193. % If another function took the same arguments, it would use them differently,
  2194. % so the ideas don't generalize well. -kmp 12-Sep-91
  2195. \param{state}---a \term{random state}, or \nil, or \t.
  2196. \Default{\nil}
  2197. \param{new-state}---a \term{random state} \term{object}.
  2198. \label Description::
  2199. %% 12.9.0 12
  2200. Creates a \term{fresh} \term{object} \oftype{random-state} suitable
  2201. for use as \thevalueof{*random-state*}.
  2202. If \param{state} is a \term{random state} \term{object},
  2203. the \param{new-state} is a \term{copy}\meaning{5} of that \term{object}.
  2204. If \param{state} is \nil,
  2205. the \param{new-state} is a \term{copy}\meaning{5} of the \term{current random state}.
  2206. If \param{state} is \t,
  2207. the \param{new-state} is a \term{fresh} \term{random state} \term{object}
  2208. that has been randomly initialized by some means.
  2209. \label Examples::
  2210. \code
  2211. (let* ((rs1 (make-random-state nil))
  2212. (rs2 (make-random-state t))
  2213. (rs3 (make-random-state rs2))
  2214. (rs4 nil))
  2215. (list (loop for i from 1 to 10
  2216. collect (random 100)
  2217. when (= i 5)
  2218. do (setq rs4 (make-random-state)))
  2219. (loop for i from 1 to 10 collect (random 100 rs1))
  2220. (loop for i from 1 to 10 collect (random 100 rs2))
  2221. (loop for i from 1 to 10 collect (random 100 rs3))
  2222. (loop for i from 1 to 10 collect (random 100 rs4))))
  2223. \EV ((29 25 72 57 55 68 24 35 54 65)
  2224. (29 25 72 57 55 68 24 35 54 65)
  2225. (93 85 53 99 58 62 2 23 23 59)
  2226. (93 85 53 99 58 62 2 23 23 59)
  2227. (68 24 35 54 65 54 55 50 59 49))
  2228. \endcode
  2229. \label Side Effects:\None.
  2230. \label Affected By:\None.
  2231. \label Exceptional Situations::
  2232. \Shouldchecktype{state}{a \term{random state}, or \nil, or \t}
  2233. \label See Also::
  2234. \funref{random}, \varref{*random-state*}
  2235. \label Notes::
  2236. %% 12.9.0 19
  2237. One important use of \funref{make-random-state} is to allow the same
  2238. series of pseudo-random \term{numbers} to be generated many times within a
  2239. single program.
  2240. \endcom
  2241. %%% ========== RANDOM
  2242. \begincom{random}\ftype{Function}
  2243. \label Syntax::
  2244. \DefunWithValues random {limit {\opt} random-state} {random-number}
  2245. \label Arguments and Values::
  2246. \param{limit}---a positive \term{integer},
  2247. or a positive \term{float}.
  2248. %% 12.9.0 3
  2249. \param{random-state}---a \term{random state}.
  2250. \Default{the \term{current random state}}
  2251. \param{random-number}---a non-negative \term{number}
  2252. less than \param{limit}
  2253. and of the same \term{type} as \param{limit}.
  2254. \label Description::
  2255. %% 12.9.0 2
  2256. %% 12.9.0 5
  2257. %% 12.9.0 6
  2258. %% 12.9.0 7
  2259. %% 12.9.0 8
  2260. %% 12.9.0 9
  2261. %% 12.9.0 10
  2262. Returns a pseudo-random number that is a non-negative \term{number}
  2263. less than \param{limit} and of the same \term{type} as \param{limit}.
  2264. The \param{random-state}, which is modified by this function,
  2265. encodes the internal state maintained by the random number generator.
  2266. An approximately uniform choice distribution is used. If \param{limit}
  2267. is an \term{integer}, each of the possible results occurs with
  2268. (approximate) probability 1/\param{limit}.
  2269. \label Examples::
  2270. \code
  2271. (<= 0 (random 1000) 1000) \EV \term{true}
  2272. (let ((state1 (make-random-state))
  2273. (state2 (make-random-state)))
  2274. (= (random 1000 state1) (random 1000 state2))) \EV \term{true}
  2275. \endcode
  2276. \label Side Effects::
  2277. The \param{random-state} is modified.
  2278. \label Affected By:\None.
  2279. \label Exceptional Situations::
  2280. \Shouldchecktype{limit}{a positive \term{integer} or a positive \term{real}}
  2281. \label See Also::
  2282. \funref{make-random-state}, \varref{*random-state*}
  2283. \label Notes::
  2284. See \CLtL\ for information about generating random numbers.
  2285. \endcom
  2286. %%% ========== RANDOM-STATE-P
  2287. \begincom{random-state-p}\ftype{Function}
  2288. \label Syntax::
  2289. \DefunWithValues random-state-p {object} {generalized-boolean}
  2290. \label Arguments and Values::
  2291. \param{object}---an \term{object}.
  2292. \param{generalized-boolean}---a \term{generalized boolean}.
  2293. \label Description::
  2294. %% 12.9.0 21
  2295. \TypePredicate{object}{random-state}
  2296. \label Examples::
  2297. \code
  2298. (random-state-p *random-state*) \EV \term{true}
  2299. (random-state-p (make-random-state)) \EV \term{true}
  2300. (random-state-p 'test-function) \EV \term{false}
  2301. \endcode
  2302. \label Side Effects:\None.
  2303. \label Affected By:\None.
  2304. \label Exceptional Situations:\None!
  2305. \label See Also::
  2306. \funref{make-random-state}, \varref{*random-state*}
  2307. \label Notes::
  2308. \code
  2309. (random-state-p \param{object}) \EQ (typep \param{object} 'random-state)
  2310. \endcode
  2311. \endcom
  2312. %%% ========== *RANDOM-STATE*
  2313. \begincom{*random-state*}\ftype{Variable}
  2314. \label Value Type::
  2315. a \term{random state}.
  2316. \label Initial Value::
  2317. \term{implementation-dependent}.
  2318. \label Description::
  2319. %% 12.9.0 11
  2320. The \term{current random state}, which is used, for example,
  2321. by \thefunction{random} when a \term{random state} is not explicitly supplied.
  2322. \label Examples::
  2323. \code
  2324. (random-state-p *random-state*) \EV \term{true}
  2325. (setq snap-shot (make-random-state))
  2326. ;; The series from any given point is random,
  2327. ;; but if you backtrack to that point, you get the same series.
  2328. (list (loop for i from 1 to 10 collect (random))
  2329. (let ((*random-state* snap-shot))
  2330. (loop for i from 1 to 10 collect (random)))
  2331. (loop for i from 1 to 10 collect (random))
  2332. (let ((*random-state* snap-shot))
  2333. (loop for i from 1 to 10 collect (random))))
  2334. \EV ((19 16 44 19 96 15 76 96 13 61)
  2335. (19 16 44 19 96 15 76 96 13 61)
  2336. (16 67 0 43 70 79 58 5 63 50)
  2337. (16 67 0 43 70 79 58 5 63 50))
  2338. \endcode
  2339. \label Affected By::
  2340. The \term{implementation}.
  2341. \funref{random}.
  2342. \label See Also::
  2343. \funref{make-random-state},
  2344. \funref{random},
  2345. \typeref{random-state}
  2346. \label Notes::
  2347. \term{Binding} \varref{*random-state*} to a different
  2348. \term{random state} \term{object} correctly saves and
  2349. restores the old \term{random state} \term{object}.
  2350. \endcom
  2351. %-------------------- Numeric Types --------------------
  2352. %%% ========== NUMBERP
  2353. \begincom{numberp}\ftype{Function}
  2354. \label Syntax::
  2355. \DefunWithValues numberp {object} {generalized-boolean}
  2356. \label Arguments and Values::
  2357. \param{object}---an \term{object}.
  2358. \param{generalized-boolean}---a \term{generalized boolean}.
  2359. \label Description::
  2360. %% 6.2.2 11
  2361. \TypePredicate{object}{number}
  2362. \label Examples::
  2363. \code
  2364. (numberp 12) \EV \term{true}
  2365. (numberp (expt 2 130)) \EV \term{true}
  2366. (numberp #c(5/3 7.2)) \EV \term{true}
  2367. (numberp nil) \EV \term{false}
  2368. (numberp (cons 1 2)) \EV \term{false}
  2369. \endcode
  2370. \label Side Effects:\None.
  2371. \label Affected By:\None.
  2372. \label Exceptional Situations:\None!
  2373. \label See Also:\None.
  2374. \label Notes::
  2375. \code
  2376. (numberp \param{object}) \EQ (typep \param{object} 'number)
  2377. \endcode
  2378. \endcom
  2379. %-------------------- Complex --------------------
  2380. %%% ========== CIS
  2381. \begincom{cis}\ftype{Function}
  2382. \label Syntax::
  2383. \DefunWithValues cis {radians} {number}
  2384. \label Arguments and Values::
  2385. \param{radians}---a \term{real}.
  2386. \param{number}---a \term{complex}.
  2387. \label Description::
  2388. %% 12.5.2 15
  2389. \funref{cis} returns the value of~$\i{e}^{i\cdot\ \i{radians}}$,
  2390. which is a \term{complex} in which the
  2391. real part is equal to the cosine of \param{radians}, and the
  2392. imaginary part is equal to the sine of \param{radians}.
  2393. \label Examples::
  2394. \code
  2395. (cis 0) \EV #C(1.0 0.0)
  2396. \endcode
  2397. \label Side Effects:\None.
  2398. \label Affected By:\None.
  2399. \label Exceptional Situations:\None.
  2400. \label See Also::
  2401. {\secref\FloatSubstitutability}
  2402. \label Notes:\None.
  2403. %The result is a complex number whose
  2404. %phase is the equal to the argument (mod 2$\pi$)
  2405. %and whose magnitude is unity.
  2406. \endcom
  2407. %%% ========== COMPLEX
  2408. \begincom{complex}\ftype{Function}
  2409. \label Syntax::
  2410. \DefunWithValues complex {realpart {\opt} imagpart} {complex}
  2411. \label Arguments and Values::
  2412. \param{realpart}---a \term{real}.
  2413. \param{imagpart}---a \term{real}.
  2414. \param{complex}---a \term{rational} or a \term{complex}.
  2415. \label Description::
  2416. \funref{complex} returns a \term{number}
  2417. whose real part is \param{realpart}
  2418. and whose imaginary part is \param{imagpart}.
  2419. If \param{realpart} is a \term{rational}
  2420. and \param{imagpart} is the \term{rational} number zero,
  2421. the result of \funref{complex} is \param{realpart}, a \term{rational}.
  2422. Otherwise, the result is a \term{complex}.
  2423. %% 12.6.0 38
  2424. If either \param{realpart} or \param{imagpart} is a \term{float},
  2425. the non-\term{float} is converted to a \term{float}
  2426. before the \term{complex} is created.
  2427. If \param{imagpart} is not supplied, the imaginary part is a
  2428. zero of the same \term{type} as \param{realpart}; \ie
  2429. {\tt (coerce 0 (type-of \param{realpart}))} is
  2430. effectively used.
  2431. \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  2432. Type upgrading implies a movement upwards in the type
  2433. hierarchy lattice.
  2434. %!!! Barmar asks: ``What type specifier are you talking about?''
  2435. In the case of \term{complexes}, the \param{type-specifier}
  2436. \reviewer{Barmar: What type specifier?}
  2437. must be a subtype of
  2438. {\tt (upgraded-complex-part-type \param{type-specifier})}.
  2439. If \param{type-specifier1} is a subtype of \param{type-specifier2}, then
  2440. {\tt (upgraded-complex-element-type '\param{type-specifier1})}
  2441. must also be a subtype of
  2442. {\tt (upgraded-complex-element-type '\param{type-specifier2})}.
  2443. Two disjoint types can be upgraded into
  2444. the same thing.
  2445. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  2446. \label Examples::
  2447. \code
  2448. (complex 0) \EV 0
  2449. (complex 0.0) \EV #C(0.0 0.0)
  2450. (complex 1 1/2) \EV #C(1 1/2)
  2451. (complex 1 .99) \EV #C(1.0 0.99)
  2452. (complex 3/2 0.0) \EV #C(1.5 0.0)
  2453. \endcode
  2454. \label Side Effects:\None.
  2455. \label Affected By:\None.
  2456. \label Exceptional Situations:\None.
  2457. \label See Also::
  2458. \funref{realpart},
  2459. \funref{imagpart},
  2460. %% Added per Boyer/Kaufmann/Moore #15 (by X3J13 vote at May 4-5, 1994 meeting)
  2461. %% -kmp 9-May-94
  2462. {\secref\SharpsignC}
  2463. \label Notes:\None.
  2464. %% Removed per Boyer/Kaufmann/Moore #15 (by X3J13 vote at May 4-5, 1994 meeting)
  2465. %% -kmp 9-May-94
  2466. % \code
  2467. % #c(a b) \EQ #.(complex a b)
  2468. % \endcode
  2469. \endcom
  2470. %%% ========== COMPLEXP
  2471. \begincom{complexp}\ftype{Function}
  2472. \label Syntax::
  2473. \DefunWithValues complexp {object} {generalized-boolean}
  2474. \label Arguments and Values::
  2475. \param{object}---an \term{object}.
  2476. \param{generalized-boolean}---a \term{generalized boolean}.
  2477. \label Description::
  2478. %% 6.2.2 16
  2479. \TypePredicate{object}{complex}
  2480. \label Examples::
  2481. \code
  2482. (complexp 1.2d2) \EV \term{false}
  2483. (complexp #c(5/3 7.2)) \EV \term{true}
  2484. \endcode
  2485. \label Side Effects:\None.
  2486. \label Affected By:\None.
  2487. \label Exceptional Situations:\None!
  2488. \label See Also::
  2489. \funref{complex} (\term{function} and \term{type}), \funref{typep}
  2490. \label Notes::
  2491. \code
  2492. (complexp \param{object}) \EQ (typep \param{object} 'complex)
  2493. \endcode
  2494. \endcom
  2495. %%% ========== CONJUGATE
  2496. \begincom{conjugate}\ftype{Function}
  2497. \label Syntax::
  2498. \DefunWithValues conjugate {number} {conjugate}
  2499. \label Arguments and Values::
  2500. \param{number}---a \term{number}.
  2501. \param{conjugate}---a \term{number}.
  2502. \label Description::
  2503. %% 12.4.0 21
  2504. Returns the complex conjugate of \param{number}.
  2505. The conjugate of a
  2506. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2507. \term{real}
  2508. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2509. number is itself.
  2510. \label Examples::
  2511. \code
  2512. (conjugate #c(0 -1)) \EV #C(0 1)
  2513. (conjugate #c(1 1)) \EV #C(1 -1)
  2514. (conjugate 1.5) \EV 1.5
  2515. (conjugate #C(3/5 4/5)) \EV #C(3/5 -4/5)
  2516. (conjugate #C(0.0D0 -1.0D0)) \EV #C(0.0D0 1.0D0)
  2517. (conjugate 3.7) \EV 3.7
  2518. \endcode
  2519. \label Side Effects:\None.
  2520. \label Affected By:\None.
  2521. \label Exceptional Situations:\None.
  2522. \label See Also:\None.
  2523. \label Notes::
  2524. For a \term{complex} number \f{z},
  2525. \code
  2526. (conjugate z) \EQ (complex (realpart z) (- (imagpart z)))
  2527. \endcode
  2528. \endcom
  2529. %%% ========== PHASE
  2530. \begincom{phase}\ftype{Function}
  2531. \label Syntax::
  2532. \DefunWithValues phase {number} {phase}
  2533. \label Arguments and Values::
  2534. \param{number}---a \term{number}.
  2535. \param{phase}---a \term{number}.
  2536. \label Description::
  2537. %% 12.5.2 8
  2538. %% 12.5.2 9
  2539. \funref{phase}
  2540. returns the phase
  2541. of \param{number} (the angle part of its polar representation)
  2542. in radians, in the range
  2543. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2544. $-\pi$ (exclusive) if minus zero is not supported, or
  2545. $-\pi$ (inclusive) if minus zero is supported,
  2546. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2547. to $\pi$ (inclusive). The phase of a positive
  2548. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2549. \term{real}
  2550. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2551. number
  2552. is zero; that of a negative
  2553. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2554. \term{real}
  2555. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2556. number is $\pi$.
  2557. The phase of zero is defined to be zero.
  2558. %% 12.5.2 10
  2559. If \param{number} is a \term{complex float},
  2560. the result is a \term{float} of the same \term{type}
  2561. as the components of \param{number}.
  2562. If \param{number} is a \term{float}, the result is a
  2563. \term{float} of the same \term{type}.
  2564. If \param{number} is a \term{rational} or a \term{complex rational},
  2565. the result is a \term{single float}.
  2566. %% 12.5.3 6
  2567. The branch cut for \funref{phase} lies along the negative real
  2568. axis, continuous with quadrant II. The range consists of that portion of
  2569. the real axis between $-\pi$ (exclusive) and~$\pi$ (inclusive).
  2570. \issue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2571. The mathematical definition of \funref{phase} is as follows:
  2572. \f{(phase \i{x}) = (atan (imagpart \i{x}) (realpart \i{x}))}
  2573. \endissue{IEEE-ATAN-BRANCH-CUT:SPLIT}
  2574. \label Examples::
  2575. \code
  2576. (phase 1) \EV 0.0s0
  2577. (phase 0) \EV 0.0s0
  2578. (phase (cis 30)) \EV -1.4159266
  2579. (phase #c(0 1)) \EV 1.5707964
  2580. \endcode
  2581. \label Side Effects:\None.
  2582. \label Affected By:\None.
  2583. \label Exceptional Situations::
  2584. Should signal \typeref{type-error} if its argument is not a \term{number}.
  2585. Might signal \typeref{arithmetic-error}.
  2586. \label See Also::
  2587. {\secref\FloatSubstitutability}
  2588. \label Notes:\None.
  2589. \endcom
  2590. %%% ========== REALPART
  2591. %%% ========== IMAGPART
  2592. \begincom{realpart, imagpart}\ftype{Function}
  2593. \label Syntax::
  2594. \DefunWithValues realpart {number} {real}
  2595. \DefunWithValues imagpart {number} {real}
  2596. \label Arguments and Values::
  2597. \param{number}---a \term{number}.
  2598. \param{real}---a \term{real}.
  2599. \label Description::
  2600. \funref{realpart} and \funref{imagpart} return the real and
  2601. imaginary parts of \param{number} respectively.
  2602. %% 12.6.0 39
  2603. If \param{number} is
  2604. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2605. \term{real},
  2606. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2607. then \funref{realpart} returns \param{number} and \funref{imagpart}
  2608. returns \f{(* 0 \param{number})}, which has the effect that the
  2609. imaginary part of a \term{rational} is \f{0} and that of
  2610. a \term{float} is a floating-point zero of the same format.
  2611. \label Examples::
  2612. \code
  2613. (realpart #c(23 41)) \EV 23
  2614. (imagpart #c(23 41.0)) \EV 41.0
  2615. (realpart #c(23 41.0)) \EV 23.0
  2616. (imagpart 23.0) \EV 0.0
  2617. \endcode
  2618. \label Side Effects:\None.
  2619. \label Affected By:\None.
  2620. \label Exceptional Situations::
  2621. \Shouldchecktype{number}{a \term{number}}
  2622. \label See Also::
  2623. \funref{complex}
  2624. \label Notes:\None.
  2625. \endcom
  2626. %%% ========== UPGRADED-COMPLEX-PART-TYPE
  2627. \begincom{upgraded-complex-part-type}\ftype{Function}
  2628. \issue{SUBTYPEP-ENVIRONMENT:ADD-ARG}
  2629. \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  2630. \label Syntax::
  2631. \DefunWithValues upgraded-complex-part-type
  2632. {typespec {\opt} environment}
  2633. {upgraded-typespec}
  2634. \label Arguments and Values::
  2635. \param{typespec}---a \term{type specifier}.
  2636. \param{environment}---an \term{environment} \term{object}.
  2637. \Default{\nil, denoting the \term{null lexical environment}
  2638. and the and current \term{global environment}}
  2639. %!!! Need to say what happens with the environment.
  2640. \param{upgraded-typespec}---a \term{type specifier}.
  2641. \label Description::
  2642. \funref{upgraded-complex-part-type} returns the part type of the
  2643. most specialized \term{complex} number representation that can
  2644. hold parts of \term{type} \term{typespec}.
  2645. %Added by KMP in response to a Barmar comment. -kmp 29-Jul-91
  2646. The \param{typespec} is a \term{subtype} of
  2647. (and possibly \term{type equivalent} to)
  2648. the \param{upgraded-typespec}.
  2649. The purpose of \funref{upgraded-complex-part-type}
  2650. is to reveal how an implementation does its \term{upgrading}.
  2651. \label Examples:\None.
  2652. \label Side Effects:\None.
  2653. \label Affected By:\None.
  2654. \label Exceptional Situations:\None.
  2655. \label See Also::
  2656. \funref{complex} (\term{function} and \term{type})
  2657. \label Notes::
  2658. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING}
  2659. \endissue{SUBTYPEP-ENVIRONMENT:ADD-ARG}
  2660. \endcom
  2661. %-------------------- Real --------------------
  2662. %%% ========== REALP
  2663. \begincom{realp}\ftype{Function}
  2664. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2665. \label Syntax::
  2666. \DefunWithValues realp {object} {generalized-boolean}
  2667. \label Arguments and Values::
  2668. \param{object}---an \term{object}.
  2669. \param{generalized-boolean}---a \term{generalized boolean}.
  2670. \label Description::
  2671. %% 6.2.2 11
  2672. \TypePredicate{object}{real}
  2673. \label Examples::
  2674. \code
  2675. (realp 12) \EV \term{true}
  2676. (realp #c(5/3 7.2)) \EV \term{false}
  2677. (realp nil) \EV \term{false}
  2678. (realp (cons 1 2)) \EV \term{false}
  2679. \endcode
  2680. \label Side Effects:\None.
  2681. \label Affected By:\None.
  2682. \label Exceptional Situations:\None!
  2683. \label See Also:\None.
  2684. \label Notes::
  2685. \code
  2686. (realp \param{object}) \EQ (typep \param{object} 'real)
  2687. \endcode
  2688. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2689. \endcom
  2690. %-------------------- Rational --------------------
  2691. %%% ========== NUMERATOR
  2692. %%% ========== DENOMINATOR
  2693. \begincom{numerator, denominator}\ftype{Function}
  2694. \label Syntax::
  2695. \DefunWithValues numerator {rational} {numerator}
  2696. \DefunWithValues denominator {rational} {denominator}
  2697. \label Arguments and Values::
  2698. \param{rational}---a \term{rational}.
  2699. \param{numerator}---an \term{integer}.
  2700. \param{denominator}---a positive \term{integer}.
  2701. \label Description::
  2702. %% 12.6.0 8
  2703. \funref{numerator} and \funref{denominator} reduce \param{rational}
  2704. to canonical form and compute the numerator or denominator of that number.
  2705. \funref{numerator} and \funref{denominator} return the numerator
  2706. or denominator of the canonical form of \param{rational}.
  2707. If \param{rational} is an \term{integer},
  2708. \funref{numerator} returns \param{rational}
  2709. and \funref{denominator} returns 1.
  2710. \label Examples::
  2711. \code
  2712. (numerator 1/2) \EV 1
  2713. (denominator 12/36) \EV 3
  2714. (numerator -1) \EV -1
  2715. (denominator (/ -33)) \EV 33
  2716. (numerator (/ 8 -6)) \EV -4
  2717. (denominator (/ 8 -6)) \EV 3
  2718. \endcode
  2719. \label Side Effects:\None.
  2720. \label Affected By:\None.
  2721. \label Exceptional Situations:\None.
  2722. \label See Also::
  2723. \funref{/}
  2724. \label Notes::
  2725. \code
  2726. (gcd (numerator x) (denominator x)) \EV 1
  2727. \endcode
  2728. \endcom
  2729. %%% ========== RATIONAL
  2730. %%% ========== RATIONALIZE
  2731. \begincom{rational, rationalize}\ftype{Function}
  2732. \label Syntax::
  2733. \DefunWithValues rational {number} {rational}
  2734. \DefunWithValues rationalize {number} {rational}
  2735. \label Arguments and Values::
  2736. \param{number}---a \term{real}.
  2737. \param{rational}---a \term{rational}.
  2738. \label Description::
  2739. %% 12.6.0 5
  2740. \funref{rational} and \funref{rationalize} convert
  2741. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2742. \term{reals}
  2743. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  2744. to \term{rationals}.
  2745. If \param{number} is already \term{rational}, it is returned.
  2746. If \param{number} is a \term{float},
  2747. \funref{rational} returns a \term{rational}
  2748. that is mathematically equal in value to the \term{float}.
  2749. \funref{rationalize} returns a \term{rational} that
  2750. approximates the \term{float} to the accuracy of
  2751. the underlying floating-point representation.
  2752. \funref{rational} assumes that the \term{float} is completely accurate.
  2753. %% 12.6.0 6
  2754. \funref{rationalize} assumes that the
  2755. \term{float} is accurate only to the precision of the
  2756. floating-point representation.
  2757. \label Examples::
  2758. \code
  2759. (rational 0) \EV 0
  2760. (rationalize -11/100) \EV -11/100
  2761. (rational .1) \EV 13421773/134217728 ;implementation-dependent
  2762. (rationalize .1) \EV 1/10
  2763. \endcode
  2764. \label Side Effects:\None.
  2765. \label Affected By::
  2766. The \term{implementation}.
  2767. \label Exceptional Situations::
  2768. \Shouldchecktype{number}{a \term{real}}
  2769. Might signal \typeref{arithmetic-error}.
  2770. \label See Also:\None.
  2771. \label Notes::
  2772. %% 12.6.0 7
  2773. It is always the case that
  2774. \code
  2775. (float (rational x) x) \EQ x
  2776. \endcode
  2777. and
  2778. \code
  2779. (float (rationalize x) x) \EQ x
  2780. \endcode
  2781. That is, rationalizing a \term{float} by either method
  2782. and then converting it back
  2783. to a \term{float}
  2784. of the same format produces the original \param{number}.
  2785. \endcom
  2786. %%% ========== RATIONALP
  2787. \begincom{rationalp}\ftype{Function}
  2788. \label Syntax::
  2789. \DefunWithValues rationalp {object} {generalized-boolean}
  2790. \label Arguments and Values::
  2791. \param{object}---an \term{object}.
  2792. \param{generalized-boolean}---a \term{generalized boolean}.
  2793. \label Description::
  2794. %% 6.2.2 14
  2795. \TypePredicate{object}{rational}
  2796. \label Examples::
  2797. \code
  2798. (rationalp 12) \EV \term{true}
  2799. (rationalp 6/5) \EV \term{true}
  2800. (rationalp 1.212) \EV \term{false}
  2801. \endcode
  2802. \label Side Effects:\None.
  2803. \label Affected By:\None.
  2804. \label Exceptional Situations:\None!
  2805. \label See Also::
  2806. \funref{rational}
  2807. \label Notes::
  2808. \code
  2809. (rationalp \param{object}) \EQ (typep \param{object} 'rational)
  2810. \endcode
  2811. \endcom
  2812. %-------------------- Integer --------------------
  2813. %%% ========== ASH
  2814. \begincom{ash}\ftype{Function}
  2815. \label Syntax::
  2816. \DefunWithValues ash {integer count} {shifted-integer}
  2817. \label Arguments and Values::
  2818. \param{integer}---an \term{integer}.
  2819. \param{count}---an \term{integer}.
  2820. \param{shifted-integer}---an \term{integer}.
  2821. \label Description::
  2822. %% 12.7.0 18
  2823. \funref{ash} performs the arithmetic shift operation on the binary
  2824. representation of \param{integer}, which is treated as if it were binary.
  2825. \funref{ash} shifts \param{integer} arithmetically left by \param{count} bit
  2826. positions if \param{count} is positive,
  2827. or right \param{count} bit positions if \param{count} is negative.
  2828. The shifted value of the same sign
  2829. as \param{integer} is returned.
  2830. Mathematically speaking, \funref{ash} performs the computation
  2831. \f{floor}(\param{integer}\centerdot $2^\param{count}$).
  2832. %% 12.7.0 20
  2833. Logically, \funref{ash}
  2834. moves all of the bits in \param{integer} to the left,
  2835. adding zero-bits at the right, or moves them to the right,
  2836. discarding bits.
  2837. \funref{ash} is defined to behave as if \param{integer} were
  2838. represented in two's complement form, regardless of
  2839. how \term{integers} are represented internally.
  2840. \label Examples::
  2841. \code
  2842. (ash 16 1) \EV 32
  2843. (ash 16 0) \EV 16
  2844. (ash 16 -1) \EV 8
  2845. (ash -100000000000000000000000000000000 -100) \EV -79
  2846. \endcode
  2847. \label Affected By:\None.
  2848. \label Exceptional Situations::
  2849. \Shouldchecktype{integer}{an \term{integer}}
  2850. \Shouldchecktype{count}{an \term{integer}}
  2851. Might signal \typeref{arithmetic-error}.
  2852. \label See Also:\None.
  2853. \label Notes::
  2854. %% 12.7.0 19
  2855. \code
  2856. (logbitp \param{j} (ash \param{n} \param{k}))
  2857. \EQ (and (>= \param{j} \param{k}) (logbitp (- \param{j} \param{k}) \param{n}))
  2858. \endcode
  2859. \endcom
  2860. %%% ========== INTEGER-LENGTH
  2861. \begincom{integer-length}\ftype{Function}
  2862. \label Syntax::
  2863. \DefunWithValues integer-length {integer} {number-of-bits}
  2864. \label Arguments and Values::
  2865. \param{integer}---an \term{integer}.
  2866. \param{number-of-bits}---a non-negative \term{integer}.
  2867. \label Description::
  2868. %% 12.7.0 22
  2869. Returns the number of bits needed to represent \param{integer}
  2870. in binary two's-complement format.
  2871. \label Examples::
  2872. %% 12.7.0 23
  2873. \code
  2874. (integer-length 0) \EV 0
  2875. (integer-length 1) \EV 1
  2876. (integer-length 3) \EV 2
  2877. (integer-length 4) \EV 3
  2878. (integer-length 7) \EV 3
  2879. (integer-length -1) \EV 0
  2880. (integer-length -4) \EV 2
  2881. (integer-length -7) \EV 3
  2882. (integer-length -8) \EV 3
  2883. (integer-length (expt 2 9)) \EV 10
  2884. (integer-length (1- (expt 2 9))) \EV 9
  2885. (integer-length (- (expt 2 9))) \EV 9
  2886. (integer-length (- (1+ (expt 2 9)))) \EV 10
  2887. \endcode
  2888. \label Side Effects:\None.
  2889. \label Affected By:\None.
  2890. \label Exceptional Situations::
  2891. \Shouldchecktype{integer}{an \term{integer}}
  2892. \label See Also:\None.
  2893. \label Notes::
  2894. This function could have been defined by:
  2895. \code
  2896. (defun integer-length (integer)
  2897. (ceiling (log (if (minusp integer)
  2898. (- integer)
  2899. (1+ integer))
  2900. 2)))
  2901. \endcode
  2902. If \param{integer} is non-negative, then its value can be represented
  2903. in unsigned binary form in a field whose width in bits is
  2904. no smaller than {\tt (integer-length \param{integer})}.
  2905. Regardless of the sign of \param{integer}, its value can be
  2906. represented in signed binary two's-complement form in a field
  2907. whose width in bits is no smaller than {\tt (+ (integer-length \param{integer}) 1)}.
  2908. \endcom
  2909. %%% ========== INTEGERP
  2910. \begincom{integerp}\ftype{Function}
  2911. \label Syntax::
  2912. \DefunWithValues integerp {object} {generalized-boolean}
  2913. \label Arguments and Values::
  2914. \param{object}---an \term{object}.
  2915. \param{generalized-boolean}---a \term{generalized boolean}.
  2916. \label Description::
  2917. %% 6.2.2 12
  2918. \TypePredicate{object}{integer}
  2919. \label Examples::
  2920. \code
  2921. (integerp 1) \EV \term{true}
  2922. (integerp (expt 2 130)) \EV \term{true}
  2923. (integerp 6/5) \EV \term{false}
  2924. (integerp nil) \EV \term{false}
  2925. \endcode
  2926. \label Side Effects:\None.
  2927. \label Affected By:\None.
  2928. \label Exceptional Situations:\None!
  2929. \label See Also:\None.
  2930. \label Notes::
  2931. \code
  2932. (integerp \param{object}) \EQ (typep \param{object} 'integer)
  2933. \endcode
  2934. \endcom
  2935. %%% ========== PARSE-INTEGER
  2936. \begincom{parse-integer}\ftype{Function}
  2937. \label Syntax::
  2938. \DefunWithValues {parse-integer} {string {\key} start end radix junk-allowed} {integer, pos}
  2939. \label Arguments and Values::
  2940. \param{string}---a \term{string}.
  2941. \issue{SUBSEQ-OUT-OF-BOUNDS}
  2942. \issue{RANGE-OF-START-AND-END-PARAMETERS:INTEGER-AND-INTEGER-NIL}
  2943. \param{start}, \param{end}---\term{bounding index designators} of \param{string}.
  2944. \Defaults{\param{start} and \param{end}}{\f{0} and \nil}
  2945. \endissue{RANGE-OF-START-AND-END-PARAMETERS:INTEGER-AND-INTEGER-NIL}
  2946. \endissue{SUBSEQ-OUT-OF-BOUNDS}
  2947. \param{radix}---a \term{radix}.
  2948. \Default{\f{10}}
  2949. \param{junk-allowed}---a \term{generalized boolean}.
  2950. \Default{\term{false}}
  2951. \param{integer}---an \term{integer} or \term{false}.
  2952. \param{pos}---a \term{bounding index} of \param{string}.
  2953. \label Description::
  2954. %% 22.2.1 45
  2955. \funref{parse-integer} parses an \term{integer} in the specified \param{radix}
  2956. from the substring of \param{string} delimited by \param{start} and \param{end}.
  2957. %% 22.2.1 49
  2958. \funref{parse-integer} expects an optional sign (\f{+} or \f{-}) followed by
  2959. a a non-empty sequence of digits to be interpreted in the specified \param{radix}.
  2960. Optional leading and trailing \term{whitespace}\meaning{1} is ignored.
  2961. \funref{parse-integer} does not recognize the syntactic radix-specifier
  2962. prefixes \f{\#O}, \f{\#B}, \f{\#X}, and \f{\#\i{n}R},
  2963. nor does it recognize a trailing decimal point.
  2964. If \param{junk-allowed} is \term{false}, an error \oftype{parse-error} is
  2965. signaled if substring does not consist entirely of the representation of a
  2966. signed \term{integer}, possibly surrounded on either side by \term{whitespace}\meaning{1}
  2967. \term{characters}.
  2968. %% 22.2.1 46
  2969. The first \term{value} returned is either
  2970. the \term{integer} that was parsed,
  2971. or else \nil\ if no syntactically correct \term{integer}
  2972. was seen but \param{junk-allowed} was \term{true}.
  2973. %% 22.2.1 48
  2974. The second \term{value} is either
  2975. the index into the \term{string} of the delimiter that terminated the parse,
  2976. or the upper \term{bounding index} of the substring if the parse terminated at
  2977. the end of the substring (as is always the case if \param{junk-allowed}
  2978. is \term{false}).
  2979. % KMP:
  2980. % This is actually somewhat ambiguous.
  2981. % A. (parse-integer "3 5" :junk-allowed nil :end 2) \EV 3,1 or 3,2 ??
  2982. % B. (parse-integer "3 5" :junk-allowed t :end 2) \EV 3,1 or 3,2 ??
  2983. % C. (parse-integer "3 a" :junk-allowed t) \EV 3,1 or 3,2 ??
  2984. % Mail sent to Quinquevirate asking if anyone had any thoughts on this.
  2985. \label Examples::
  2986. \code
  2987. (parse-integer "123") \EV 123, 3
  2988. (parse-integer "123" :start 1 :radix 5) \EV 13, 3
  2989. (parse-integer "no-integer" :junk-allowed t) \EV NIL, 0
  2990. \endcode
  2991. \label Side Effects:\None.
  2992. \label Affected By:\None.
  2993. \label Exceptional Situations::
  2994. If \param{junk-allowed} is \term{false},
  2995. an error is signaled if substring does not consist entirely of
  2996. the representation of an \term{integer},
  2997. possibly surrounded on either side by
  2998. \term{whitespace}\meaning{1} characters.
  2999. %% Per X3J13. -kmp 05-Oct-93
  3000. \label See Also:\None.
  3001. \label Notes:\None.
  3002. \endcom
  3003. %-------------------- Integer Bits --------------------
  3004. %%% ========== BOOLE
  3005. \begincom{boole}\ftype{Function}
  3006. \label Syntax::
  3007. \DefunWithValues boole {op integer-1 integer-2} {result-integer}
  3008. \label Arguments and Values::
  3009. \param{Op}---a \term{bit-wise logical operation specifier}.
  3010. \param{integer-1}---an \term{integer}.
  3011. \param{integer-2}---an \term{integer}.
  3012. \param{result-integer}---an \term{integer}.
  3013. \label Description::
  3014. %% 12.7.0 12
  3015. \funref{boole} performs bit-wise logical operations on
  3016. \param{integer-1} and \param{integer-2}, which are treated as if
  3017. they were binary and in two's complement representation.
  3018. The operation to be performed and the return value are determined by
  3019. \param{op}.
  3020. \funref{boole} returns the values
  3021. specified for any \param{op} in \thenextfigure.
  3022. {
  3023. \def\zz{0\ \ \ 0}
  3024. \def\ww{1\ \ \ 1}
  3025. \def\zw{0\ \ \ 1}
  3026. \def\wz{1\ \ \ 0}
  3027. \def\sp{\ \ \ }
  3028. \tablefigtwo{Bit-Wise Logical Operations}{Op}{Result}{
  3029. \varref{boole-1} & \param{integer-1} \cr
  3030. \varref{boole-2} & \param{integer-2} \cr
  3031. \varref{boole-andc1} & and complement of \param{integer-1} with \param{integer-2} \cr
  3032. \varref{boole-andc2} & and \param{integer-1} with complement of \param{integer-2} \cr
  3033. \varref{boole-and} & and \cr
  3034. \varref{boole-c1} & complement of \param{integer-1} \cr
  3035. \varref{boole-c2} & complement of \param{integer-2} \cr
  3036. \varref{boole-clr} & always 0 (all zero bits) \cr
  3037. \varref{boole-eqv} & equivalence (exclusive nor) \cr
  3038. \varref{boole-ior} & inclusive or \cr
  3039. \varref{boole-nand} & not-and \cr
  3040. \varref{boole-nor} & not-or \cr
  3041. \varref{boole-orc1} & or complement of \param{integer-1} with \param{integer-2} \cr
  3042. \varref{boole-orc2} & or \param{integer-1} with complement of \param{integer-2} \cr
  3043. \varref{boole-set} & always -1 (all one bits) \cr
  3044. \varref{boole-xor} & exclusive or \cr
  3045. }
  3046. }
  3047. \label Examples::
  3048. \code
  3049. (boole boole-ior 1 16) \EV 17
  3050. (boole boole-and -2 5) \EV 4
  3051. (boole boole-eqv 17 15) \EV -31
  3052. ;;; These examples illustrate the result of applying BOOLE and each
  3053. ;;; of the possible values of OP to each possible combination of bits.
  3054. (progn
  3055. (format t "~&Results of (BOOLE <op> #b0011 #b0101) ...~
  3056. ~%---Op-------Decimal-----Binary----Bits---~%")
  3057. (dolist (symbol '(boole-1 boole-2 boole-and boole-andc1
  3058. boole-andc2 boole-c1 boole-c2 boole-clr
  3059. boole-eqv boole-ior boole-nand boole-nor
  3060. boole-orc1 boole-orc2 boole-set boole-xor))
  3061. (let ((result (boole (symbol-value symbol) #b0011 #b0101)))
  3062. (format t "~& ~A~13T~3,' D~23T~:*~5,' B~31T ...~4,'0B~%"
  3063. symbol result (logand result #b1111)))))
  3064. \OUT Results of (BOOLE <op> #b0011 #b0101) ...
  3065. \OUT ---Op-------Decimal-----Binary----Bits---
  3066. \OUT BOOLE-1 3 11 ...0011
  3067. \OUT BOOLE-2 5 101 ...0101
  3068. \OUT BOOLE-AND 1 1 ...0001
  3069. \OUT BOOLE-ANDC1 4 100 ...0100
  3070. \OUT BOOLE-ANDC2 2 10 ...0010
  3071. \OUT BOOLE-C1 -4 -100 ...1100
  3072. \OUT BOOLE-C2 -6 -110 ...1010
  3073. \OUT BOOLE-CLR 0 0 ...0000
  3074. \OUT BOOLE-EQV -7 -111 ...1001
  3075. \OUT BOOLE-IOR 7 111 ...0111
  3076. \OUT BOOLE-NAND -2 -10 ...1110
  3077. \OUT BOOLE-NOR -8 -1000 ...1000
  3078. \OUT BOOLE-ORC1 -3 -11 ...1101
  3079. \OUT BOOLE-ORC2 -5 -101 ...1011
  3080. \OUT BOOLE-SET -1 -1 ...1111
  3081. \OUT BOOLE-XOR 6 110 ...0110
  3082. \EV NIL
  3083. \endcode
  3084. %\filbreak
  3085. \label Affected By:\None.
  3086. \label Exceptional Situations::
  3087. Should signal \typeref{type-error} if its first argument is not a
  3088. \term{bit-wise logical operation specifier} or if any subsequent argument is not
  3089. an \term{integer}.
  3090. \label See Also::
  3091. \funref{logand}
  3092. \label Notes::
  3093. %% 12.7.0 14
  3094. In general,
  3095. \code
  3096. (boole boole-and x y) \EQ (logand x y)
  3097. \endcode
  3098. %% The following example contributed by Dan Hoey (hoey@AIC.NRL.Navy.Mil)
  3099. \term{Programmers} who would prefer to use numeric indices rather than
  3100. \term{bit-wise logical operation specifiers} can get an equivalent effect
  3101. by a technique such as the following:
  3102. \code
  3103. ;; The order of the values in this `table' are such that
  3104. ;; (logand (boole (elt boole-n-vector n) #b0101 #b0011) #b1111) => n
  3105. (defconstant boole-n-vector
  3106. (vector boole-clr boole-and boole-andc1 boole-2
  3107. boole-andc2 boole-1 boole-xor boole-ior
  3108. boole-nor boole-eqv boole-c1 boole-orc1
  3109. boole-c2 boole-orc2 boole-nand boole-set))
  3110. \EV BOOLE-N-VECTOR
  3111. (proclaim '(inline boole-n))
  3112. \EV \term{implementation-dependent}
  3113. (defun boole-n (n integer &rest more-integers)
  3114. (apply #'boole (elt boole-n-vector n) integer more-integers))
  3115. \EV BOOLE-N
  3116. (boole-n #b0111 5 3) \EV 7
  3117. (boole-n #b0001 5 3) \EV 1
  3118. (boole-n #b1101 5 3) \EV -3
  3119. (loop for n from #b0000 to #b1111 collect (boole-n n 5 3))
  3120. \EV (0 1 2 3 4 5 6 7 -8 -7 -6 -5 -4 -3 -2 -1)
  3121. \endcode
  3122. \endcom
  3123. %%% ========== BOOLE-1
  3124. %%% ========== BOOLE-2
  3125. %%% ========== BOOLE-AND
  3126. %%% ========== BOOLE-ANDC1
  3127. %%% ========== BOOLE-ANDC2
  3128. %%% ========== BOOLE-C1
  3129. %%% ========== BOOLE-C2
  3130. %%% ========== BOOLE-CLR
  3131. %%% ========== BOOLE-EQV
  3132. %%% ========== BOOLE-IOR
  3133. %%% ========== BOOLE-NAND
  3134. %%% ========== BOOLE-NOR
  3135. %%% ========== BOOLE-ORC1
  3136. %%% ========== BOOLE-ORC2
  3137. %%% ========== BOOLE-SET
  3138. %%% ========== BOOLE-XOR
  3139. \begincom{boole-1, boole-2, boole-and, boole-andc1, boole-andc2,
  3140. boole-c1, boole-c2, boole-clr, boole-eqv, boole-ior,
  3141. boole-nand, boole-nor, boole-orc1, boole-orc2, boole-set,
  3142. boole-xor}\ftype{Constant Variable}
  3143. \label Constant Value::
  3144. The identity and nature of the \term{values} of each of these \term{variables}
  3145. is \term{implementation-dependent},
  3146. except that it must be \term{distinct} from each of the \term{values} of the others,
  3147. and it must be a valid first \term{argument} to \thefunction{boole}.
  3148. \label Description::
  3149. Each of these \term{constants} has a \term{value} which is one of the
  3150. sixteen possible \term{bit-wise logical operation specifiers}.
  3151. \label Examples::
  3152. \code
  3153. (boole boole-ior 1 16) \EV 17
  3154. (boole boole-and -2 5) \EV 4
  3155. (boole boole-eqv 17 15) \EV -31
  3156. \endcode
  3157. \label See Also::
  3158. \funref{boole}
  3159. %% Per X3J13. -kmp 05-Oct-93
  3160. \label Notes:\None.
  3161. \endcom
  3162. %%% ========== LOGNAND
  3163. %%% ========== LOGEQV
  3164. %%% ========== LOGNOT
  3165. %%% ========== LOGIOR
  3166. %%% ========== LOGXOR
  3167. %%% ========== LOGNAND
  3168. %%% ========== LOGNOR
  3169. %%% ========== LOGANDC1
  3170. %%% ========== LOGANDC2
  3171. %%% ========== LOGORC1
  3172. %%% ========== LOGORC2
  3173. \begincom{logand, logandc1, logandc2, logeqv, logior,
  3174. lognand, lognor, lognot, logorc1, logorc2,
  3175. logxor}\ftype{Function}
  3176. \label Syntax::
  3177. \DefunWithValues logand {{\rest} integers} {result-integer}
  3178. \DefunWithValues logandc1 {integer-1 integer-2} {result-integer}
  3179. \DefunWithValues logandc2 {integer-1 integer-2} {result-integer}
  3180. \DefunWithValues logeqv {{\rest} integers} {result-integer}
  3181. \DefunWithValues logior {{\rest} integers} {result-integer}
  3182. \DefunWithValues lognand {integer-1 integer-2} {result-integer}
  3183. \DefunWithValues lognor {integer-1 integer-2} {result-integer}
  3184. \DefunWithValues lognot {integer} {result-integer}
  3185. \DefunWithValues logorc1 {integer-1 integer-2} {result-integer}
  3186. \DefunWithValues logorc2 {integer-1 integer-2} {result-integer}
  3187. \DefunWithValues logxor {{\rest} integers} {result-integer}
  3188. \label Arguments and Values::
  3189. \param{integers}---\term{integers}.
  3190. \param{integer}---an \term{integer}.
  3191. \param{integer-1}---an \term{integer}.
  3192. \param{integer-2}---an \term{integer}.
  3193. \param{result-integer}---an \term{integer}.
  3194. \label Description::
  3195. The \term{functions}
  3196. \funref{logandc1},
  3197. \funref{logandc2},
  3198. \funref{logand},
  3199. \funref{logeqv},
  3200. \funref{logior},
  3201. \funref{lognand},
  3202. \funref{lognor},
  3203. \funref{lognot},
  3204. \funref{logorc1},
  3205. \funref{logorc2},
  3206. and \funref{logxor}
  3207. perform bit-wise logical operations on their \term{arguments},
  3208. that are treated as if they were binary.
  3209. \Thenextfigure\ lists the meaning of each of the \term{functions}.
  3210. Where an `identity' is shown, it indicates the \term{value} \term{yielded}
  3211. by the \term{function} when no \term{arguments} are supplied.
  3212. %% 12.7.0 11
  3213. %% 12.7.0 8
  3214. %% 12.7.0 15
  3215. %% 12.7.0 5
  3216. %% 12.7.0 6
  3217. %% 12.7.0 7
  3218. \tablefigthree{Bit-wise Logical Operations on Integers}%
  3219. {Function}{Identity}{Operation performed}{
  3220. \funref{logandc1} & --- & and complement of \param{integer-1} with \param{integer-2} \cr
  3221. \funref{logandc2} & --- & and \param{integer-1} with complement of \param{integer-2} \cr
  3222. \funref{logand} & \f{-1} & and \cr
  3223. \funref{logeqv} & \f{-1} & equivalence (exclusive nor) \cr
  3224. \funref{logior} & \f{0} & inclusive or \cr
  3225. \funref{lognand} & --- & complement of \param{integer-1} and \param{integer-2} \cr
  3226. \funref{lognor} & --- & complement of \param{integer-1} or \param{integer-2} \cr
  3227. \funref{lognot} & --- & complement \cr
  3228. \funref{logorc1} & --- & or complement of \param{integer-1} with \param{integer-2} \cr
  3229. \funref{logorc2} & --- & or \param{integer-1} with complement of \param{integer-2} \cr
  3230. \funref{logxor} & \f{0} & exclusive or \cr
  3231. }
  3232. Negative \param{integers} are treated as if they were in two's-complement notation.
  3233. \label Examples::
  3234. \code
  3235. (logior 1 2 4 8) \EV 15
  3236. (logxor 1 3 7 15) \EV 10
  3237. (logeqv) \EV -1
  3238. (logand 16 31) \EV 16
  3239. (lognot 0) \EV -1
  3240. (lognot 1) \EV -2
  3241. (lognot -1) \EV 0
  3242. (lognot (1+ (lognot 1000))) \EV 999
  3243. ;;; In the following example, m is a mask. For each bit in
  3244. ;;; the mask that is a 1, the corresponding bits in x and y are
  3245. ;;; exchanged. For each bit in the mask that is a 0, the
  3246. ;;; corresponding bits of x and y are left unchanged.
  3247. (flet ((show (m x y)
  3248. (format t "~%m = #o~6,'0O~%x = #o~6,'0O~%y = #o~6,'0O~%"
  3249. m x y)))
  3250. (let ((m #o007750)
  3251. (x #o452576)
  3252. (y #o317407))
  3253. (show m x y)
  3254. (let ((z (logand (logxor x y) m)))
  3255. (setq x (logxor z x))
  3256. (setq y (logxor z y))
  3257. (show m x y))))
  3258. \OUT m = #o007750
  3259. \OUT x = #o452576
  3260. \OUT y = #o317407
  3261. \OUT
  3262. \OUT m = #o007750
  3263. \OUT x = #o457426
  3264. \OUT y = #o312557
  3265. \EV NIL
  3266. \endcode
  3267. \label Side Effects:\None.
  3268. \label Affected By:\None.
  3269. \label Exceptional Situations::
  3270. Should signal \typeref{type-error} if any argument is not an \term{integer}.
  3271. \label See Also::
  3272. \funref{boole}
  3273. \label Notes::
  3274. %Per Barmar.
  3275. \f{(logbitp \param{k} -1)} returns \term{true} for all values of \param{k}.
  3276. %% 12.7.0 9
  3277. Because the following functions are not associative,
  3278. they take exactly two arguments rather than any number
  3279. of arguments.
  3280. \code
  3281. (lognand \param{n1} \param{n2}) \EQ (lognot (logand \param{n1} \param{n2}))
  3282. (lognor \param{n1} \param{n2}) \EQ (lognot (logior \param{n1} \param{n2}))
  3283. (logandc1 \param{n1} \param{n2}) \EQ (logand (lognot \param{n1}) \param{n2})
  3284. (logandc2 \param{n1} \param{n2}) \EQ (logand \param{n1} (lognot \param{n2}))
  3285. (logiorc1 \param{n1} \param{n2}) \EQ (logior (lognot \param{n1}) \param{n2})
  3286. (logiorc2 \param{n1} \param{n2}) \EQ (logior \param{n1} (lognot \param{n2}))
  3287. (logbitp \param{j} (lognot \param{x})) \EQ (not (logbitp \param{j} \param{x}))
  3288. \endcode
  3289. \endcom
  3290. %%% ========== LOGBITP
  3291. \begincom{logbitp}\ftype{Function}
  3292. \label Syntax::
  3293. \DefunWithValues logbitp {index integer} {generalized-boolean}
  3294. \label Arguments and Values::
  3295. \issue{ARGUMENTS-UNDERSPECIFIED:SPECIFY}
  3296. \param{index}---a non-negative \term{integer}.
  3297. \endissue{ARGUMENTS-UNDERSPECIFIED:SPECIFY}
  3298. \param{integer}---an \term{integer}.
  3299. \param{generalized-boolean}---a \term{generalized boolean}.
  3300. \label Description::
  3301. \funref{logbitp} is used to test the value of a particular bit
  3302. in \param{integer}, that is treated as if it were binary.
  3303. %% 12.7.0 17
  3304. The value of \funref{logbitp} is \term{true} if the bit in \param{integer}
  3305. whose index is \param{index} (that is, its weight is $2^\i{index}$)
  3306. is a one-bit; otherwise it is \term{false}.
  3307. Negative \param{integers} are treated as if they were in
  3308. two's-complement notation.
  3309. \label Examples::
  3310. \code
  3311. (logbitp 1 1) \EV \term{false}
  3312. (logbitp 0 1) \EV \term{true}
  3313. (logbitp 3 10) \EV \term{true}
  3314. (logbitp 1000000 -1) \EV \term{true}
  3315. (logbitp 2 6) \EV \term{true}
  3316. (logbitp 0 6) \EV \term{false}
  3317. \endcode
  3318. \label Side Effects:\None.
  3319. \label Affected By:\None.
  3320. \label Exceptional Situations::
  3321. \Shouldchecktype{index}{a non-negative \term{integer}}
  3322. \Shouldchecktype{integer}{an \term{integer}}
  3323. \label See Also:\None.
  3324. \label Notes::
  3325. \code
  3326. (logbitp \param{k} \param{n}) \EQ (ldb-test (byte 1 \param{k}) \param{n})
  3327. \endcode
  3328. \endcom
  3329. %%% ========== LOGCOUNT
  3330. \begincom{logcount}\ftype{Function}
  3331. \label Syntax::
  3332. \DefunWithValues logcount {integer} {number-of-on-bits}
  3333. \label Arguments and Values::
  3334. \param{integer}---an \term{integer}.
  3335. \param{number-of-on-bits}---a non-negative \term{integer}.
  3336. \label Description::
  3337. %% 12.7.0 21
  3338. Computes and returns the number of bits
  3339. in the two's-complement binary representation of \param{integer}
  3340. that are `on' or `set'.
  3341. If \param{integer} is negative, the \f{0} bits are counted;
  3342. otherwise, the \f{1} bits are counted.
  3343. \label Examples::
  3344. \code
  3345. (logcount 0) \EV 0
  3346. (logcount -1) \EV 0
  3347. (logcount 7) \EV 3
  3348. (logcount 13) \EV 3 ;Two's-complement binary: ...0001101
  3349. (logcount -13) \EV 2 ;Two's-complement binary: ...1110011
  3350. (logcount 30) \EV 4 ;Two's-complement binary: ...0011110
  3351. (logcount -30) \EV 4 ;Two's-complement binary: ...1100010
  3352. (logcount (expt 2 100)) \EV 1
  3353. (logcount (- (expt 2 100))) \EV 100
  3354. (logcount (- (1+ (expt 2 100)))) \EV 1
  3355. \endcode
  3356. \label Side Effects:\None.
  3357. \label Affected By:\None.
  3358. \label Exceptional Situations::
  3359. Should signal \typeref{type-error} if its argument is not an \term{integer}.
  3360. \label See Also:\None.
  3361. \label Notes::
  3362. Even if the \term{implementation} does not represent \term{integers} internally
  3363. in two's complement binary, \funref{logcount} behaves as if it did.
  3364. The following identity always holds:
  3365. \code
  3366. (logcount \param{x})
  3367. \EQ (logcount (- (+ \param{x} 1)))
  3368. \EQ (logcount (lognot \param{x}))
  3369. \endcode
  3370. \endcom
  3371. %%% ========== LOGTEST
  3372. \begincom{logtest}\ftype{Function}
  3373. \label Syntax::
  3374. \DefunWithValues logtest {integer-1 integer-2} {generalized-boolean}
  3375. \label Arguments and Values::
  3376. \param{integer-1}---an \term{integer}.
  3377. \param{integer-2}---an \term{integer}.
  3378. \param{generalized-boolean}---a \term{generalized boolean}.
  3379. \label Description::
  3380. %% 12.7.0 16
  3381. Returns \term{true} if any of the bits designated by the 1's
  3382. in \param{integer-1} is 1 in \param{integer-2};
  3383. otherwise it is \term{false}.
  3384. \param{integer-1} and \param{integer-2} are treated as if they were binary.
  3385. Negative \param{integer-1} and \param{integer-2} are treated as if
  3386. they were represented in two's-complement binary.
  3387. \label Examples::
  3388. \code
  3389. (logtest 1 7) \EV \term{true}
  3390. (logtest 1 2) \EV \term{false}
  3391. (logtest -2 -1) \EV \term{true}
  3392. (logtest 0 -1) \EV \term{false}
  3393. \endcode
  3394. \label Side Effects:\None.
  3395. \label Affected By:\None.
  3396. \label Exceptional Situations::
  3397. \Shouldchecktype{integer-1}{an \term{integer}}
  3398. \Shouldchecktype{integer-2}{an \term{integer}}
  3399. \label See Also:\None.
  3400. \label Notes::
  3401. \code
  3402. (logtest \param{x} \param{y}) \EQ (not (zerop (logand \param{x} \param{y})))
  3403. \endcode
  3404. \endcom
  3405. %-------------------- Integer Bytes --------------------
  3406. %%% ========== BYTE
  3407. %%% ========== BYTE-SIZE
  3408. %%% ========== BYTE-POSITION
  3409. \begincom{byte, byte-size, byte-position}\ftype{Function}
  3410. \label Syntax::
  3411. \DefunWithValues byte {size position} {bytespec}
  3412. \DefunWithValues byte-size {bytespec} {size}
  3413. \DefunWithValues byte-position {bytespec} {position}
  3414. \label Arguments and Values::
  3415. %% 12.8.0 2
  3416. \param{size}, \param{position}---a non-negative \term{integer}.
  3417. \param{bytespec}---a \term{byte specifier}.
  3418. \label Description::
  3419. %% 12.8.0 3
  3420. %% 12.8.0 2
  3421. \funref{byte} returns a \term{byte specifier} that indicates
  3422. a \term{byte} of width \param{size} and whose bits have weights
  3423. $2^{\param{position} + \param{size} - 1\/}$ through $2^\param{position}$,
  3424. and whose representation is
  3425. \term{implementation-dependent}.
  3426. \funref{byte-size} returns the number of bits specified by \param{bytespec}.
  3427. \funref{byte-position} returns the position specified by \param{bytespec}.
  3428. \label Examples::
  3429. \code
  3430. (setq b (byte 100 200)) \EV #<BYTE-SPECIFIER size 100 position 200>
  3431. (byte-size b) \EV 100
  3432. (byte-position b) \EV 200
  3433. \endcode
  3434. \label Affected By:\None.
  3435. \label Exceptional Situations:\None.
  3436. \label See Also::
  3437. \funref{ldb}, \funref{dpb}
  3438. \label Notes::
  3439. %% 12.8.0 4
  3440. \code
  3441. (byte-size (byte \param{j} \param{k})) \EQ \param{j}
  3442. (byte-position (byte \param{j} \param{k})) \EQ \param{k}
  3443. \endcode
  3444. A \term{byte} of \term{size} of \f{0} is permissible;
  3445. it refers to a \term{byte} of width zero. For example,
  3446. \code
  3447. (ldb (byte 0 3) #o7777) \EV 0
  3448. (dpb #o7777 (byte 0 3) 0) \EV 0
  3449. \endcode
  3450. \endcom
  3451. %%% ========== DEPOSIT-FIELD
  3452. \begincom{deposit-field}\ftype{Function}
  3453. %% 12.8.0 12
  3454. \label Syntax::
  3455. \DefunWithValues deposit-field {newbyte bytespec integer} {result-integer}
  3456. \label Arguments and Values::
  3457. \param{newbyte}---an \term{integer}.
  3458. \param{bytespec}---a \term{byte specifier}.
  3459. \param{integer}---an \term{integer}.
  3460. \param{result-integer}---an \term{integer}.
  3461. \label Description::
  3462. %% 12.8.0 13
  3463. Replaces a field of bits within \param{integer}; specifically,
  3464. returns an \term{integer} that contains the bits of \param{newbyte}
  3465. within the \term{byte} specified by \param{bytespec},
  3466. and elsewhere contains the bits of \param{integer}.
  3467. \label Examples::
  3468. \code
  3469. (deposit-field 7 (byte 2 1) 0) \EV 6
  3470. (deposit-field -1 (byte 4 0) 0) \EV 15
  3471. (deposit-field 0 (byte 2 1) -3) \EV -7
  3472. \endcode
  3473. \label Side Effects:\None.
  3474. \label Affected By:\None.
  3475. \label Exceptional Situations:\None.
  3476. \label See Also::
  3477. \funref{byte},
  3478. \funref{dpb}
  3479. \label Notes::
  3480. \code
  3481. (logbitp \param{j} (deposit-field \param{m} (byte \param{s} \param{p}) \param{n}))
  3482. \EQ (if (and (>= \param{j} \param{p}) (< \param{j} (+ \param{p} \param{s})))
  3483. (logbitp \param{j} \param{m})
  3484. (logbitp \param{j} \param{n}))
  3485. \endcode
  3486. \funref{deposit-field} is to \funref{mask-field}
  3487. as \funref{dpb} is to \funref{ldb}.
  3488. \endcom
  3489. %%% ========== DPB
  3490. \begincom{dpb}\ftype{Function}
  3491. \label Syntax::
  3492. \DefunWithValues dpb {newbyte bytespec integer} {result-integer}
  3493. \label Pronunciation::
  3494. \pronounced{\stress{d\schwa }\Stress{pib}}
  3495. or \pronounced{\stress{d\schwa }\Stress{p\schwa b}}
  3496. or \pronounced{\Stress{d\harde}\Stress{p\harde}\Stress{b\harde}}
  3497. \label Arguments and Values::
  3498. \param{newbyte}---an \term{integer}.
  3499. \param{bytespec}---a \term{byte specifier}.
  3500. \param{integer}---an \term{integer}.
  3501. \param{result-integer}---an \term{integer}.
  3502. \label Description::
  3503. %% 12.8.0 11
  3504. \funref{dpb} (deposit byte) is used to
  3505. replace a field of bits within \param{integer}.
  3506. \funref{dpb} returns an \term{integer} that is
  3507. the same as \param{integer} except in the bits specified by \param{bytespec}.
  3508. Let \f{s} be the size specified
  3509. by \param{bytespec}; then the low \f{s} bits of \param{newbyte} appear in
  3510. the result in the byte specified by \param{bytespec}.
  3511. \param{Newbyte} is interpreted as
  3512. being right-justified, as if it were the result of \funref{ldb}.
  3513. \label Examples::
  3514. \code
  3515. (dpb 1 (byte 1 10) 0) \EV 1024
  3516. (dpb -2 (byte 2 10) 0) \EV 2048
  3517. (dpb 1 (byte 2 10) 2048) \EV 1024
  3518. \endcode
  3519. \label Side Effects:\None.
  3520. \label Affected By:\None.
  3521. \label Exceptional Situations:\None.
  3522. \label See Also::
  3523. \funref{byte}, \funref{deposit-field}, \funref{ldb}
  3524. \label Notes::
  3525. \code
  3526. (logbitp \param{j} (dpb \param{m} (byte \param{s} \param{p}) \param{n}))
  3527. \EQ (if (and (>= \param{j} \param{p}) (< \param{j} (+ \param{p} \param{s})))
  3528. (logbitp (- \param{j} \param{p}) \param{m})
  3529. (logbitp \param{j} \param{n}))
  3530. \endcode
  3531. In general,
  3532. \code
  3533. (dpb \param{x} (byte 0 \param{y}) \param{z}) \EV \param{z}
  3534. \endcode
  3535. for all valid values of \param{x}, \param{y}, and \param{z}.
  3536. Historically, the name ``dpb'' comes from a DEC PDP-10 assembly language
  3537. instruction meaning ``deposit byte.''
  3538. \endcom
  3539. %%% ========== LDB
  3540. \begincom{ldb}\ftype{Accessor}
  3541. \label Syntax::
  3542. \DefunWithValues ldb {bytespec integer} {byte}
  3543. \Defsetf ldb {bytespec place} {new-byte}
  3544. \label Pronunciation::
  3545. \pronounced{\Stress{lid}ib}
  3546. or \pronounced{\Stress{lid}\schwa b}
  3547. or \pronounced{\Stress{el}\Stress{d\harde}\Stress{b\harde}}
  3548. \label Arguments and Values::
  3549. \param{bytespec}---a \term{byte specifier}.
  3550. \param{integer}---an \term{integer}.
  3551. \param{byte}, \param{new-byte}---a non-negative \term{integer}.
  3552. \label Description::
  3553. %% 12.8.0 5
  3554. \funref{ldb} extracts and returns the \term{byte} of \param{integer}
  3555. specified by \param{bytespec}.
  3556. \funref{ldb} returns an \term{integer} in which the bits with weights
  3557. $2^{(\i{s}-1)}$ through $2^{0}$ are the same as those in
  3558. \param{integer} with weights $2^{(\i{p}+\i{s}-1)}$
  3559. through $2^\i{p}$, and all other bits zero; \i{s} is
  3560. \f{(byte-size \param{bytespec})}
  3561. and \i{p} is \f{(byte-position \param{bytespec})}.
  3562. %% 12.8.0 7
  3563. \macref{setf} may be used with \funref{ldb} to modify
  3564. a byte within the \param{integer} that is stored
  3565. in a given \param{place}.
  3566. \issue{PUSH-EVALUATION-ORDER:FIRST-ITEM}
  3567. The order of evaluation, when an \funref{ldb} form is supplied
  3568. to \macref{setf}, is exactly left-to-right.
  3569. \idxtext{order of evaluation}\idxtext{evaluation order}%
  3570. \endissue{PUSH-EVALUATION-ORDER:FIRST-ITEM}
  3571. The effect is to perform a \funref{dpb} operation
  3572. and then store the result back into the \param{place}.
  3573. \label Examples::
  3574. \code
  3575. (ldb (byte 2 1) 10) \EV 1
  3576. (setq a (list 8)) \EV (8)
  3577. (setf (ldb (byte 2 1) (car a)) 1) \EV 1
  3578. a \EV (10)
  3579. \endcode
  3580. \label Side Effects:\None.
  3581. \label Affected By:\None.
  3582. \label Exceptional Situations:\None.
  3583. \label See Also::
  3584. \funref{byte},
  3585. \funref{byte-position},
  3586. \funref{byte-size},
  3587. \funref{dpb}
  3588. \label Notes::
  3589. \code
  3590. (logbitp \param{j} (ldb (byte \param{s} \param{p}) \param{n}))
  3591. \EQ (and (< \param{j} \param{s}) (logbitp (+ \param{j} \param{p}) \param{n}))
  3592. \endcode
  3593. In general,
  3594. \code
  3595. (ldb (byte 0 \param{x}) \param{y}) \EV 0
  3596. \endcode
  3597. for all valid values of \param{x} and \param{y}.
  3598. Historically, the name ``ldb'' comes from a DEC PDP-10 assembly language
  3599. instruction meaning ``load byte.''
  3600. \endcom
  3601. %%% ========== LDB-TEST
  3602. \begincom{ldb-test}\ftype{Function}
  3603. \label Syntax::
  3604. \DefunWithValues ldb-test {bytespec integer} {generalized-boolean}
  3605. \label Arguments and Values::
  3606. \param{bytespec}---a \term{byte specifier}.
  3607. \param{integer}---an \term{integer}.
  3608. \param{generalized-boolean}---a \term{generalized boolean}.
  3609. \label Description::
  3610. %% 12.8.0 8
  3611. Returns \term{true} if any of the bits of the byte in \param{integer}
  3612. specified by \param{bytespec} is non-zero; otherwise returns \term{false}.
  3613. \label Examples::
  3614. \code
  3615. (ldb-test (byte 4 1) 16) \EV \term{true}
  3616. (ldb-test (byte 3 1) 16) \EV \term{false}
  3617. (ldb-test (byte 3 2) 16) \EV \term{true}
  3618. \endcode
  3619. \label Side Effects:\None.
  3620. \label Affected By:\None.
  3621. \label Exceptional Situations:\None.
  3622. \label See Also::
  3623. \funref{byte}, \funref{ldb}, \funref{zerop}
  3624. \label Notes::
  3625. \code
  3626. (ldb-test bytespec n) \EQ
  3627. (not (zerop (ldb bytespec n))) \EQ
  3628. (logtest (ldb bytespec -1) n)
  3629. \endcode
  3630. %Item 3 of that equivalence contributed by Barmar. -kmp 16-Jul-91
  3631. \endcom
  3632. %%% ========== MASK-FIELD
  3633. \begincom{mask-field}\ftype{Accessor}
  3634. \label Syntax::
  3635. \DefunWithValues mask-field {bytespec integer} {masked-integer}
  3636. \Defsetf mask-field {bytespec place} {new-masked-integer}
  3637. \label Arguments and Values::
  3638. \param{bytespec}---a \term{byte specifier}.
  3639. \param{integer}---an \term{integer}.
  3640. \param{masked-integer}, \param{new-masked-integer}---a non-negative \term{integer}.
  3641. \label Description::
  3642. %% 12.8.0 9
  3643. \funref{mask-field} performs a ``mask'' operation on \param{integer}.
  3644. It returns an \term{integer} that has the same bits as \param{integer} in
  3645. the \term{byte} specified by \param{bytespec}, but that has zero-bits everywhere else.
  3646. %% 12.8.0 10
  3647. \macref{setf} may be used with \funref{mask-field}
  3648. to modify a byte within the \term{integer} that is stored
  3649. in a given \param{place}.
  3650. The effect is to perform a \funref{deposit-field} operation
  3651. and then store the result back into the \param{place}.
  3652. \label Examples::
  3653. \code
  3654. (mask-field (byte 1 5) -1) \EV 32
  3655. (setq a 15) \EV 15
  3656. (mask-field (byte 2 0) a) \EV 3
  3657. a \EV 15
  3658. (setf (mask-field (byte 2 0) a) 1) \EV 1
  3659. a \EV 13
  3660. \endcode
  3661. \label Side Effects:\None.
  3662. \label Affected By:\None.
  3663. \label Exceptional Situations:\None.
  3664. \label See Also::
  3665. \funref{byte},
  3666. \funref{ldb}
  3667. \label Notes::
  3668. \code
  3669. (ldb \param{bs} (mask-field \param{bs} \param{n})) \EQ (ldb \param{bs} \param{n})
  3670. (logbitp \param{j} (mask-field (byte \param{s} \param{p}) \param{n}))
  3671. \EQ (and (>= \param{j} \param{p}) (< \param{j} \param{s}) (logbitp \param{j} \param{n}))
  3672. (mask-field \param{bs} \param{n}) \EQ (logand \param{n} (dpb -1 \param{bs} 0))
  3673. \endcode
  3674. \endcom
  3675. %-------------------- Fixnum --------------------
  3676. %%% ========== MOST-POSITIVE-FIXNUM
  3677. %%% ========== MOST-NEGATIVE-FIXNUM
  3678. \begincom{most-positive-fixnum, most-negative-fixnum}\ftype{Constant Variable}
  3679. \label Constant Value::
  3680. \term{implementation-dependent}.
  3681. \label Description::
  3682. %% 12.10.0 1
  3683. %% 12.10.0 2
  3684. \conref{most-positive-fixnum} is that \term{fixnum} closest in value
  3685. to positive infinity provided by the implementation,
  3686. \issue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  3687. and greater than or equal to both $2^{15}$ - 1 and
  3688. \conref{array-dimension-limit}.
  3689. \endissue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  3690. %% 12.10.0 4
  3691. \conref{most-negative-fixnum} is that \term{fixnum} closest in value
  3692. to negative infinity provided by the implementation,
  3693. \issue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  3694. and less than or equal to $-2^{15}$.
  3695. \endissue{FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION}
  3696. \label Examples:\None.
  3697. \label See Also:\None.
  3698. \label Notes:\None.
  3699. \endcom
  3700. %-------------------- Ratio --------------------
  3701. %-------------------- Float --------------------
  3702. %%% ========== DECODE-FLOAT
  3703. %%% ========== SCALE-FLOAT
  3704. %%% ========== FLOAT-RADIX
  3705. %%% ========== FLOAT-SIGN
  3706. %%% ========== FLOAT-DIGITS
  3707. %%% ========== FLOAT-PRECISION
  3708. %%% ========== INTEGER-DECODE-FLOAT
  3709. \begincom{decode-float, scale-float, float-radix, float-sign,
  3710. float-digits, float-precision, integer-decode-float}\ftype{Function}
  3711. \label Syntax::
  3712. \DefunWithValues decode-float {float} {significand, exponent, sign}
  3713. \DefunWithValues scale-float {float integer} {scaled-float}
  3714. \DefunWithValues float-radix {float} {float-radix}
  3715. \DefunWithValues float-sign {float-1 {\opt} float-2} {signed-float}
  3716. \DefunWithValues float-digits {float} {digits1}
  3717. \DefunWithValues float-precision {float} {digits2}
  3718. \DefunWithValues integer-decode-float {float} {significand, exponent, integer-sign}
  3719. \label Arguments and Values::
  3720. \param{digits1}---a non-negative \term{integer}.
  3721. \param{digits2}---a non-negative \term{integer}.
  3722. \param{exponent}---an \term{integer}.
  3723. \param{float}---a \term{float}.
  3724. \param{float-1}---a \term{float}.
  3725. \param{float-2}---a \term{float}.
  3726. \param{float-radix}---an \term{integer}.
  3727. \param{integer}---a non-negative \term{integer}.
  3728. \param{integer-sign}---the \term{integer} \f{-1},
  3729. or the \term{integer} \f{1}.
  3730. \param{scaled-float}---a \term{float}.
  3731. \param{sign}---A \term{float} of the same \term{type} as \param{float}
  3732. but numerically equal to \f{1.0} or \f{-1.0}.
  3733. \param{signed-float}---a \term{float}.
  3734. \param{significand}---a \term{float}.
  3735. \label Description::
  3736. %% 12.6.0 27
  3737. %% 12.6.0 28
  3738. \funref{decode-float} computes three values that characterize
  3739. \param{float}.
  3740. The first value is of the same \term{type}
  3741. as \param{float} and
  3742. represents the significand.
  3743. The second value represents the exponent
  3744. to which the radix (notated in this description by \i{b}) must
  3745. be raised to obtain the value that, when multiplied with the first
  3746. result, produces the absolute value of \param{float}.
  3747. If \param{float} is zero, any \term{integer} value may be returned,
  3748. provided that the identity shown for \funref{scale-float} holds.
  3749. The third value
  3750. is of the same \term{type} as \param{float}
  3751. and is 1.0 if \param{float} is greater
  3752. than or equal to zero or -1.0 otherwise.
  3753. \funref{decode-float}
  3754. divides \param{float} by an integral power of \i{b}
  3755. so as to bring its value between $1/\i{b}$ (inclusive) and~$1$ (exclusive),
  3756. and returns the quotient as the first value.
  3757. If \param{float} is zero, however, the result
  3758. equals the absolute value of \param{float} (that is, if there is a negative
  3759. zero, its significand is considered to be a positive zero).
  3760. %% 12.6.0 29
  3761. \funref{scale-float} returns
  3762. {\tt (* \param{float} (expt (float \i{b} \param{float})
  3763. \param{integer}))\/}, where \i{b} is the radix of the floating-point
  3764. representation. \param{float} is not necessarily between $1/\i{b}$ and~$1$.
  3765. %% 12.6.0 31
  3766. \funref{float-radix} returns
  3767. the radix of \param{float}.
  3768. %% 12.6.0 32
  3769. \funref{float-sign} returns a number \f{z} such
  3770. that \f{z} and \param{float-1} have the same sign and also such that
  3771. \f{z} and \param{float-2} have the same absolute value.
  3772. If \param{float-2} is not supplied, its value is \f{(float 1 \param{float-1})}.
  3773. %% Barmar says this is redundant. I agree. -kmp 28-Dec-90
  3774. % \f{(float-sign x)} produces a \f{1.0} or \f{-1.0}
  3775. % of appropriate format
  3776. % according to the sign of \f{x} if \param{float-2} is not supplied.
  3777. If an implementation
  3778. has distinct representations for negative zero and positive zero,
  3779. then \f{(float-sign -0.0)} \EV\ \f{-1.0}.
  3780. %% 12.6.0 33
  3781. \funref{float-digits} returns
  3782. the number of radix \i{b} digits
  3783. used in the representation of \param{float} (including any implicit
  3784. digits, such as a ``hidden bit'').
  3785. \funref{float-precision}
  3786. returns
  3787. the number of significant radix \i{b} digits present in \param{float};
  3788. if \param{float} is a \term{float}
  3789. zero, then the result is an \term{integer} zero.
  3790. For \term{normalized} \term{floats},
  3791. the results of \funref{float-digits} and \funref{float-precision} are the same,
  3792. but the precision is less than the number of representation digits
  3793. for a \term{denormalized} or zero number.
  3794. %% 12.6.0 34
  3795. %% 12.6.0 35
  3796. %% 12.6.0 36
  3797. \funref{integer-decode-float} computes three values that characterize
  3798. \param{float} -
  3799. the significand scaled so as to be an \term{integer},
  3800. and the same last two
  3801. values that are returned by \funref{decode-float}.
  3802. If \param{float} is zero, \funref{integer-decode-float} returns
  3803. zero as the first value.
  3804. The second value bears the same relationship to the first value
  3805. as for \funref{decode-float}:
  3806. \code
  3807. (multiple-value-bind (signif expon sign)
  3808. (integer-decode-float f)
  3809. (scale-float (float signif f) expon)) \EQ (abs f)
  3810. \endcode
  3811. \label Examples::
  3812. \code
  3813. ;; Note that since the purpose of this functionality is to expose
  3814. ;; details of the implementation, all of these examples are necessarily
  3815. ;; very implementation-dependent. Results may vary widely.
  3816. ;; Values shown here are chosen consistently from one particular implementation.
  3817. (decode-float .5) \EV 0.5, 0, 1.0
  3818. (decode-float 1.0) \EV 0.5, 1, 1.0
  3819. (scale-float 1.0 1) \EV 2.0
  3820. (scale-float 10.01 -2) \EV 2.5025
  3821. (scale-float 23.0 0) \EV 23.0
  3822. (float-radix 1.0) \EV 2
  3823. (float-sign 5.0) \EV 1.0
  3824. (float-sign -5.0) \EV -1.0
  3825. (float-sign 0.0) \EV 1.0
  3826. (float-sign 1.0 0.0) \EV 0.0
  3827. (float-sign 1.0 -10.0) \EV 10.0
  3828. (float-sign -1.0 10.0) \EV -10.0
  3829. (float-digits 1.0) \EV 24
  3830. (float-precision 1.0) \EV 24
  3831. (float-precision least-positive-single-float) \EV 1
  3832. (integer-decode-float 1.0) \EV 8388608, -23, 1
  3833. \endcode
  3834. \label Side Effects:\None.
  3835. \label Affected By::
  3836. The implementation's representation for \term{floats}.
  3837. \label Exceptional Situations::
  3838. The functions \funref{decode-float}, \funref{float-radix}, \funref{float-digits},
  3839. \funref{float-precision}, and \funref{integer-decode-float} should signal an error
  3840. if their only argument is not a \term{float}.
  3841. \Thefunction{scale-float} should signal an error if its first argument
  3842. is not a \term{float} or if its second argument is not an \term{integer}.
  3843. \Thefunction{float-sign} should signal an error if its first argument
  3844. is not a \term{float} or if its second argument is supplied but is
  3845. not a \term{float}.
  3846. \label See Also:\None.
  3847. \label Notes::
  3848. The product of the first result of \funref{decode-float} or \funref{integer-decode-float},
  3849. of the radix raised to the power of the second result, and of the third result
  3850. is exactly equal to the value of \param{float}.
  3851. %% 12.6.0 30
  3852. \code
  3853. (multiple-value-bind (signif expon sign)
  3854. (decode-float f)
  3855. (scale-float signif expon))
  3856. \EQ (abs f)
  3857. \endcode
  3858. and
  3859. \code
  3860. (multiple-value-bind (signif expon sign)
  3861. (decode-float f)
  3862. (* (scale-float signif expon) sign))
  3863. \EQ f
  3864. \endcode
  3865. \endcom
  3866. %%% ========== FLOAT
  3867. \begincom{float}\ftype{Function}
  3868. \label Syntax::
  3869. \DefunWithValues float {number {\opt} prototype} {float}
  3870. \label Arguments and Values::
  3871. \param{number}---a \term{real}.
  3872. \param{prototype}---a \term{float}.
  3873. \param{float}---a \term{float}.
  3874. \label Description::
  3875. %% 12.6.0 4
  3876. \funref{float} converts a
  3877. \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  3878. \term{real}
  3879. \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89}
  3880. number to a \term{float}.
  3881. If a \param{prototype} is supplied,
  3882. a \term{float} is returned that is mathematically equal to \param{number}
  3883. but has the same format as \param{prototype}.
  3884. If \param{prototype} is not supplied,
  3885. then if the \param{number} is already a \term{float}, it is returned;
  3886. otherwise, a \term{float} is returned that is mathematically equal to \param{number}
  3887. but is a \term{single float}.
  3888. \label Examples::
  3889. \code
  3890. (float 0) \EV 0.0
  3891. (float 1 .5) \EV 1.0
  3892. (float 1.0) \EV 1.0
  3893. (float 1/2) \EV 0.5
  3894. \EV 1.0d0
  3895. \OV 1.0
  3896. (eql (float 1.0 1.0d0) 1.0d0) \EV \term{true}
  3897. \endcode
  3898. \label Side Effects:\None.
  3899. \label Affected By:\None.
  3900. \label Exceptional Situations:\None.
  3901. \label See Also::
  3902. \funref{coerce}
  3903. \label Notes:\None.
  3904. \endcom
  3905. %%% ========== FLOATP
  3906. \begincom{floatp}\ftype{Function}
  3907. \label Syntax::
  3908. \Defun floatp {object} {generalized-boolean}
  3909. \label Arguments and Values::
  3910. \param{object}---an \term{object}.
  3911. \param{generalized-boolean}---a \term{generalized boolean}.
  3912. \label Description::
  3913. %% 6.2.2 15
  3914. \TypePredicate{object}{float}
  3915. \label Examples::
  3916. \code
  3917. (floatp 1.2d2) \EV \term{true}
  3918. (floatp 1.212) \EV \term{true}
  3919. (floatp 1.2s2) \EV \term{true}
  3920. (floatp (expt 2 130)) \EV \term{false}
  3921. \endcode
  3922. \label Side Effects:\None.
  3923. \label Affected By:\None.
  3924. \label Exceptional Situations:\None!
  3925. \label See Also:\None.
  3926. \label Notes::
  3927. \code
  3928. (floatp \param{object}) \EQ (typep \param{object} 'float)
  3929. \endcode
  3930. \endcom
  3931. %-------------------- Float Subtypes --------------------
  3932. %%% ========== LEAST-NEGATIVE-DOUBLE-FLOAT
  3933. %%% ========== LEAST-NEGATIVE-NORMALIZED-DOUBLE-FLOAT
  3934. %%% ========== LEAST-NEGATIVE-LONG-FLOAT
  3935. %%% ========== LEAST-NEGATIVE-NORMALIZED-LONG-FLOAT
  3936. %%% ========== LEAST-NEGATIVE-SHORT-FLOAT
  3937. %%% ========== LEAST-NEGATIVE-NORMALIZED-SHORT-FLOAT
  3938. %%% ========== LEAST-NEGATIVE-SINGLE-FLOAT
  3939. %%% ========== LEAST-NEGATIVE-NORMALIZED-SINGLE-FLOAT
  3940. %%% ========== LEAST-POSITIVE-DOUBLE-FLOAT
  3941. %%% ========== LEAST-POSITIVE-NORMALIZED-DOUBLE-FLOAT
  3942. %%% ========== LEAST-POSITIVE-LONG-FLOAT
  3943. %%% ========== LEAST-POSITIVE-NORMALIZED-LONG-FLOAT
  3944. %%% ========== LEAST-POSITIVE-SHORT-FLOAT
  3945. %%% ========== LEAST-POSITIVE-NORMALIZED-SHORT-FLOAT
  3946. %%% ========== LEAST-POSITIVE-SINGLE-FLOAT
  3947. %%% ========== LEAST-POSITIVE-NORMALIZED-SINGLE-FLOAT
  3948. %%% ========== MOST-NEGATIVE-DOUBLE-FLOAT
  3949. %%% ========== MOST-NEGATIVE-LONG-FLOAT
  3950. %%% ========== MOST-NEGATIVE-SHORT-FLOAT
  3951. %%% ========== MOST-NEGATIVE-SINGLE-FLOAT
  3952. %%% ========== MOST-POSITIVE-DOUBLE-FLOAT
  3953. %%% ========== MOST-POSITIVE-LONG-FLOAT
  3954. %%% ========== MOST-POSITIVE-SHORT-FLOAT
  3955. %%% ========== MOST-POSITIVE-SINGLE-FLOAT
  3956. \begincom{most-positive-short-float, least-positive-short-float,
  3957. least-positive-normalized-short-float,
  3958. most-positive-double-float, least-positive-double-float,
  3959. least-positive-normalized-double-float,
  3960. most-positive-long-float, least-positive-long-float,
  3961. least-positive-normalized-long-float,
  3962. most-positive-single-float, least-positive-single-float,
  3963. least-positive-normalized-single-float,
  3964. most-negative-short-float, least-negative-short-float,
  3965. least-negative-normalized-short-float,
  3966. most-negative-single-float, least-negative-single-float,
  3967. least-negative-normalized-single-float,
  3968. most-negative-double-float, least-negative-double-float,
  3969. least-negative-normalized-double-float,
  3970. most-negative-long-float, least-negative-long-float,
  3971. least-negative-normalized-long-float}\ftype{Constant Variable}
  3972. \issue{FLOAT-UNDERFLOW:ADD-VARIABLES}
  3973. \label Constant Value::
  3974. \term{implementation-dependent}.
  3975. \label Description::
  3976. %% 12.10.0 9
  3977. These \term{constant variables} provide a way for programs to examine
  3978. the \term{implementation-defined} limits for the various float formats.
  3979. Of these \term{variables},
  3980. each which has ``\f{-normalized}'' in its \term{name}
  3981. must have a \term{value} which is a \term{normalized} \term{float}, and
  3982. each which does not have ``\f{-normalized}'' in its name
  3983. may have a \term{value} which is either a \term{normalized} \term{float}
  3984. or a \term{denormalized} \term{float}, as appropriate.
  3985. Of these \term{variables},
  3986. each which has ``\f{short-float}'' in its name
  3987. must have a \term{value} which is a \term{short float},
  3988. each which has ``\f{single-float}'' in its name
  3989. must have a \term{value} which is a \term{single float},
  3990. each which has ``\f{double-float}'' in its name
  3991. must have a \term{value} which is a \term{double float}, and
  3992. each which has ``\f{long-float}'' in its name
  3993. must have a \term{value} which is a \term{long float}.
  3994. \beginlist
  3995. \itemitem{\bull}
  3996. \vtop{\hbox{\conref{most-positive-short-float},
  3997. \conref{most-positive-single-float},}
  3998. \hbox{\conref{most-positive-double-float},
  3999. \conref{most-positive-long-float}}}
  4000. \Vskip 18pt!
  4001. Each of these \term{constant variables} has as its \term{value}
  4002. the positive \term{float} of the largest magnitude
  4003. (closest in value to, but not equal to, positive infinity)
  4004. for the float format implied by its name.
  4005. \itemitem{\bull}
  4006. \vtop{\hbox{\conref{least-positive-short-float},
  4007. \conref{least-positive-normalized-short-float},}
  4008. \hbox{\conref{least-positive-single-float},
  4009. \conref{least-positive-normalized-single-float},}
  4010. \hbox{\conref{least-positive-double-float},
  4011. \conref{least-positive-normalized-double-float},}
  4012. \hbox{\conref{least-positive-long-float},
  4013. \conref{least-positive-normalized-long-float}}}
  4014. \Vskip 42pt!
  4015. Each of these \term{constant variables} has as its \term{value}
  4016. the smallest positive (nonzero) \term{float}
  4017. for the float format implied by its name.
  4018. \itemitem{\bull}
  4019. \vtop{\hbox{\conref{least-negative-short-float},
  4020. \conref{least-negative-normalized-short-float},}
  4021. \hbox{\conref{least-negative-single-float},
  4022. \conref{least-negative-normalized-single-float},}
  4023. \hbox{\conref{least-negative-double-float},
  4024. \conref{least-negative-normalized-double-float},}
  4025. \hbox{\conref{least-negative-long-float},
  4026. \conref{least-negative-normalized-long-float}}}
  4027. \Vskip 42pt!
  4028. Each of these \term{constant variables} has as its \term{value}
  4029. the negative (nonzero) \term{float} of the smallest magnitude
  4030. for the float format implied by its name.
  4031. (If an implementation supports minus zero as a \term{different}
  4032. \term{object} from positive zero, this value must not be minus zero.)
  4033. \itemitem{\bull}
  4034. \vtop{\hbox{\conref{most-negative-short-float},
  4035. \conref{most-negative-single-float},}
  4036. \hbox{\conref{most-negative-double-float},
  4037. \conref{most-negative-long-float}}}
  4038. \Vskip 18pt!
  4039. Each of these \term{constant variables} has as its \term{value}
  4040. the negative \term{float} of the largest magnitude
  4041. (closest in value to, but not equal to, negative infinity)
  4042. for the float format implied by its name.
  4043. \endlist
  4044. \label Examples:\None.
  4045. \label See Also:\None.
  4046. \label Notes::
  4047. \endissue{FLOAT-UNDERFLOW:ADD-VARIABLES}
  4048. \endcom
  4049. %%% ========== SHORT-FLOAT-EPSILON
  4050. %%% ========== SHORT-FLOAT-NEGATIVE-EPSILON
  4051. %%% ========== SINGLE-FLOAT-EPSILON
  4052. %%% ========== SINGLE-FLOAT-NEGATIVE-EPSILON
  4053. %%% ========== DOUBLE-FLOAT-EPSILON
  4054. %%% ========== DOUBLE-FLOAT-NEGATIVE-EPSILON
  4055. %%% ========== LONG-FLOAT-EPSILON
  4056. %%% ========== LONG-FLOAT-NEGATIVE-EPSILON
  4057. \begincom{short-float-epsilon, short-float-negative-epsilon,
  4058. single-float-epsilon, single-float-negative-epsilon,
  4059. double-float-epsilon, double-float-negative-epsilon,
  4060. long-float-epsilon, long-float-negative-epsilon}\ftype{Constant Variable}
  4061. \label Constant Value::
  4062. %% 12.10.0 10
  4063. \term{implementation-dependent}.
  4064. \label Description::
  4065. The value of each of the constants \conref{short-float-epsilon},
  4066. \conref{single-float-epsilon},
  4067. \conref{double-float-epsilon}, and \conref{long-float-epsilon} is
  4068. the smallest positive \term{float} $\epsilon$ of the given format,
  4069. such that the following expression is \term{true} when evaluated:
  4070. {\tt (not (= (float 1 $\epsilon$) (+ (float 1 $\epsilon$) $\epsilon$)))\/}
  4071. The value of each of the constants \conref{short-float-negative-epsilon},
  4072. \conref{single-float-negative-epsilon},
  4073. \conref{double-float-negative-epsilon}, and
  4074. \conref{long-float-negative-epsilon} is the smallest positive
  4075. \term{float} $\epsilon$ of the given format, such that the following
  4076. expression is \term{true} when evaluated:
  4077. {\tt (not (= (float 1 $\epsilon$) (- (float 1 $\epsilon$) $\epsilon$)))\/}
  4078. \label Examples:\None.
  4079. \label See Also:\None.
  4080. \label Notes:\None.
  4081. \endcom
  4082. %%% ========== ARITHMETIC-ERROR
  4083. \begincom{arithmetic-error}\ftype{Condition Type}
  4084. \label Class Precedence List::
  4085. \typeref{arithmetic-error},
  4086. \typeref{error},
  4087. \typeref{serious-condition},
  4088. \typeref{condition},
  4089. \typeref{t}
  4090. \label Description::
  4091. \Thetype{arithmetic-error} consists of error conditions
  4092. that occur during arithmetic operations.
  4093. The operation and operands are initialized with
  4094. \theinitkeyargs{operation} and \kwd{operands} to \funref{make-condition},
  4095. and are \term{accessed} by
  4096. the functions \funref{arithmetic-error-operation} and
  4097. \funref{arithmetic-error-operands}.
  4098. \label See Also::
  4099. \funref{arithmetic-error-operation}, \funref{arithmetic-error-operands}
  4100. \endcom%{arithmetic-error}\ftype{Condition Type}
  4101. %%% ========== ARITHMETIC-ERROR-OPERANDS
  4102. \begincom{arithmetic-error-operands, arithmetic-error-operation}\ftype{Function}
  4103. \label Syntax::
  4104. \DefunWithValues arithmetic-error-operands {condition} {operands}
  4105. \DefunWithValues arithmetic-error-operation {condition} {operation}
  4106. \label Arguments and Values::
  4107. \param{condition}---a \term{condition} \oftype{arithmetic-error}.
  4108. \param{operands}---a \term{list}.
  4109. \param{operation}---a \term{function designator}.
  4110. \label Description::
  4111. \funref{arithmetic-error-operands} returns a \term{list} of the operands
  4112. which were used in the offending call to the operation that signaled
  4113. the \param{condition}.
  4114. \funref{arithmetic-error-operation} returns a \term{list} of
  4115. the offending operation in the offending call that signaled the \param{condition}.
  4116. \label Examples:\None.
  4117. \label Side Effects:\None.
  4118. \label Affected By:\None!
  4119. \label Exceptional Situations:\None.
  4120. \label See Also::
  4121. \typeref{arithmetic-error},
  4122. {\chapref\Conditions}
  4123. \label Notes::
  4124. %%Shouldn't be needed any more. -kmp 1-Sep-91
  4125. %It is an error to use \macref{setf} with \funref{arithmetic-error-operands}.
  4126. \endcom
  4127. \begincom{division-by-zero}\ftype{Condition Type}
  4128. \label Class Precedence List::
  4129. \typeref{division-by-zero},
  4130. \typeref{arithmetic-error},
  4131. \typeref{error},
  4132. \typeref{serious-condition},
  4133. \typeref{condition},
  4134. \typeref{t}
  4135. \label Description::
  4136. \Thetype{division-by-zero} consists of error conditions that
  4137. occur because of division by zero.
  4138. \endcom%{division-by-zero}\ftype{Condition Type}
  4139. %!!! ACW: A statement of the intended difference between
  4140. % FLOATING-POINT-INVALID-OPERATION and FLOATING-POINT-INEXACT would be helpful.
  4141. \begincom{floating-point-invalid-operation}\ftype{Condition Type}
  4142. \issue{FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89}
  4143. \label Class Precedence List::
  4144. \typeref{floating-point-invalid-operation},
  4145. \typeref{arithmetic-error},
  4146. \typeref{error},
  4147. \typeref{serious-condition},
  4148. \typeref{condition},
  4149. \typeref{t}
  4150. \label Description::
  4151. \Thetype{floating-point-invalid-operation} consists of
  4152. error conditions that occur because of certain
  4153. %!!! Barmar: which?
  4154. floating point traps.
  4155. It is \term{implementation-dependent} whether floating point traps
  4156. occur, and whether or how they may be enabled or disabled. Therefore,
  4157. conforming code may establish handlers for this condition, but must not
  4158. depend on its being \term{signaled}.
  4159. \endissue{FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89}
  4160. \endcom%{floating-point-invalid-operation}\ftype{Condition Type}
  4161. \begincom{floating-point-inexact}\ftype{Condition Type}
  4162. \issue{FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89}
  4163. \label Class Precedence List::
  4164. \typeref{floating-point-inexact},
  4165. \typeref{arithmetic-error},
  4166. \typeref{error},
  4167. \typeref{serious-condition},
  4168. \typeref{condition},
  4169. \typeref{t}
  4170. \label Description::
  4171. \Thetype{floating-point-inexact} consists of
  4172. error conditions that occur because of certain
  4173. %!!! Barmar: Which?
  4174. floating point traps.
  4175. It is \term{implementation-dependent} whether floating point traps
  4176. occur, and whether or how they may be enabled or disabled. Therefore,
  4177. conforming code may establish handlers for this condition, but must not
  4178. depend on its being \term{signaled}.
  4179. \endissue{FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89}
  4180. \endcom%{floating-point-inexact}\ftype{Condition Type}
  4181. \begincom{floating-point-overflow}\ftype{Condition Type}
  4182. \label Class Precedence List::
  4183. \typeref{floating-point-overflow},
  4184. \typeref{arithmetic-error},
  4185. \typeref{error},
  4186. \typeref{serious-condition},
  4187. \typeref{condition},
  4188. \typeref{t}
  4189. \label Description::
  4190. \Thetype{floating-point-overflow} consists of error
  4191. conditions that occur because of floating-point overflow.
  4192. \endcom%{floating-point-overflow}\ftype{Condition Type}
  4193. \begincom{floating-point-underflow}\ftype{Condition Type}
  4194. \label Class Precedence List::
  4195. \typeref{floating-point-underflow},
  4196. \typeref{arithmetic-error},
  4197. \typeref{error},
  4198. \typeref{serious-condition},
  4199. \typeref{condition},
  4200. \typeref{t}
  4201. \label Description::
  4202. \Thetype{floating-point-underflow} consists of
  4203. error conditions that occur because of floating-point underflow.
  4204. \endcom%{floating-point-underflow}\ftype{Condition Type}