Differences

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

--- clearing_20the_20contents_20of_20a_20structure [2018/03/31 13:19] – external edit 127.0.0.1
+++ clearing_20the_20contents_20of_20a_20structure [2024/01/05 00:22] (current) – external edit 127.0.0.1
@@ Line 2: / Line 2: @@
 //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)
         DEF PROC_ClearStruct(S{})
@@ Line 8: / Line 9: @@
         E{} = S{} : S{} = F{}
         ENDPROC
+</code>
 \\  Call using:\\
+<code bb4w>
         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:\\
+<code bb4w>
         FOR I% = 0 TO DIM(StructToBeCleared{()},1)
           PROC_ClearStruct(StructToBeCleared{(I%)})
         NEXT I%
+</code>
 \\
 ----
 ==== 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// and //BBC BASIC for SDL 2.0// automatically empty 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{}
         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
         ENDPROC                  : REM Clean up any strings in E{}, freeing their memory
+</code>