BBC BASIC Programmers' Reference

by Jon Ripley, May 2007

The following routine will clear the contents of any structure passed to it:

        REM Clear any structure (by Jon Ripley)
        DEF PROC_ClearStruct(S{})
        LOCAL E{}, F{}
        DIM E{} = S{}, F{} = S{}
        E{} = S{} : S{} = F{}
        ENDPROC

Call using:

        PROC_ClearStruct( StructToBeCleared{} )

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:

        FOR I% = 0 TO DIM(StructToBeCleared{()},1)
          PROC_ClearStruct(StructToBeCleared{(I%)})
        NEXT I%

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 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:

        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