StrSub

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

Subroutine StrSub extracts a sub string from StrSrc. The resulting sub string is stored in StrDest.

Syntax

Arguments

StrSrc [Input]

String from which a sub string will be extracted. StrSrc can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

StrDest [Input/Output]

Destination string. Upon return from StrSub, it contains the sub string extracted from StrSrc. It can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

Start [Input, Optional]

Start point of the string to be extracted from StrSrc. If Start is larger than the number of characters in StrSrc, the resulting StrDest will be empty.

Length [Input, Optional]

Length of the sub string to be extracted from StrSrc. If Start+Length is larger than the number of characters in StrSrc, StrSub will extract all characters from StrSrc to the right of Start (inclusive). If Length is zero, the resulting StrDest is an empty string.

iRet [Output, Optional]

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

Comments

StrSub 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 StrSub 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 StrSub.

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 StrSub.

StrSub 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.

Dynamic StrDest (BStrings and Fortran OLE Strings)

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

The size of the new string buffer is the size of the sub string extracted from StrSrc.

If StrSub 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 StrSub fails to allocate the new string due to lack of available memory.

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

Examples

!Demonstrates the use of StrSub

!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=50)::FStr

!Create a BString

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

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 a OLE string by extracting a sub string from Bstr

call StrSub(BStr,OLEStr,4,2,iRet)

if (iRet.ne.BSTRINGS_ERROR) then

    call StrCopy(OLEStr,FStr)

    print *,'OLEStr created'

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

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

endif

!free memory used by dynamic strings

call StrFree(OLEStr)

call StrFree(BStr)

stop

end

Related Topics

f90VBSafeArrays Library