StrConcat

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

Subroutine StrConcat concatenates StrA and StrB. The result is returned in StrA.

Syntax

Arguments

StrA [Input/Output]

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

StrB [Input]

String whose content will be concatenated to the right of StrA. StrB 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 total number of characters in StrA after the concatenation, or BSTRINGS_ERROR if the procedure failed.

StrLen [Input, Optional]

Number of characters in StrB that should be concatenated to the right of StrA. If this argument is not passed, StrConcat will concatenate all the characters in StrB to the right of StrA.

Comments

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

Static StrA (Fortran Strings and Fixed OLE Strings)

When StrA is a fixed length string, it must be declared or allocated by the main program before calling StrConcat.

StrConcat will fail if the combined trimmed length of StrA and StrB is larger than the number of characters that can be stored in StrA. In this case, the original content in StrA, 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 StrB, StrConcat attempts to add all the characters in StrB to the right of StrA. If StrLen is passed, and its value is less than the number of characters in StrB, only the first StrLen characters in StrB are added to the right of StrA.

Dynamic StrA (BStrings and Fortran OLE Strings)

When StrA is a dynamic type, StrConcat will allocate a new buffer large enough to accommodate the concatenated strings. If StrA has been allocated before calling StrConcat, the procedure might reallocate the string to ensure it can accommodate the concatenated strings. The size of the new buffer will be, at least, the value of StrLenTrim(StrA)+StrLenTrim(StrB).

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

Examples

!Demonstrates the use of StrConcat

!Copyright 1999-2000, Canaima Software

!All rights reserved

!load f90VB modules

use f90VBDefs

use f90VBBStrings

implicit none

!declare of BString

integer(BSTRHNDL_KIND)::BstrA

!Declare an OLE String

type(OLESTRING)::OLEStr

!Declare a Fortran string

character(len=5)::FStr

integer(HRESULT_KIND)::iRet

integer::i

character(len=255)::TmpFStr

!concatenate a Fortran String to a BString

call StrCopy('This is',BStrA)

call StrConcat(BStrA,' the result of a')

call StrConcat(BStrA,' concatenation operation')

call StrCopy(BstrA, TmpFStr)

print *, trim(TmpFStr)

print *,'Total String length:', StrLenTrim(BstrA)

!concatenate a Fortran String to a OLE String

!note that the first call to StrConcat will

!allocate a new OLEStr

print *,''

print *,'Another example:'

do i=10,15

    write(FStr,'(i2)') i

    call StrConcat(OLEStr,FStr,iRet)

    call StrCopy(OLEStr,TmpFStr)

    print *,'OLE String:', trim(TmpFStr)

    print *,'Concat. characters:',iRet

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

enddo

!free memory used by dynamic strings

call StrFree(OLEStr)

call StrFree(BStrA)

stop

end

Related Topics

StrCopy