BStrAlloc

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

Function BStrAlloc allocates a new BString, initializes its content to StrSrc, and returns a handle to the new BString. If BStrAlloc fails, a null handle is returned.

Syntax

Arguments

StrSrc [Input]

String with the content used to initialize the new BString. StrSrc can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

StrLen [Input, Optional]

Number of characters from StrSrc that should be copied to StrDest. If StrLen>StrLenTrim(StrSrc), then StrDest's buffer is allocated to the size indicated in StrLen, and all characters in StrSrc are copied to StrDest. If StrLen is not passed, BStrAlloc assumes its value is the same as the trimmed length of StrSrc.

Comments

Function BStrAlloc is used to create new BStrings. To change the content of an existing BString, you can use BStrReAlloc or StrCopy.

BStrAlloc returns a handle to the allocated string, or a null handle if the function fails.

The programmer must take care to store the handle returned by BStrAlloc in order to reference the created BString in the future.

BStrAlloc always uses the default code page and conversion flag values when StrSrc is a Fortran String. If you want to create a BString with user-specified code page and flags, you can use the more general procedure StrCopy.

To restore the memory used by a BString created with BStrAlloc, the calling program must explicitly deallocate the string using subroutine StrFree.

Argument StrLen

Argument StrLen is used to indicate how many of the characters in StrSrc should be copied to StrDest. If zero is passed in argument StrLen, BStrAlloc allocates StrDest and sets its content to null (an empty string). If argument StrLen is not passed or has a negative value, the StrDest buffer is allocated to, at least, the size of StrLenTrim(StrSrc).

Note: When the size of the largest string to store in a dynamic type is known beforehand, initially allocating StrDest to this size may speed up further assignments.

Examples

!Demonstrates the use of function BStrAlloc

!Copyright 1999-2000, Canaima Software

!All rights reserved

!load f90VB modules

use f90VBDefs

use f90VBBStrings

implicit none

!declare two BStrings

integer(BSTRHNDL_KIND):: BStrA, BStrB

character(len=25):: FStr

!Allocate and initialize BStrA

BStrA = BStrAlloc('Example string')

!Allocate and initialize BStrB with the first

!seven characters from BStrA

BstrB= BStrAlloc(BstrA,7)

!Copy BStrA into a Fortran string for printing

call StrCopy(BstrA, FStr)

!Print info about BStrA

print *,'BStrA:', FStr

print *,'BString A Length:',StrLenTrim(BStrA)

!Copy BStrB into a Fortran string for printing

call StrCopy(BstrB, FStr)

!Print info about BStrA

call StrCopy(BstrB, FStr)

print *,'BStrB:', FStr

print *,'BString B Length:',StrLenTrim(BStrB)

!Free string memory

call StrFree(BStrA)

call StrFree(BStrB)

stop

end

Related Topics

BStrConvFromVB and BStrConvToVB