User Tools

Site Tools


clearing_20the_20contents_20of_20a_20structure

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

clearing_20the_20contents_20of_20a_20structure [2018/03/31 13:19]
127.0.0.1 external edit
clearing_20the_20contents_20of_20a_20structure [2018/04/17 15:18] (current)
tbest3112 Added syntax highlighting
Line 2: Line 2:
  
 //by Jon Ripley, May 2007//\\ \\  The following routine will clear the contents of any structure passed to it:\\  //by Jon Ripley, May 2007//\\ \\  The following routine will clear the contents of any structure passed to it:\\ 
 +<code bb4w>
         REM Clear any structure (by Jon Ripley)         REM Clear any structure (by Jon Ripley)
         DEF PROC_ClearStruct(S{})         DEF PROC_ClearStruct(S{})
Line 8: Line 9:
         E{} = S{} : S{} = F{}         E{} = S{} : S{} = F{}
         ENDPROC         ENDPROC
 +</​code>​
 \\  Call using:​\\ ​ \\  Call using:​\\ ​
 +<code bb4w>
         PROC_ClearStruct( StructToBeCleared{} )         PROC_ClearStruct( StructToBeCleared{} )
 +</​code>​
 The **StructToBeCleared{}** can be any kind of structure.\\ \\  To clear the contents of a structure array you need to iterate through all elements calling "​PROC_ClearStruct"​ for each, for a one dimensional array this code would suffice:​\\ ​ The **StructToBeCleared{}** can be any kind of structure.\\ \\  To clear the contents of a structure array you need to iterate through all elements calling "​PROC_ClearStruct"​ for each, for a one dimensional array this code would suffice:​\\ ​
 +<code bb4w>
         FOR I% = 0 TO DIM(StructToBeCleared{()},​1)         FOR I% = 0 TO DIM(StructToBeCleared{()},​1)
           PROC_ClearStruct(StructToBeCleared{(I%)})           PROC_ClearStruct(StructToBeCleared{(I%)})
         NEXT I%         NEXT I%
 +</​code>​
 \\ \\
 ---- ----
 ==== How it works ==== ==== How it works ====
 //by Richard Russell, June 2007//\\ \\  The statements "LOCAL F{}" and "DIM F{} = S{}" create a local structure **"​F{}"​** with an identical format to the structure **"​S{}"​** but in which all the members are //empty//, that is all numeric members (including numeric arrays) are set to zero and all string members (including string arrays) are set to null (zero length) strings.\\ \\  The statement "S{} = F{}" copies the contents of **"​F{}"​** into **"​S{}"​**,​ thus clearing it. Superficially this would seem to be sufficient to accomplish the task, but there is a problem. As it states in the [[http://​www.bbcbasic.co.uk/​bbcwin/​manual/​bbcwin2.html#​structcopy|Help documentation]] you should not copy structures containing **string** members, since only the //string descriptors//​ are copied rather than the string contents. In this particular case the effect of copying the empty structure **"​F{}"​** into **"​S{}"​** will be to cause the memory occupied by any strings it contains to be //leaked//, that is to be used up irreversibly. The eventual outcome may be an untrappable **No room** error, which is very serious.\\ \\  The straightforward solution to this problem is to empty any string members of **"​S{}"​** explicitly, before clearing the remainder of its contents. However this requires knowledge of the specific format of the structure, and in the case of a string array requires each element to be emptied individually (for example in a FOR...NEXT loop), which is inconvenient and relatively slow.\\ \\  The alternative method adopted in **PROC_ClearStruct** above relies on the fact that BBC BASIC for Windows automatically empties any strings, and string arrays, contained in a LOCAL structure (when the procedure or function in which that structure was declared is exited). This automatic 'clean up' is necessary to avoid a memory leak every time you use a LOCAL structure containing strings.\\ \\  By declaring a second LOCAL stucture **"​E{}"​**,​ and copying the contents of structure **"​S{}"​** into it, advantage can be taken of this automatic clean up process. Here is a breakdown of the main steps in PROC_ClearStruct with their functions annotated:​\\ \\  //by Richard Russell, June 2007//\\ \\  The statements "LOCAL F{}" and "DIM F{} = S{}" create a local structure **"​F{}"​** with an identical format to the structure **"​S{}"​** but in which all the members are //empty//, that is all numeric members (including numeric arrays) are set to zero and all string members (including string arrays) are set to null (zero length) strings.\\ \\  The statement "S{} = F{}" copies the contents of **"​F{}"​** into **"​S{}"​**,​ thus clearing it. Superficially this would seem to be sufficient to accomplish the task, but there is a problem. As it states in the [[http://​www.bbcbasic.co.uk/​bbcwin/​manual/​bbcwin2.html#​structcopy|Help documentation]] you should not copy structures containing **string** members, since only the //string descriptors//​ are copied rather than the string contents. In this particular case the effect of copying the empty structure **"​F{}"​** into **"​S{}"​** will be to cause the memory occupied by any strings it contains to be //leaked//, that is to be used up irreversibly. The eventual outcome may be an untrappable **No room** error, which is very serious.\\ \\  The straightforward solution to this problem is to empty any string members of **"​S{}"​** explicitly, before clearing the remainder of its contents. However this requires knowledge of the specific format of the structure, and in the case of a string array requires each element to be emptied individually (for example in a FOR...NEXT loop), which is inconvenient and relatively slow.\\ \\  The alternative method adopted in **PROC_ClearStruct** above relies on the fact that BBC BASIC for Windows automatically empties any strings, and string arrays, contained in a LOCAL structure (when the procedure or function in which that structure was declared is exited). This automatic 'clean up' is necessary to avoid a memory leak every time you use a LOCAL structure containing strings.\\ \\  By declaring a second LOCAL stucture **"​E{}"​**,​ and copying the contents of structure **"​S{}"​** into it, advantage can be taken of this automatic clean up process. Here is a breakdown of the main steps in PROC_ClearStruct with their functions annotated:​\\ \\ 
 +<code bb4w>
         LOCAL E{}, F{}           : REM Declare local structures E{} and F{}         LOCAL E{}, F{}           : REM Declare local structures E{} and F{}
         DIM E{} = S{}, F{} = S{} : REM Set E{} and F{} to have the same format as S{}         DIM E{} = S{}, F{} = S{} : REM Set E{} and F{} to have the same format as S{}
Line 23: Line 30:
         S{} = F{}                : REM Copy empty structure F{} into S{}, hence clearing it         S{} = F{}                : REM Copy empty structure F{} into S{}, hence clearing it
         ENDPROC ​                 : REM Clean up any strings in E{}, freeing their memory         ENDPROC ​                 : REM Clean up any strings in E{}, freeing their memory
 +</​code>​
clearing_20the_20contents_20of_20a_20structure.txt ยท Last modified: 2018/04/17 15:18 by tbest3112