StrCopy

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

StrCopy stores a copy of the source string (StrSrc) into the destination string (StrDest). The procedure performs any necessary type conversion automatically. If StrDest is a dynamic string type, StrCopy will automatically allocate/reallocate StrDest with its new content.

Syntax

Arguments

StrSrc [Input]

String with content used to initialize or to store into 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. StrDest can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings). If StrDest is a null BString handle or an unallocated Fortran OLE String, StrCopy will allocate a new string and return it in StrDest.

iRet [Output, Optional]

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

StrLen [Input, Optional]

Number of characters from StrSrc that should be copied to StrDest. If StrDest is a dynamic string type (Fortran OLE String or BString) and 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, StrCopy assumes its value is the same as the trimmed length of StrSrc.

CodePage [Input, Optional]

Code page used to perform the conversion from Unicode strings (Fixed OLE Strings, Fortran OLE Strings and BStrings) to ANSI/Multibyte strings (Fortran strings) and vice versa. This parameter can be given the value of any code page that is installed or available in the system. See comments for more information.

Flags [Input, Optional]

A set of bit flags that specify the handling of unmapped characters when converting from Unicode to ANSI/Multibyte strings and vice versa. See comments for more information.

DefaultChar [Input, Optional]

Character used if a Unicode character cannot be represented in the specified code page, when converting from Unicode strings to ANSI/Multibyte strings. See comments for more information.

DefaultCharUsed [Output, Optional]

Logical flag indicating if the procedure used DefaultChar during the conversion process.

Comments

StrCopy behaves differently depending on the type of the destination string. Fortran OLE Strings and BStrings are allocated dynamically when they are created. The number of characters they can hold is limited only by the resources available to the operating system at the moment StrCopy 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 StrCopy.

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

StrCopy 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, StrCopy will copy the complete StrSrc into StrDest.

Dynamic StrDest (BStrings and Fortran OLE Strings)

When StrDest is a dynamic type, StrCopy 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 StrCopy, the procedure may reallocate the string to ensure it can accommodate the characters transferred from StrSrc.

The size of the new string buffer depends on the values passed in argument StrLen. If argument StrLen is not passed or has a negative value, the StrDest buffer is allocated to, at least, the size returned by StrLenTrim(StrSrc). If StrLen is larger than StrLenTrim(StrSrc), the buffer allocated for StrDest is, at least, the size indicated in StrLen.

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

To restore the memory used by StrDest created with StrCopy, 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, StrCopy returns an empty string in StrDest. If StrDest is a dynamic type, the string is allocated and set to null (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). If StrLen is passed, and its value is less than the number of characters in StrSrc, only the first StrLen characters in StrSrc are stored in StrDest.

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.

Code Pages

The CodePage argument is valid only when StrDest is an ANSI/Multibyte string (i.e. a Fortran String) and StrSrc is a Unicode string (all other f90VB string types) or vice versa. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following precoded values:

If a CodePage argument is not passed, StrCopy assumes the default value (CP_ACP).

Flags

Flags passed to StrCopy are bit-wise values. They are used to control the translation of characters when converting from Unicode to ANSI/Multibyte types or vice versa. The following tables explain allowed flags that can be used in each case.

StrDest: Unicode (Fixed OLE Strings, Fortran OLE Strings and BStrings)

MB_PRECOMPOSED Always use precomposed characters - that is, characters in which a base character and a non-spacing character have a single character value. This is the default translation option. Cannot be used with MB_COMPOSITE

MB_COMPOSITE Always use composite characters - that is, characters in which a base character and a non-spacing character have different character values. Cannot be used with MB_PRECOMPOSED

MB_ERR_INVALID_CHARS If the procedure encounters an invalid input character, it fails and StrCopy returns BSTRINGS_ERROR in iRet.

MB_USEGLYPHCHARS Use glyph characters instead of control characters

A composite character consists of a base character and a non-spacing character, each having different character values. A precomposed character has a single character value for a base/non-spacing character combination. In the character è, the e is the base character and the accent grave mark is the nonspacing character.

StrCopy's default behavior is to translate to the precomposed form. The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

StrDest: ANSI/Multibyte (Fortran String)

WC_NO_BEST_FIT_CHARS Any Unicode characters that do not translate directly to Multibyte equivalents will be translated to the default character (see DefaultChar argument). In other words, if translating from Unicode to Multibyte and back to Unicode again does not yield the exact same Unicode character, the default character is used. This flag may be used by itself or in combination with the other Flag options

WC_COMPOSITECHECK Convert composite characters to precomposed characters

