doc/commands/string.txt

   1                         Dynamic & static strings  \r
   2                         ------------------------\r
   3 \r
   4 Fifth supports both static and dynamic strings.\r
   5 Static strings must have predefined space reserved,\r
   6 and string mustn't exceed this length. They manipulation is\r
   7 faster. But they use more memory. Static string memory address is used\r
   8 to refer to the string.\r
   9 \r
  10 Dynamic strings can have at any time length form 0 to 0FFh,\r
  11 They take up only memory they currently need. They are held\r
  12 in dynamic memory blocks, so dynamic block handle is used to refer\r
  13 to this string.\r
  14 \r
  15 Both types of strings are stored in the way, where first (0th)\r
  16 byte holds current string length, following bytes are string itself.\r
  17 \r
  18 Dynamic:\r
  19 \r
  20 Dstral ( -- handle )\r
  21                 Allocate new string.\r
  22 \r
  23 Dstrlen ( handle -- length )\r
  24                 Return string length.\r
  25 \r
  26 c+Dstr ( chr handle -- )\r
  27                 Add one byte to end of the string.\r
  28 \r
  29 c+lDstr ( chr handle -- )\r
  30                 Add one byte to left side (beginning) of the string.\r
  31 \r
  32 Dstr. ( handle -- )\r
  33                 Write contec of string into screen.\r
  34 \r
  35 Dstrsure ( size Dstr -- )\r
  36                 Makes sure that at least rquested\r
  37                 "size" (amount of characters) is allocated for given\r
  38                 dynamic string.\r
  39 \r
  40 Dstr2str ( handle address -- )\r
  41                 Copy dyamic string into static memory space.\r
  42 \r
  43 str2Dstr ( address handle -- )\r
  44                 Copy static string into dyamic string.\r
  45 \r
  46 Dstr+str ( Dstr addr -- )\r
  47                 Add contenc of dynamic string to static string.\r
  48 \r
  49 D" any string" ( -- Dstr )\r
  50                 Moves specified string into dynamic string called "defDstr".\r
  51 \r
  52 D> any_string ( -- Dstr )\r
  53                 Moves specified string into dynamic string called "defDstr".\r
  54                 Space marks end of string!\r
  55 \r
  56 D>2 any_string ( -- Dstr )\r
  57                 Moves specified string into dynamic string called "defDstr2".\r
  58                 Space marks end of string!\r
  59 \r
  60 Dstr+Dstr ( Dstr1 Dstr2 -- )\r
  61                 Adds "Dstr1" to "Dstr2" and places result into "Dstr2". \r
  62 \r
  63 Dstrclear ( Dstr -- )\r
  64                 Clears contenc of dynamic string.\r
  65 \r
  66 Dstr2Dstr ( Dstr1 Dstr2 -- )\r
  67                 Moves "Dstr1" to "Dstr2".\r
  68 Dstr ( data" name -- )\r
  69                 Creates new dynamic string and moves specified data into it.\r
  70                 Then creates new constant with given "name" holding created\r
  71                 dynamic string handle.\r
  72 \r
  73                 ex: Dstr Hello, my name is Sven!" message      \ creates it\r
  74                     message Dstr.                              \ tests it\r
  75 \r
  76 Dstrlscan ( char Dstr -- loc )\r
  77                 Searches dynamic string for "char", from left to right,\r
  78                 returns first found "char" location in string, or 0,\r
  79                 if not found.\r
  80 \r
  81 Dstrrscan ( char Dstr -- loc )\r
  82                 Searches dynamic string for "char", from right to left,\r
  83                 returns first found "char" location in string, or 0,\r
  84                 if not found.\r
  85 \r
  86 Dstrlscane ( char Dstr -- loc )\r
  87                 Same as "Dstrlscan" buf returns string length+1 as location.\r
  88 ÿ\r
  89 Dstrleft ( amo Dstr -- )\r
  90                 Only specified amount of characters from left remains\r
  91                 in dynamic string. ie. cut right part out.\r
  92 \r
  93 Dstrright ( amo Dstr -- )\r
  94                 Only specified amount of characters from right remains\r
  95                 in dynamic string. ie. cut left part out.\r
  96 \r
  97 Dstrcutl ( amo Dstr -- )\r
  98                 Cut specified amount of characters from left of dynamic\r
  99                 string out.\r
 100 \r
 101 Dstrsp ( char Dstr1 Dstr2 -- )\r
 102                 Separate dynamic string in Dstr1 into two parts,\r
 103                 using "char" as separator. First part will be stored in\r
 104                 "Dstr2", second part in "Dstr1".\r
 105                 ex: asc \                               \ ..separator\r
 106                     D> listF\listLIB\5TH_DRVMOUSE       \ ..separate from\r
 107                     defDstr2                            \ ..place result in\r
 108                     Dstrsp              \ separation command\r
 109                     defDstr Dstr.       \ will be: listLIB\5TH_DRVMOUSE\r
 110                     defDstr2 Dstr.      \ will be: listF\r
 111 \r
 112 Dv ( addr -- )\r
 113                 Allocates empty dynamic string, and places it's handle\r
 114                 into given address.\r
 115 \r
 116 Df ( addr -- )\r
 117                 Reads dynamic string handle from given address and\r
 118                 deallocates (frees) it.\r
 119 \r
 120 ex:     var mystring1\r
 121         : testmodule\r
 122         mystring1 Dv            \ allocates string\r
 123 \r
 124                 <whatever>\r
 125 \r
 126         mystring1 Df ;          \ deallocates it again when no longer needed.\r