--- gforth/prim 1998/12/20 23:17:55 1.20 +++ gforth/prim 1999/03/29 22:52:28 1.27 @@ -115,12 +115,13 @@ INC_IP(1); r> dup @ swap cell+ >r ; execute xt -- core +""Perform the semantics represented by the execution token, @var{xt}."" ip=IP; IF_TOS(TOS = sp[0]); EXEC(xt); perform a_addr -- gforth -""equivalent to @code{@ execute}"" +""Equivalent to @code{@ execute}."" /* and pfe */ ip=IP; IF_TOS(TOS = sp[0]); @@ -140,8 +141,7 @@ goto branch; branch -- gforth branch: -ip = (Xt *)(((Cell)IP)+(Cell)NEXT_INST); -NEXT_P0; +SET_IP((Xt *)(((Cell)IP)+(Cell)NEXT_INST)); : r> dup @ + >r ; @@ -149,8 +149,7 @@ NEXT_P0; \ this is non-syntactical: code must open a brace that is closed by the macro define(condbranch, $1 $2 -$3 ip = (Xt *)(((Cell)IP)+(Cell)NEXT_INST); - NEXT_P0; +$3 SET_IP((Xt *)(((Cell)IP)+(Cell)NEXT_INST)); NEXT; } else @@ -188,8 +187,7 @@ if (f==0) { if (f==0) { sp++; IF_TOS(TOS = sp[0]); - ip = (Xt *)(((Cell)IP)+(Cell)NEXT_INST); - NEXT_P0; + SET_IP((Xt *)(((Cell)IP)+(Cell)NEXT_INST)); NEXT; } else @@ -203,8 +201,7 @@ few cycles in that case, but is easy to invocation */ if (f!=0) { sp--; - ip = (Xt *)(((Cell)IP)+(Cell)NEXT_INST); - NEXT_P0; + SET_IP((Xt *)(((Cell)IP)+(Cell)NEXT_INST)); NEXT; } else @@ -443,18 +440,27 @@ n = rp[4]; \ digit is high-level: 0/0% move c_from c_to ucount -- core +"" If @var{ucount}>0, copy the contents of @var{ucount} address units +at @var{c-from} to @var{c-to}. @code{move} chooses its copy direction +to avoid problems when @var{c-from}, @var{c-to} overlap."" memmove(c_to,c_from,ucount); /* make an Ifdef for bsd and others? */ : >r 2dup u< IF r> cmove> ELSE r> cmove THEN ; cmove c_from c_to u -- string +"" If @var{u}>0, copy the contents of @var{ucount} characters from +data space at @var{c-from} to @var{c-to}. The copy proceeds @code{char}-by-@code{char} +from low address to high address."" while (u-- > 0) *c_to++ = *c_from++; : bounds ?DO dup c@ I c! 1+ LOOP drop ; cmove> c_from c_to u -- string c_move_up +"" If @var{u}>0, copy the contents of @var{ucount} characters from +data space at @var{c-from} to @var{c-to}. The copy proceeds @code{char}-by-@code{char} +from high address to low address."" while (u-- > 0) c_to[u] = c_from[u]; : @@ -463,16 +469,18 @@ while (u-- > 0) DO 1- dup c@ I c! -1 +LOOP drop ; fill c_addr u c -- core +"" If @var{u}>0, store character @var{c} in each of @var{u} consecutive +@code{char} addresses in memory, starting at address @var{c-addr}."" memset(c_addr,c,u); : -rot bounds ?DO dup I c! LOOP drop ; compare c_addr1 u1 c_addr2 u2 -- n string -""Compare the strings lexicographically. If they are equal, n is 0; if -the first string is smaller, n is -1; if the first string is larger, n +""Compare two strings lexicographically. If they are equal, @var{n} is 0; if +the first string is smaller, @var{n} is -1; if the first string is larger, @var{n} is 1. Currently this is based on the machine's character -comparison. In the future, this may change to considering the current +comparison. In the future, this may change to consider the current locale and its collation order."" n = memcmp(c_addr1, c_addr2, u10) dup 0< IF drop -1 ELSE 0> 1 and THEN ; toupper c1 -- c2 gforth +""If @var{c1} is a lower-case character (in the current locale), @var{c2} +is the equivalent upper-case character. All other characters are unchanged."" c2 = toupper(c1); : dup [char] a - [ char z char a - 1 + ] Literal u< bl and - ; @@ -522,6 +532,8 @@ else if (n>0) ELSE c@ toupper I c@ toupper - unloop THEN -text-flag ; -trailing c_addr u1 -- c_addr u2 string dash_trailing +""Adjust the string specified by @var{c-addr, u1} to remove all trailing +spaces. @var{u2} is the length of the modified string."" u2 = u1; while (u2>0 && c_addr[u2-1] == ' ') u2--; @@ -530,6 +542,8 @@ while (u2>0 && c_addr[u2-1] == ' ') dup 0= UNTIL ELSE 1+ THEN ; /string c_addr1 u1 n -- c_addr2 u2 string slash_string +""Adjust the string specified by @var{c-addr1, u1} to remove @var{n} +characters from the start of the string."" c_addr2 = c_addr1+n; u2 = u1-n; : @@ -627,7 +641,7 @@ n2 = n1>>1; LOOP nip ; fm/mod d1 n1 -- n2 n3 core f_m_slash_mod -""floored division: d1 = n3*n1+n2, n1>n2>=0 or 0>=n2>n1"" +""Floored division: @var{d1} = @var{n3}*@var{n1}+@var{n2}, @var{n1}>@var{n2}>=0 or 0>=@var{n2}>@var{n1}."" #ifdef BUGGY_LONG_LONG DCell r = fmdiv(d1,n1); n2=r.hi; @@ -649,7 +663,7 @@ if (1%-3>0 && (d1<0) != (n1<0) && n2!=0) r> 0< IF swap negate swap THEN ; sm/rem d1 n1 -- n2 n3 core s_m_slash_rem -""symmetric division: d1 = n3*n1+n2, sign(n2)=sign(d1) or 0"" +""Symmetric division: @var{d1} = @var{n3}*@var{n1}+@var{n2}, sign(@var{n2})=sign(@var{d1}) or 0."" #ifdef BUGGY_LONG_LONG DCell r = smdiv(d1,n1); n2=r.hi; @@ -918,17 +932,17 @@ f = FLAG(u1-u2 < u3-u2); : over - >r - r> u< ; -sp@ -- a_addr gforth spat +sp@ -- a_addr gforth sp_fetch a_addr = sp+1; -sp! a_addr -- gforth spstore +sp! a_addr -- gforth sp_store sp = a_addr; /* works with and without TOS caching */ -rp@ -- a_addr gforth rpat +rp@ -- a_addr gforth rp_fetch a_addr = rp; -rp! a_addr -- gforth rpstore +rp! a_addr -- gforth rp_store rp = a_addr; \+floating @@ -942,8 +956,8 @@ fp = f_addr; \+ ;s -- gforth semis -ip = (Xt *)(*rp++); -NEXT_P0; +""The primitive compiled by @code{EXIT}."" +SET_IP((Xt *)(*rp++)); >r w -- core to_r *--rp = w; @@ -1079,7 +1093,7 @@ w = *a_addr; : tuck @ + swap ! ; -c@ c_addr -- c core cfetch +c@ c_addr -- c core c_fetch c = *c_addr; : [ bigendian [IF] ] @@ -1104,7 +1118,7 @@ c = *c_addr; ; : 8>> 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ ; -c! c c_addr -- core cstore +c! c c_addr -- core c_store *c_addr = c; : [ bigendian [IF] ] @@ -1171,6 +1185,8 @@ n2 = n1 * sizeof(Char); ; count c_addr1 -- c_addr2 u core +"" If @var{c-add1} is the address of a counted string return the length of +the string, @var{u}, and the address of its first character, @var{c-addr2}."" u = *c_addr1; c_addr2 = c_addr1+1; : @@ -1310,45 +1326,45 @@ a_addr = PFA(xt); 2 cells + ; >code-address xt -- c_addr gforth to_code_address -""c_addr is the code address of the word xt"" +""@var{c-addr} is the code address of the word @var{xt}."" /* !! This behaves installation-dependently for DOES-words */ c_addr = (Address)CODE_ADDRESS(xt); : @ ; >does-code xt -- a_addr gforth to_does_code -""If xt ist the execution token of a defining-word-defined word, -a_addr is the start of the Forth code after the DOES>; -Otherwise a_addr is 0."" +""If @var{xt} is the execution token of a defining-word-defined word, +@var{a-addr} is the start of the Forth code after the @code{DOES>}; +Otherwise @var{a-addr} is 0."" a_addr = (Cell *)DOES_CODE(xt); : cell+ @ ; code-address! c_addr xt -- gforth code_address_store -""Creates a code field with code address c_addr at xt"" +""Create a code field with code address @var{c-addr} at @var{xt}."" MAKE_CF(xt, c_addr); CACHE_FLUSH(xt,(size_t)PFA(0)); : ! ; does-code! a_addr xt -- gforth does_code_store -""creates a code field at xt for a defining-word-defined word; a_addr -is the start of the Forth code after DOES>"" +""Create a code field at @var{xt} for a defining-word-defined word; @var{a-addr} +is the start of the Forth code after @code{DOES>}."" MAKE_DOES_CF(xt, a_addr); CACHE_FLUSH(xt,(size_t)PFA(0)); : dodoes: over ! cell+ ! ; does-handler! a_addr -- gforth does_handler_store -""creates a DOES>-handler at address a_addr. a_addr usually points -just behind a DOES>."" +""Create a @code{DOES>}-handler at address @var{a-addr}. Usually, @var{a-addr} points +just behind a @code{DOES>}."" MAKE_DOES_HANDLER(a_addr); CACHE_FLUSH((caddr_t)a_addr,DOES_HANDLER_SIZE); : drop ; /does-handler -- n gforth slash_does_handler -""the size of a does-handler (includes possible padding)"" +""The size of a @code{DOES>}-handler (includes possible padding)."" /* !! a constant or environmental query might be better */ n = DOES_HANDLER_SIZE; : @@ -1406,7 +1422,7 @@ ucols=cols; flush-icache c_addr u -- gforth flush_icache ""Make sure that the instruction cache of the processor (if there is -one) does not contain stale data at @var{c_addr} and @var{u} bytes +one) does not contain stale data at @var{c-addr} and @var{u} bytes afterwards. @code{END-CODE} performs a @code{flush-icache} automatically. Caveat: @code{flush-icache} might not work on your installation; this is usually the case if direct threading is not @@ -1432,6 +1448,10 @@ if (old_tp) #endif getenv c_addr1 u1 -- c_addr2 u2 gforth +""The string @var{c-addr1 u1} specifies an environment variable. The string @var{c-addr2 u2} +is the host operating system's expansion of that environment variable. If the +environment variable does not exist, @var{c-addr2 u2} specifies a string 0 characters +in length."" c_addr2 = getenv(cstr(c_addr1,u1,1)); u2 = (c_addr2 == NULL ? 0 : strlen(c_addr2)); @@ -1463,19 +1483,31 @@ timeout.tv_usec=1000*(n%1000); (void)select(0,0,0,0,&timeout); allocate u -- a_addr wior memory +""Allocate @var{u} address units of contiguous data space. The initial +contents of the data space is undefined. If the allocation is successful, +@var{a-addr} is the start address of the allocated region and @var{wior} +is 0. If the allocation fails, @var{a-addr} is undefined and @var{wior} +is an implementation-defined I/O result code."" a_addr = (Cell *)malloc(u?u:1); wior = IOR(a_addr==NULL); free a_addr -- wior memory +""Return the region of data space starting at @var{a-addr} to the system. +The regon must originally have been obtained using @code{allocate} or +@code{resize}. If the operational is successful, @var{wior} is 0. +If the operation fails, @var{wior} is an implementation-defined +I/O result code."" free(a_addr); wior = 0; resize a_addr1 u -- a_addr2 wior memory -""Change the size of the allocated area at @i{a_addr1} to @i{u} +""Change the size of the allocated area at @i{a-addr1} to @i{u} address units, possibly moving the contents to a different -area. @i{a_addr2} is the address of the resulting area. If -@code{a_addr1} is 0, Gforth's (but not the standard) @code{resize} -@code{allocate}s @i{u} address units."" +area. @i{a-addr2} is the address of the resulting area. +If the operational is successful, @var{wior} is 0. +If the operation fails, @var{wior} is an implementation-defined +I/O result code. If @i{a-addr1} is 0, Gforth's (but not the standard) +@code{resize} @code{allocate}s @i{u} address units."" /* the following check is not necessary on most OSs, but it is needed on SunOS 4.1.2. */ if (a_addr1==NULL) @@ -1513,26 +1545,26 @@ IF_FTOS(FTOS=fp[0]); close-file wfileid -- wior file close_file wior = IOR(fclose((FILE *)wfileid)==EOF); -open-file c_addr u ntype -- w2 wior file open_file -w2 = (Cell)fopen(tilde_cstr(c_addr, u, 1), fileattr[ntype]); +open-file c_addr u ntype -- wfileid wior file open_file +wfileid = (Cell)fopen(tilde_cstr(c_addr, u, 1), fileattr[ntype]); #if defined(GO32) && defined(MSDOS) -if(w2 && !(ntype & 1)) - setbuf((FILE*)w2, NULL); +if(wfileid && !(ntype & 1)) + setbuf((FILE*)wfileid, NULL); #endif -wior = IOR(w2 == 0); +wior = IOR(wfileid == 0); -create-file c_addr u ntype -- w2 wior file create_file +create-file c_addr u ntype -- wfileid wior file create_file Cell fd; fd = open(tilde_cstr(c_addr, u, 1), O_CREAT|O_TRUNC|ufileattr[ntype], 0666); if (fd != -1) { - w2 = (Cell)fdopen(fd, fileattr[ntype]); + wfileid = (Cell)fdopen(fd, fileattr[ntype]); #if defined(GO32) && defined(MSDOS) - if(w2 && !(ntype & 1)) - setbuf((FILE*)w2, NULL); + if(wfileid && !(ntype & 1)) + setbuf((FILE*)wfileid, NULL); #endif - wior = IOR(w2 == 0); + wior = IOR(wfileid == 0); } else { - w2 = 0; + wfileid = 0; wior = IOR(1); } @@ -1540,7 +1572,7 @@ delete-file c_addr u -- wior file delet wior = IOR(unlink(tilde_cstr(c_addr, u, 1))==-1); rename-file c_addr1 u1 c_addr2 u2 -- wior file-ext rename_file -""rename file c_addr1 u1 to new name c_addr2 u2"" +""Rename file @var{c_addr1 u1} to new name @var{c_addr2 u2}"" char *s1=tilde_cstr(c_addr2, u2, 1); wior = IOR(rename(tilde_cstr(c_addr1, u1, 0), s1)==-1); @@ -1665,7 +1697,7 @@ r = d; f>d r -- d float f_to_d #ifdef BUGGY_LONG_LONG -d.hi = ldexp(r,-CELL_BITS) - (r<0); +d.hi = ldexp(r,-(int)(CELL_BITS)) - (r<0); d.lo = r-ldexp((Float)d.hi,CELL_BITS); #else d = r; @@ -1718,7 +1750,7 @@ f/ r1 r2 -- r3 float f_slash r3 = r1/r2; f** r1 r2 -- r3 float-ext f_star_star -""@i{r3} is @i{r1} raised to the @i{r2}th power"" +""@i{r3} is @i{r1} raised to the @i{r2}th power."" r3 = pow(r1,r2); fnegate r1 -- r2 float @@ -1745,12 +1777,12 @@ floats n1 -- n2 float n2 = n1*sizeof(Float); floor r1 -- r2 float -""round towards the next smaller integral value, i.e., round toward negative infinity"" +""Round towards the next smaller integral value, i.e., round toward negative infinity."" /* !! unclear wording */ r2 = floor(r1); fround r1 -- r2 float -""round to the nearest integral value"" +""Round to the nearest integral value."" /* !! unclear wording */ #ifdef HAVE_RINT r2 = rint(r1); @@ -1778,15 +1810,21 @@ int decpt; sig=ecvt(r, u, &decpt, &flag); n=(r==0 ? 1 : decpt); f1=FLAG(flag!=0); -f2=FLAG(isdigit(sig[0])!=0); +f2=FLAG(isdigit((unsigned)(sig[0]))!=0); memmove(c_addr,sig,u); >float c_addr u -- flag float to_float +""Attempt to convert the character string @var{c-addr u} to +internal floating-point representation. If the string +represents a valid floating-point number @var{r} is placed +on the floating-point stack and @var{flag} is true. Otherwise, +@var{flag} is false. A string of blanks is a special case +and represents the flotaing-point number 0."" /* real signature: c_addr u -- r t / f */ Float r; char *number=cstr(c_addr, u, 1); char *endconv; -while(isspace(number[--u]) && u>0); +while(isspace((unsigned)(number[--u])) && u>0); switch(number[u]) { case 'd': @@ -1828,7 +1866,7 @@ fatan r1 -- r2 float-ext r2 = atan(r1); fatan2 r1 r2 -- r3 float-ext -""@i{r1/r2}=tan@i{r3}. The standard does not require, but probably +""@i{r1/r2}=tan(@i{r3}). ANS Forth does not require, but probably intends this to be the inverse of @code{fsincos}. In gforth it is."" r3 = atan2(r1,r2); @@ -1868,7 +1906,7 @@ r2 = log(r1+1.); #endif flog r1 -- r2 float-ext -""the decimal logarithm"" +""The decimal logarithm."" r2 = log10(r1); falog r1 -- r2 float-ext