WC_DISCARDNS Discard nonspacing characters during conversion

WC_SEPCHARS Generate separate characters during conversion. This is the default conversion behavior

WC_DEFAULTCHAR Replace exceptions with the default character (DefaultChar) during conversion.

When WC_COMPOSITECHECK is specified, StrCopy converts composite characters to precomposed characters. A composite character consists of a base character and a non-spacing character, each having different character values.

When an application specifies WC_COMPOSITECHECK, it can use the last 3 flags in the table (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine StrCopy's behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last 3 flags can only be used if the WC_COMPOSITECHECK flag is set. StrCopy's default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

Arguments DefaultChar and DefaultCharUsed

During the conversion from Unicode to ANSI/Multibyte strings, some Unicode characters may not have an equivalent ANSI/Multibyte representation. Argument DefaultChar indicates a character that can be used if a Unicode character cannot be represented in the specified code page. If this argument is not passed to StrCopy, the procedure uses the system default value. If StrCopy has to use the default character (either one passed to the subroutine or the system's default), the procedure returns .TRUE. in argument DefaultCharUsed.

Examples

!Demonstrates several uses of subroutine StrCopy

!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

!declare a Fixed OLE String (integer vector)

integer(OLECHAR_KIND)::FxOLEStr(15)

!declare a Fortran OLE String structure

type(OLESTRING)::OLEStr

!declare a Fortran string

character(len=35)::FStr

!utility variables

integer(HRESULT_KIND)::iRet

integer::i

character(len=1024)::TmpFStr

!Create and initialize a new BString

call StrCopy('This is a BString example',BStrB,iRet)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating BString'

else

    call StrCopy(BStrB,TmpFStr)

    print *,'A BString was created'

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

    print *,'BString handle:',BStrB

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

endif

!Copy the first 10 characters of BStrB to a Fortran String

call StrCopy(BStrB,FStr,iRet,10)

!add some additional text to fortran string

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error copying BString to Fortran String'

else

    FStr=trim(FStr)//' Fortran String example'

    print *,''

    print *,'BString copied to Fortran String'

    print *,'Fortran String Length:',StrLenTrim(FStr)

    print *,'Fortran String content:',trim(FStr)

endif

!create a Fortran OLE String with a large buffer

call StrCopy(FStr(1:8)//'not '//FStr(9:24),OLEStr,iRet,100)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating Fortran OLE String'

else

    call StrCopy(OLEStr,TmpFStr)

    print *,''

    print *,'Fortran OLE String Created'

    print *,'OLE String Length:',StrLenTrim(OLEStr)

    print *,'OLE String Buffer length:', StrLen(OLEStr)

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

    print *,'Fortran OLE String structure:'

    print *,'String handle:',OLEStr%StrHndl

    print *,'First 5 characters:', (OLEStr%Str(i),i=1,5)

    print *,'First 5 characters in ascii:',(achar(OLEStr%Str(i)),i=1,5)

endif

!Create a new BString from a Fortran OLE String

call StrCopy(OLEStr,BStrA,iRet)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating BString'

else

    call StrCopy(BstrA,TmpFStr)

    print *,''

    print *,'A BString was created'

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

    print *,'BString buffer length:',StrLen(BStrA)

    print *,'BString handle:',BStrA

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

endif

!Change the content of a BString and 

!force allocation of a large buffer

call StrCopy(BStrA,BStrB,iRet,150)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating BString'

else

    call StrCopy(BstrB,TmpFStr)

    print *,''

    print *,'A BString was created'

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

    print *,'BString buffer length:',StrLen(BStrB)

    print *,'BString handle:',BStrB

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

endif

!Produces an error because Fixed OLE String is not

!large enough to hold all characters in Fortran String

print *,''

print *,'FxOLEStr is too small to accept FStr'

call StrCopy(FStr,FxOLEStr,iRet)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating BString'

endif

print *,'Copy only the first 4 characters of FStr'

call StrCopy(FStr,FxOLEStr,iRet,4)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating BString'

else

    call StrCopy(FxOLEStr,TmpFStr)

    print *,'A Fixed OLE String was created'

    print *,'Fixed OLE String Length:',StrLenTrim(FxOLEStr)

    print *,'Fixed OLE buffer length:',StrLen(FxOLEStr)

    print *,'Fixed OLE content:', trim(TmpFStr)

endif

!release memory used by dynamic f90VB strings

call StrFree(BstrA)

call StrFree(BstrB)

call StrFree(OLEStr)

stop

end

Related Topics

StrFortran