From: Svjatoslav Agejenko Date: Fri, 20 Feb 2026 17:46:30 +0000 (+0200) Subject: Expand documentation for Fifth language commands: added detailed descriptions, exampl... X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=cc1da096d795d1a0d2e3a8212531c2e72c397adf;p=fifth.git Expand documentation for Fifth language commands: added detailed descriptions, examples, and usage notes for new commands and existing features. --- diff --git a/doc/language.org b/doc/language.org index 3a8e6a6..82fba1b 100644 --- a/doc/language.org +++ b/doc/language.org @@ -30,371 +30,547 @@ like ordinary letters. * Fifth commands ** Compilation & miscellaneous +*** init ( -- ) -init module ( -- ) - First module, control is passed to on startup. Contains - initialization routines. Also it is the last core module. - All new modules on top of it comes as result of executing - external source files. +- Description :: First module, control is passed to on startup. Contains + initialization routines. Also it is the last core module. All new + modules on top of it comes as result of executing external source + files. -head ( -- ) compiles new dictionary entry without specifying - new module type. - ex: head myentry +*** head ( -- ) -: ( -- ) creates new code module -; ( -- ) ends module (immideate) - ex: : hello ." hi there" ; +- Description :: Compiles new dictionary entry without specifying new + module type. +- Example :: + : head myentry + +*** : ( -- ) + +- Description :: Creates new code module. + +*** ; ( -- ) + +- Description :: Ends module (immideate). +- Example :: + : : hello ." hi there" ; + +*** const ( n -- ) + +- Description :: Defines new constant. +- Example :: + : 2147483647 const max + +*** :i ( -- ) + +- Description :: Same as =:= but this module will be executed + immideately even in compile mode. +- Example :: + : :i ( 41 scan ; + +*** create ( -- ) + +- Description :: Same as =head=, but specify module type as data. +- Example :: + : create LotoResults 5 , 13 , 52 , 12 , 11 , 3 , + +*** allot ( n -- ) + +- Description :: Allocate *n* bytes in dictionary. +- Example :: + : create MyArray 100 allot + +*** " " ( -- ) + +- Description :: Compile string and its size into core. +- Example :: + : create Mystring " This is it's contects" + +*** str " ( -- ) + +- Description :: Just shorter way for defining strings. +- Example :: + : str Mystring This is it's contenc" + +*** var ( -- ) + +- Description :: Define new 32 bit variable. +- Example :: + : var result + +*** ' ( -- n ) + +- Description :: Return memory address of given entry. +- Example :: + : ' init -const ( n -- ) defines new constant. - ex: 2147483647 const max +*** forget ( -- ) -:i ( -- ) same as ":" but this module will be executed - immideately even in compile mode. - ex: :i ( 41 scan ; +- Description :: Erases from RAM given entry and all entries what was + defined after it. +- Example :: + : forget myprog + +*** [ ( -- ) + +- Description :: Set interpret mode (immideate). + +*** ] ( n -- ) + +- Description :: Set compile mode and compile top stack element in as + literal. Together =[ .... ]= combination provides good way to + compute some values only once, at compile time, rather than every + time while program is running. +- Example :: + : : calculate - [ 4 MyConst1 + MyConst2 * ] ; -create ( -- ) same as "head" , but specify module type as data. - ex: create LotoResults 5 , 13 , 52 , 12 , 11 , 3 , +*** defer ( -- ) -allot ( n -- ) allocate n bytes in dictionary. - ex: create MyArray 100 allot - -" " ( -- ) compile string and its size into core. - ex: create Mystring " This is it's contects" +- Description :: Creates new module, with jump instruction. Later + address where to jump can be modified by =is= command. This + provides method of forward referencing. So you can use modules what + not yet exist. -str " ( -- ) just shorter way for defining strings. - ex: str Mystring This is it's contenc" +*** is ( address1 address2 -- ) -var ( -- ) define new 32 bit variable. - ex: var result +- Description :: *address1* - where to jump, *address2* - address of + module created by =defer= command. +- Example :: + : defer dispver + : : run dispver ." running ..." ; + : ... whatever ... + : : (dispver ." Version 9.99 " ; + : ' (dispver ' dispver is -' ( -- n ) return memory address of given entry. - ex: ' init + Now if I type "run" on the screen appears: + : Version 9.99 running ... -forget ( -- ) erases from RAM given entry and all entries what was - defined after it. - ex: forget myprog +*** asc ( -- ) -[ ( -- ) set interpret mode (immideate) -] ( n -- ) set compile mode and compile top stack element - in as literal. Together [ .... ] cobination provides good - way to compute some values only once, at compile time, - rather than every time while program is running. - ex: : calculate - [ 4 MyConst1 + MyConst2 * ] ; +- Description :: Reads char ascii code and treats it as literal + (immideate). +- Example :: + : : BreakLine 30 do asc - emit loop ; -defer ( -- ) creates new module, with jump instruction. - Later address where to jump can be modified by "is" command. - This provides method of foward referencing. So you can use - modules what not jet exist. -is ( address1 address2 -- ) address1 - where to jump, address2 - - address of module created by defer command. - ex: defer dispver - : run dispver ." running ..." ; - ... whatever ... - : (dispver ." Version 9.99 " ; - ' (dispver ' dispver is + same as: + : : BreakLine 30 do 45 emit loop ; - Now if I type "run" on the screen appears: - Version 9.99 running ... +*** dyninc ( handle -- ) -asc ( -- ) reads char ascii code and treats it as literal. - (immideate) - ex: : BreakLine 30 do asc - emit loop ; - same as: - : BreakLine 30 do 45 emit loop ; +- Description :: Execute code in dynamic memory handle. Automatically + deallocates it when done. -dyninc ( handle -- ) execute code in dynamic memory handle. - automatically deallocates it when done. +*** include ( filenumber -- ) -include ( filenumber -- ) execute code in specified file. +- Description :: Execute code in specified file. -words ( -- ) display existing blocks in core. +*** words ( -- ) -bye ( -- ) exit from Fifth +- Description :: Display existing blocks in core. -fkey ( -- c ) - Read one byte from input stream. +*** bye ( -- ) -sadd ( c addr -- ) - Add one byte "c" to string located at "addr" and updates - string length. +- Description :: Exit from Fifth. -scan ( c -- ) - Read input stream and store it to pad until it finds c . - It ignores all "c" bytes until it finds any non "c" byte. - in other words: - c is: " - input stream: """"This is test !"aoeu idh - result: This is test ! +*** fkey ( -- c ) - Is useful for breaking text lines into words. +- Description :: Read one byte from input stream. -skey ( -- c ) - So called safe "fkey". Reads data from input stream - but converts characters with ASCII codes: 9 13 10 - to spaces. +*** sadd ( c addr -- ) -str=str? ( adr1 adr2 -- result ) - Compares string at "adr1" with string at "adr2", returns - true flag if they are equal or false if they are not. - true = -1 - false = 0 +- Description :: Add one byte *c* to string located at *addr* and + updates string length. -find ( -- addr ) - Searches whole dictionary for word in "pad". If found, - returns it address, if not, returns 0. +*** scan ( c -- ) + +- Description :: Read input stream and store it to =pad= until it + finds *c*. It ignores all *c* bytes until it finds any non *c* + byte. Is useful for breaking text lines into words. +- Example :: + : c is: " + : input stream: """"This is test !"aoeu idh + : result: This is test ! -execute ( -- ) - Execute word located in "pad". Depending on "mode". +*** skey ( -- c ) -dta ( addr -- DataAddr ) - Calculates address of dictionary entry data area, from - entry point. +- Description :: So called safe =fkey=. Reads data from input stream + but converts characters with ASCII codes: 9 13 10 to spaces. -2num ( -- num result ) - Attempt to convert string located in "pad" into numeric - value. If succeed returns number and true as result. - If not, returns whatever and false as result. +*** str=str? ( adr1 adr2 -- result ) -dadd ( addr length -- ) - Add to dictionary data located at "addr", with specified - length. +- Description :: Compares string at *adr1* with string at *adr2*, + returns true flag if they are equal or false if they are not. + true = -1, false = 0. -lit ( n -- ) - Act with number depending on "mode". When interpreting, - leaves it in stack. +*** find ( -- addr ) +- Description :: Searches whole dictionary for word in =pad=. If + found, returns its address, if not, returns 0. -incmod ( addr -- ) - Add to dictionary data located at "addr"+1 , length is taken - from "addr". +*** execute ( -- ) -here ( -- n ) - return "h" contents. - -mode var 8 bit - Holds input stream parser operation mode. - 0 = interpreting - 1 = compiling +- Description :: Execute word located in =pad=. Depending on =mode=. -pad var 128 bytes - Holds temprorary strings. +*** dta ( addr -- DataAddr ) -h var 32 bit - Pointer to free byte in memory, always at the end of the - dictionary. Each time when something is stored - by "c," command, pointer is incareased. +- Description :: Calculates address of dictionary entry data area, + from entry point. -lp var 32 bit - Pointer to last dictionary word. Each time when new word is - compiled or erased by "forget", this pointer is updated. +*** 2num ( -- num result ) -modulechk ( Dstr -- ) check if module is loaded, if not - immideately load it. +- Description :: Attempt to convert string located in =pad= into + numeric value. If succeed returns number and true as result. If + not, returns whatever and false as result. -ne ( entrydata entrytype -- ) Compile new dictionary entry. - It's name must be in "pad". +*** dadd ( addr length -- ) + +- Description :: Add to dictionary data located at *addr*, with + specified length. + +*** lit ( n -- ) + +- Description :: Act with number depending on =mode=. When + interpreting, leaves it in stack. + +*** incmod ( addr -- ) + +- Description :: Add to dictionary data located at *addr*+1, length + is taken from *addr*. + +*** here ( -- n ) + +- Description :: Return =h= contents. + +*** mode ( var, 8 bit ) + +- Description :: Holds input stream parser operation mode. 0 = + interpreting, 1 = compiling. + +*** pad ( var, 128 bytes ) + +- Description :: Holds temporary strings. + +*** h ( var, 32 bit ) + +- Description :: Pointer to free byte in memory, always at the end of + the dictionary. Each time when something is stored by =c,= command, + pointer is increased. + +*** lp ( var, 32 bit ) + +- Description :: Pointer to last dictionary word. Each time when new + word is compiled or erased by =forget=, this pointer is updated. + +*** modulechk ( Dstr -- ) + +- Description :: Check if module is loaded, if not immideately load it. + +*** ne ( entrydata entrytype -- ) + +- Description :: Compile new dictionary entry. Its name must be in + =pad=. ** Conditionals & control flow +*** if ( flag -- ) -if ( flag -- ) (immideate) - "if 1.. else 2.. then" or - "if 1.. then" construction. Conditional execution. - Performs "1.." if "flag" was true, - elseway performs "2.." if exist. Execution continues after - word "then". - ex: 1 if ." nonzero" else ." zero" then +- Description :: =if 1.. else 2.. then= or =if 1.. then= + construction. Conditional execution (immideate). Performs "1.." if + *flag* was true, elseway performs "2.." if exist. Execution + continues after word =then=. +- Example :: + : 1 if ." nonzero" else ." zero" then ->= ( n1 n2 -- result ) true if (n1 = n2) or (n1 > n2) - ex: 5 3 >= if ." first number is greater or equal" then +*** >= ( n1 n2 -- result ) -<= ( n1 n2 -- result ) true if (n1 = n2) or (n1 < n2) -= ( n1 n2 -- result ) true if n1 = n2 +- Description :: True if (n1 = n2) or (n1 > n2). +- Example :: + : 5 3 >= if ." first number is greater or equal" then + +*** <= ( n1 n2 -- result ) + +- Description :: True if (n1 = n2) or (n1 < n2). + +*** = ( n1 n2 -- result ) + +- Description :: True if n1 = n2. -do ( count -- ) (immideate) - "do .. loop" construction. Performs ".." "count" times. - In every step "count" is decareased until it is 0. - ex: : test 5 do i .d loop ; - result: 4 3 2 1 0 +*** do ( count -- ) -doexit ( -- ) exit from "do .. loop" +- Description :: =do .. loop= construction (immideate). Performs ".." + *count* times. In every step *count* is decreased until it is 0. +- Example :: + : : test 5 do i .d loop ; + result: 4 3 2 1 0 + +*** doexit ( -- ) + +- Description :: Exit from =do .. loop=. -for ( count top -- ) (immideate) - "for .. loop" construction. Performs ".." (top - count) times. - In every step "count" is incareased until it reaches "top" . - ex: : test 4 10 for i .d loop ; - result: 4 5 6 7 8 9 +*** for ( count top -- ) + +- Description :: =for .. loop= construction (immideate). Performs ".." + (top - count) times. In every step *count* is increased until it + reaches *top*. +- Example :: + : : test 4 10 for i .d loop ; + result: 4 5 6 7 8 9 -forexit ( -- ) exit from "for .. loop" +*** forexit ( -- ) -until ( -- ) (immideate) - "until .. loop" construction. Performs ".." until flag become - true. False by default. Top of return stack holds flag. +- Description :: Exit from =for .. loop=. -done ( -- ) exit from "until .. loop" +*** until ( -- ) + +- Description :: =until .. loop= construction (immideate). Performs + ".." until flag become true. False by default. Top of return stack + holds flag. + +*** done ( -- ) + +- Description :: Exit from =until .. loop=. ** Disk & file access +*** diskload ( FromDisk ToMem amount -- ) + +- Description :: Load specified amount of bytes from disk into memory. + +*** disksave ( FromMem ToDisk amount -- ) + +- Description :: Save specified amount of bytes from memory into disk. + +*** format ( -- ) + +- Description :: Erase all files. + +*** fsDfilesize@ ( handle -- size ) -diskload ( FromDisk ToMem amount -- ) - Load specified abount of bytes from disk into memory. +- Description :: Return size of opened file. -disksave ( FromMem ToDisk amount -- ) - save specified abount of bytes from memory into disk. +*** fsDcurloc@ ( handle -- location ) -format ( -- ) Erase all files. +- Description :: Return current location in file. -fsDfilesize@ ( handle -- size ) - Return size of opened file. +*** fsDupdated@ ( handle -- updated? ) -fsDcurloc@ ( handle -- location ) - Return current location in file. +- Description :: Return true if file was updated, ie. write operations + occurred. -fsDupdated@ ( handle -- updated? ) - Return true if file was updated, - ie. write operations occured. +*** fssave ( FromMem DestFileHandle amount -- ) -fssave ( FromMem DestFileHandle amount -- ) - Save data to file. +- Description :: Save data to file. -fsload ( SrcFileHandle ToMem amount -- ) - Load data from file. +*** fsload ( SrcFileHandle ToMem amount -- ) -fseof ( handle -- bytesLeft ) - Return amount of bytes left till end of file. - Useful before read operation. +- Description :: Load data from file. -fsls ( -- ) List all files and lists (directories,folders) - in current path. +*** fseof ( handle -- bytesLeft ) -fslsr ( -- ) Same as "fsls" but recursively scans also sub lists. +- Description :: Return amount of bytes left till end of file. Useful + before read operation. -fscl ( DynStrHand -- ) - Change list (path) +*** fsls ( -- ) -fscreate ( DynStrHand -- DescPnt ) - Create new file or list. Can create multiple lists at once. - ex: when creating: - "\listGAMES\listSTRATEGY\listSIMWORLD\5th-runme" - and only "\listGAMES\" already exist, then - "listSTRATEGY" and "listSIMWORLD" lists will be created, - and empty file "5th-runme" placed in there. +- Description :: List all files and lists (directories, folders) in + current path. -fsDsave ( DynHand DynStrHand -- ) - Create new file and save all data from dynamic memory - block to it. +*** fslsr ( -- ) -fsDload ( DynStr DynHand -- ) - Load whole file into dynamic memory block. +- Description :: Same as =fsls= but recursively scans also sub lists. -fsDloadnew ( DynStr -- DynHand ) - Load whole file into new dynamic memory block. +*** fscl ( DynStrHand -- ) + +- Description :: Change list (path). + +*** fscreate ( DynStrHand -- DescPnt ) + +- Description :: Create new file or list. Can create multiple lists at + once. +- Example :: + When creating: + : "\listGAMES\listSTRATEGY\listSIMWORLD\5th-runme" + and only =\listGAMES\= already exist, then =listSTRATEGY= and + =listSIMWORLD= lists will be created, and empty file =5th-runme= + placed in there. + +*** fsDsave ( DynHand DynStrHand -- ) + +- Description :: Create new file and save all data from dynamic memory + block to it. + +*** fsDload ( DynStr DynHand -- ) + +- Description :: Load whole file into dynamic memory block. + +*** fsDloadnew ( DynStr -- DynHand ) + +- Description :: Load whole file into new dynamic memory block. ** Dynamic memory +*** dynal ( size -- handle ) -dynal ( size -- handle ) - Allocate dynamic memory block and return it's handle. +- Description :: Allocate dynamic memory block and return its handle. -dynde ( handle -- ) - Deallocate dynamic memory block. +*** dynde ( handle -- ) -dynp ( handle -- addr ) - Returns pointer to memory where dynamic block - data begins. +- Description :: Deallocate dynamic memory block. -dyns ( handle -- size ) - Returns size of dynamic block. +*** dynp ( handle -- addr ) -dynresize ( NewSize handle -- ) - Nondestructively resize dynamic block. +- Description :: Returns pointer to memory where dynamic block data + begins. -dync@ ( addr handle ) - Read one byte from dynamic block. +*** dyns ( handle -- size ) -dync! ( byte addr dynhandle ) - Write one byte to dynamic block. +- Description :: Returns size of dynamic block. -dyn@ ( addr handle ) - Read 32 bit number from dynamic block. - Address will spacify, whitch number, not byte. +*** dynresize ( NewSize handle -- ) -dyn! ( 32BitNum addr dynhandle ) - Write 32 bit number to dynamic block. - Address will spacify, whitch number, not byte. +- Description :: Nondestructively resize dynamic block. -dyncon ( size "name" -- ) - Allocate dynamic block with specified size, and - create constant honding its handle. - ex: 100 dyncon MyNewBlock +*** dync@ ( addr handle ) + +- Description :: Read one byte from dynamic block. + +*** dync! ( byte addr dynhandle ) + +- Description :: Write one byte to dynamic block. + +*** dyn@ ( addr handle ) + +- Description :: Read 32 bit number from dynamic block. Address will + specify which number, not byte. + +*** dyn! ( 32BitNum addr dynhandle ) + +- Description :: Write 32 bit number to dynamic block. Address will + specify which number, not byte. + +*** dyncon ( size "name" -- ) + +- Description :: Allocate dynamic block with specified size, and + create constant holding its handle. +- Example :: + : 100 dyncon MyNewBlock -dyn. ( handle -- ) - Write contenc of dynamic memory block to screen. +*** dyn. ( handle -- ) + +- Description :: Write content of dynamic memory block to screen. ** Graphics and text +*** . ( n -- ) + +- Description :: Print number on screen. + +*** d. ( n -- ) + +- Description :: Print number on screen in decimal. + +*** ? ( addr -- ) + +- Description :: Print 32 bit value located at *addr*. + +*** ." " ( -- ) + +- Description :: Print string into screen. Immideately compiles. +- Example :: + : : greeting ." Hello, World" ; + +*** tab. ( -- ) + +- Description :: Print tabulator. + +*** calccol ( b g r -- c ) + +- Description :: Calculate color what best matches given Blue Green & + Red values. Values must be in range 0 - 255. + +*** imgalloc ( xsize ysize -- imgbuf ) + +- Description :: Allocate image buffer for specified size. + +*** imgsize ( imgbuf -- ) + +- Description :: Print on the screen X & Y size of image buffer. + +*** point ( x y imgbuf -- addr ) + +- Description :: Returns memory address for specified pixel. -. ( n -- ) print number on screen +*** pset ( color x y imgbuf -- ) -d. ( n -- ) print number on screen in decimal +- Description :: Set graphic point. -? ( addr -- ) print 32 bit value located at addr. +*** boxf ( x1 x2 y1 y2 imgbuf color -- ) -." " ( -- ) print string into screen. Immideately - compiles. - ex: : greeting ." Hello, World" ; +- Description :: Draw filled box. -tab. ( -- ) print tabulator +*** cls ( imgbuf -- ) -calccol ( b g r -- c ) calculate color what best matches given - Blue Green & Red values. Values must be in range 0 - 255. +- Description :: Clear image buffer. -imgalloc ( xsize ysize -- imgbuf ) allocate image buffer for - specified size. +*** setpal ( b g r color -- ) -imgsize ( imgbuf -- ) print on the screen X & Y size of image - buffer. +- Description :: Set palette value for specified color. Values must be + in range 0 - 63. -point ( x y imgbuf -- addr ) returns memory address for specified - pixel. +*** putchar ( char color x y imgbuf -- ) -pset ( color x y imgbuf -- ) set graphic point +- Description :: Put graphic character in imagebuffer to specified (x + & y) location. -boxf ( x1 x2 y1 y2 imgbuf color -- ) draw filled box +*** scroll ( x y imgbuf -- ) -cls ( imgbuf -- ) clear image buffer +- Description :: Scroll in imgbuf. -setpal ( b g r color -- ) set palette value for specified color. - values bust be in size 0 - 63. +*** scrollf ( color x y screen -- ) -putchar ( char color x y imgbuf -- ) put graphic character in - imagebuffer to specified (x & y) location. +- Description :: Scroll and fill empty space with given color. -scroll ( x y imgbuf -- ) scroll in imgbuf. +*** at! ( x y -- ) -scrollf ( color x y screen -- ) scroll and fill empty space with - given color. +- Description :: Set cursor location. -at! ( x y -- ) set cursor location -curc! ( color -- ) set text color -curb! ( solor -- ) set backround color +*** curc! ( color -- ) -colnorm ( -- ) set text color to normal -colneg ( -- ) set text color to negative (selected) +- Description :: Set text color. -dyntype ( dynhandle -- ) display contenc of dynamic memory on screen -fsdisp ( file -- ) clear screen, display file, and wait for key +*** curb! ( color -- ) -type ( addr length -- ) - Types on the screen string, from memory at addr and - specified length. +- Description :: Set background color. -write ( addr -- ) - Types on the screen string, from memory at "addr"+1 - length is taken from "addr" . +*** colnorm ( -- ) -screen const 32 bit - Holds handle of screen buffer. +- Description :: Set text color to normal. -copyscreen ( SrcImgHandle DestImgHandle -- ) copy contenc of source - image to destination image. Source and destination images - must have same size. +*** colneg ( -- ) + +- Description :: Set text color to negative (selected). + +*** dyntype ( dynhandle -- ) + +- Description :: Display content of dynamic memory on screen. + +*** fsdisp ( file -- ) + +- Description :: Clear screen, display file, and wait for key. + +*** type ( addr length -- ) + +- Description :: Types on the screen string, from memory at *addr* + and specified length. + +*** write ( addr -- ) + +- Description :: Types on the screen string, from memory at *addr*+1, + length is taken from *addr*. + +*** screen ( const, 32 bit ) + +- Description :: Holds handle of screen buffer. + +*** copyscreen ( SrcImgHandle DestImgHandle -- ) + +- Description :: Copy content of source image to destination image. + Source and destination images must have same size. ** Math, memory & stack manipulation *** off ( n -- ) @@ -409,7 +585,6 @@ copyscreen ( SrcImgHandle DestImgHandle -- ) copy contenc of source - Example :: : MyVariable on - *** 2dup ( n1 n2 -- n1 n2 n1 n2 ) *** 2drop ( n1 n2 -- ) *** nip ( n1 n2 -- n2 ) @@ -509,6 +684,7 @@ copyscreen ( SrcImgHandle DestImgHandle -- ) copy contenc of source - Description :: Returns absolute value of *n*. ** Dynamic & static strings + Fifth supports both static and dynamic strings. Static strings must have predefined space reserved, and string mustn't exceed this length. They manipulation is faster. But they use more memory. Static @@ -521,114 +697,139 @@ blocks, so dynamic block handle is used to refer to this string. Both types of strings are stored in the way, where first (0th) byte holds current string length, following bytes are string itself. +*** Dstral ( -- handle ) +- Description :: Allocate new dynamic string. -Dynamic: +*** Dstrlen ( handle -- length ) -Dstral ( -- handle ) - Allocate new string. +- Description :: Return string length. -Dstrlen ( handle -- length ) - Return string length. +*** c+Dstr ( chr handle -- ) -c+Dstr ( chr handle -- ) - Add one byte to end of the string. +- Description :: Add one byte to end of the string. -c+lDstr ( chr handle -- ) - Add one byte to left side (beginning) of the string. +*** c+lDstr ( chr handle -- ) -Dstr. ( handle -- ) - Write contec of string into screen. +- Description :: Add one byte to left side (beginning) of the string. -Dstrsure ( size Dstr -- ) - Makes sure that at least rquested - "size" (amount of characters) is allocated for given - dynamic string. +*** Dstr. ( handle -- ) -Dstr2str ( handle address -- ) - Copy dyamic string into static memory space. +- Description :: Write content of string into screen. -str2Dstr ( address handle -- ) - Copy static string into dyamic string. +*** Dstrsure ( size Dstr -- ) -Dstr+str ( Dstr addr -- ) - Add contenc of dynamic string to static string. +- Description :: Makes sure that at least requested *size* (amount of + characters) is allocated for given dynamic string. -D" any string" ( -- Dstr ) - Moves specified string into dynamic string called "defDstr". +*** Dstr2str ( handle address -- ) -D> any_string ( -- Dstr ) - Moves specified string into dynamic string called "defDstr". - Space marks end of string! +- Description :: Copy dynamic string into static memory space. -D>2 any_string ( -- Dstr ) - Moves specified string into dynamic string called "defDstr2". - Space marks end of string! +*** str2Dstr ( address handle -- ) -Dstr+Dstr ( Dstr1 Dstr2 -- ) - Adds "Dstr1" to "Dstr2" and places result into "Dstr2". +- Description :: Copy static string into dynamic string. -Dstrclear ( Dstr -- ) - Clears contenc of dynamic string. +*** Dstr+str ( Dstr addr -- ) -Dstr2Dstr ( Dstr1 Dstr2 -- ) - Moves "Dstr1" to "Dstr2". -Dstr ( data" name -- ) - Creates new dynamic string and moves specified data into it. - Then creates new constant with given "name" holding created - dynamic string handle. +- Description :: Add content of dynamic string to static string. - ex: Dstr Hello, my name is Sven!" message \ creates it - message Dstr. \ tests it +*** D" any string" ( -- Dstr ) -Dstrlscan ( char Dstr -- loc ) - Searches dynamic string for "char", from left to right, - returns first found "char" location in string, or 0, - if not found. +- Description :: Moves specified string into dynamic string called + =defDstr=. -Dstrrscan ( char Dstr -- loc ) - Searches dynamic string for "char", from right to left, - returns first found "char" location in string, or 0, - if not found. +*** D> any_string ( -- Dstr ) -Dstrlscane ( char Dstr -- loc ) - Same as "Dstrlscan" buf returns string length+1 as location. -ÿ -Dstrleft ( amo Dstr -- ) - Only specified amount of characters from left remains - in dynamic string. ie. cut right part out. +- Description :: Moves specified string into dynamic string called + =defDstr=. Space marks end of string! -Dstrright ( amo Dstr -- ) - Only specified amount of characters from right remains - in dynamic string. ie. cut left part out. +*** D>2 any_string ( -- Dstr ) -Dstrcutl ( amo Dstr -- ) - Cut specified amount of characters from left of dynamic - string out. +- Description :: Moves specified string into dynamic string called + =defDstr2=. Space marks end of string! -Dstrsp ( char Dstr1 Dstr2 -- ) - Separate dynamic string in Dstr1 into two parts, - using "char" as separator. First part will be stored in - "Dstr2", second part in "Dstr1". - ex: asc \ \ ..separator - D> listF\listLIB\5TH_DRVMOUSE \ ..separate from - defDstr2 \ ..place result in - Dstrsp \ separation command - defDstr Dstr. \ will be: listLIB\5TH_DRVMOUSE - defDstr2 Dstr. \ will be: listF +*** Dstr+Dstr ( Dstr1 Dstr2 -- ) -Dv ( addr -- ) - Allocates empty dynamic string, and places it's handle - into given address. +- Description :: Adds *Dstr1* to *Dstr2* and places result into + *Dstr2*. -Df ( addr -- ) - Reads dynamic string handle from given address and - deallocates (frees) it. +*** Dstrclear ( Dstr -- ) -ex: var mystring1 - : testmodule - mystring1 Dv \ allocates string - - +- Description :: Clears content of dynamic string. + +*** Dstr2Dstr ( Dstr1 Dstr2 -- ) + +- Description :: Moves *Dstr1* to *Dstr2*. + +*** Dstr ( data" name -- ) + +- Description :: Creates new dynamic string and moves specified data + into it. Then creates new constant with given *name* holding + created dynamic string handle. +- Example :: + : Dstr Hello, my name is Sven!" message \ creates it + : message Dstr. \ tests it - mystring1 Df ; \ deallocates it again when no longer needed. +*** Dstrlscan ( char Dstr -- loc ) + +- Description :: Searches dynamic string for *char*, from left to + right, returns first found *char* location in string, or 0, if not + found. + +*** Dstrrscan ( char Dstr -- loc ) + +- Description :: Searches dynamic string for *char*, from right to + left, returns first found *char* location in string, or 0, if not + found. + +*** Dstrlscane ( char Dstr -- loc ) + +- Description :: Same as =Dstrlscan= but returns string length+1 as + location. + +*** Dstrleft ( amo Dstr -- ) + +- Description :: Only specified amount of characters from left remains + in dynamic string. ie. cut right part out. + +*** Dstrright ( amo Dstr -- ) + +- Description :: Only specified amount of characters from right + remains in dynamic string. ie. cut left part out. + +*** Dstrcutl ( amo Dstr -- ) + +- Description :: Cut specified amount of characters from left of + dynamic string out. + +*** Dstrsp ( char Dstr1 Dstr2 -- ) + +- Description :: Separate dynamic string in *Dstr1* into two parts, + using *char* as separator. First part will be stored in *Dstr2*, + second part in *Dstr1*. +- Example :: + : asc \ \ ..separator + : D> listF\listLIB\5TH_DRVMOUSE \ ..separate from + : defDstr2 \ ..place result in + : Dstrsp \ separation command + : defDstr Dstr. \ will be: listLIB\5TH_DRVMOUSE + : defDstr2 Dstr. \ will be: listF + +*** Dv ( addr -- ) + +- Description :: Allocates empty dynamic string, and places its + handle into given address. + +*** Df ( addr -- ) + +- Description :: Reads dynamic string handle from given address and + deallocates (frees) it. +- Example :: + : var mystring1 + : : testmodule + : mystring1 Dv \ allocates string + : + : + : + : mystring1 Df ; \ deallocates it again when no longer needed.