Differences

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

--- clearing_20the_20contents_20of_20a_20structure [2018/04/17 15:18] – Added syntax highlighting tbest3112
+++ clearing_20the_20contents_20of_20a_20structure [2024/01/05 00:22] (current) – external edit 127.0.0.1
@@ Line 23: / Line 23: @@
 ----
 ==== 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{}