BBC BASIC Programmers' Reference

User Tools

Site Tools

Trace:
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 14:19]
127.0.0.1 external edit 		clearing_20the_20contents_20of_20a_20structure [2018/04/17 16: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.1522502349.txt.gz ยท Last modified: 2018/03/31 14:19 by 127.0.0.1

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki