StrRepeat

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

Subroutine StrRepeat concatenates one or more copies of the source string (StrSrc) and stores the result into the destination string (StrDest)

Syntax

Arguments

StrSrc [Input]

String whose content must be concatenated and stored in StrDest. StrSrc can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

StrDest [Input/Output]

Destination string. It can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

iRet [Output, Optional]

Upon return, iRet contains the number of characters copied to StrDest, or BSTRINGS_ERROR if the procedure failed.

nCopies [Input, Optional]

Number of copies of StrSrc that should be concatenated and stored in StrDest. If this argument is not passed, StrRepeat assumes its value is one.

Comments

StrRepeat behaves differently depending on the type of the destination string. Fortran OLE Strings and BStrings are allocated dynamically when they are created. The limit in the number of characters they can hold is imposed by the resources available to the operating system at the moment StrRepeat is called. Fortran Strings and Fixed OLE Strings are allocated statically, or by the calling program. The limit in the number of characters they can receive is set during compilation, or before calling StrRepeat.

Static StrDest (Fortran Strings and Fixed OLE Strings)

When StrDest is a fixed length string, the destination string must be declared or allocated by the main program before calling StrRepeat.

StrRepeat will fail if it is requested to write more characters than those accepted by StrDest. In this case, the original content in StrDest, if any, is left intact, and argument iRet is set to BSTRINGS_ERROR upon return from the procedure.

If argument StrLen is not passed, has a negative value, or is larger than the number of characters in StrSrc, StrRepeat will copy the complete StrSrc into StrDest.

Dynamic StrDest (BStrings and Fortran OLE Strings)

When StrDest is a dynamic type, StrRepeat will allocate a new buffer for the destination string if the destination string has not already been allocated by the calling program. If StrDest has been allocated before calling StrRepeat, the procedure might reallocate the string to ensure it can accommodate the characters concatenated from StrSrc.

The size of the new string buffer is given by StrLenTrim(StrSrc) times nCopies. If nCopies is not passed or has a negative value, StrRepeat assumes a value of one.

If StrRepeat fails, the original content of the destination string may or may not be destroyed, and argument iRet is set to BSTRINGS_ERROR upon return from the procedure. The only case in which StrDest might be destroyed is when StrRepeat fails due to lack of available memory to allocate the new string. Otherwise, StrDest is left intact.

To restore the memory used by StrDest created with StrRepeat, the calling program must explicitly deallocate the string using subroutine StrFree.

Examples

!Demonstrates the use of StrRepeat

!copyright 1999, Canaima Software

!All rights reserved

!load f90VB modules

use f90VBDefs

use f90VBBStrings

implicit none

!declare a Fortran OLE String

type(OLESTRING)::OLEStr

!declare a BString

integer(BSTRHNDL_KIND)::BStr

integer(HRESULT_KIND)::iRet

character(len=200)::FStr

!Create a BString containing 3 concatenated copies of input string

call StrRepeat('Do-Re-Mi-Fa-Sol-La-Si-',BStr,iRet,3)

if (iRet.ne.BSTRINGS_ERROR) then

    call StrCopy(BStr,FStr)

    print *,'BString created'

    print *,'BString length:', StrLenTrim(BStr)

    print *,'BString content:',trim(FStr)

endif

!Create an OLE String containing 3 concatenated copies of input string

call StrRepeat(BStr,OLEStr,iRet,2)

if (iRet.ne.BSTRINGS_ERROR) then

    call StrCopy(OLEStr,FStr)

    print *,'OLEStr created'

    print *,'OLEStr length:', StrLenTrim(OLEStr)

    print *,'OLEStr content:',trim(FStr)

endif

!Change content of original BStr

call StrRepeat('La',BStr,iRet,10)

if (iRet.ne.BSTRINGS_ERROR) then

    call StrCopy(BStr,FStr)

    print *,'BString created'

    print *,'BString length:', StrLenTrim(BStr)

    print *,'BString content:',trim(FStr)

endif

!free memory used by dynamic strings

call StrFree(OLEStr)

call StrFree(BStr)

stop

end

Related Topics

StrSub