=====Clearing the contents of a structure=====

//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{})
        LOCAL E{}, F{}
        DIM E{} = S{}, F{} = S{}
        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// 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{}
        E{} = S{}                : REM Copy stucture-to-be-cleared into local structure E{}
        S{} = F{}                : REM Copy empty structure F{} into S{}, hence clearing it
        ENDPROC                  : REM Clean up any strings in E{}, freeing their memory
</code>