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 format="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 format="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 for each, for a one dimensional array this code would suffice: code format="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 and  create a local structure **** with an identical format to the structure **** 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 copies the contents of **** into ****, thus clearing it. Superficially this would seem to be sufficient to accomplish the task, but there is a problem. As it states in the [|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 **** into **** 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 **** 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 ****, and copying the contents of structure **** 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 format="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