Click or drag to resize

IMcOMGlobalMcFromText Method

Scans a character string for numeric values.

Namespace:  MediaCy.IQL.ObjectManager
Assembly:  MediaCy.IQL.ObjectManager (in MediaCy.IQL.ObjectManager.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function McFromText ( 
	SourceText As String,
	<OutAttribute> ByRef NumbersFound As Object,
	<OptionalAttribute> <OutAttribute> ByRef CharLimits As Object,
	Optional MaxNumbersToScan As Integer = 1
) As Integer

Parameters

SourceText
Type: SystemString
A text string to be scanned for numbers.
NumbersFound
Type: SystemObject
A Variant into which scanned numbers are placed as an array. The type of this Variant determines the type of numeric results returned. If the Variant is initially Empty, then it is filled with a float (VT_R8) array. This is always filled with an array, even if only one number is scanned (it will then be a length-1 array). If zero numbers are scanned, the returned NumbersFound array will be zero-length.
CharLimits (Optional)
Type: SystemObject
If given, a length-1 or length-2 Long array. The first element is an offset into SourceText giving the starting point of the scan; on exit, this element in the object will be updated to the offset of the next character to be scanned (i.e., the character that terminated the scan). If the array is length-2, then then second element is the maximum number of characters to scan; on exit, this element is reduced by the actual number of characters scanned (if this element is not given, the SourceText string is potentially scanned up to its end). If this argument is not supplied, no offset or character limits are used or updated; scanning starts at the beginning of the SourceText string and can cover the whole string, if necessary.
MaxNumbersToScan (Optional)
Type: SystemInt32
If given, the maximum number of values to be scanned from SourceText and placed into NumbersFound. The actual number of scanned values is the return value of the function and may be less than this maximum. If this argument is not supplied, a maximum of one value is scanned.

Return Value

Type: Int32
The number of values scanned and placed in the NumbersFound results array. The return value may be less than the MaxNumbersToScan requested number of values (it may even be zero) if the SourceText string is empty or contains too few convertable number(s) or if the CharLimits offset, count array is past the end of the string or references text which contains too few numbers.
Remarks
FromText scans a character string for numeric values, converts the values to binary form and places them in a data array. This function is is analagous to the C language 'sscanf' function; its purpose is to convert numeric text strings in a string variable into numerical data stored in binary form in Long, Integer, Float or Single data arrays. The conversion is quite forgiving. Numbers in the text may be separated by any number of white-space, comma or other non-numeric characters. The three common situations which call for scanning text strings for numbers are illustrated in the examples: (Example 1) one number only needs to be converted from the string; (Example 2) succesive "records" of a known number of different variables need to be converted into separate vectors; or (Example 3) a vector of values needs to be scanned into one object. In scanning for a number, leading white-space (spaces, tabs or new-lines) and all other non-numeric characters are always skipped before converting a value. In this context, a period is considered a numeric character only if NumbersFound is a floating point Variant or is an Empty Variant; thus, for non-floating point objects, numbers in the text with decimal points will convert as two integral values. In rare cases the conversion may be too forgiving. For example, you may be reading tab-separated data where two tabs in a row means that a value is missing, or you might want to extract text sub-strings along with numeric values from the SourceText argument. In these cases, you must examine the text string at the offset of the first element of the update the last number converted to do any special processing before calling McFromText to convert the next number (remember that all non-numeric leading characters will be skipped when scanning for a number). You can use the McSearchString() function to find text sub-strings and a selector to retrieve them (e.g., see the first example with the McSearchString documentation). Example 3 illustrates another use of McSearchString() as a helper for FromText. In the example, McSearchString() is passed a regular expression that finds whole lines; the return value from McSearchString(), iScan, is then directly suitable for use as the CharLimits argument of the call to McFromText (it gives the starting offset and the number of characters matched in the line just found).
Examples
VB
Copy
'Example 1. Parse a single number from text
Dim sText As String
sText = InputBox("Enter one number for FromText to parse", "FromText Test")
Dim varN As Variant
' varN = 1& 'Set result type to Long
If McFromText(sText, varN) > 0 Then ' scan for one number
Results.Text = "Your number was: " + Str(varN(0)) + " Type is: " + TypeName(varN)
Else ' zero returned by FromText
Results.Text = sText + " contains no number."
End If
'Example 2. Parse pairs of long,double numbers from text
sText = InputBox("Enter Long,Double pairs for FromText to parse", "FromText Test")
' Create accumulation arrays as IMcObject
Dim lArray As IMcObject, dArray As IMcObject
Set lArray = McArrayTemp("LONG") 'init accumulation arrays to empty
Set dArray = McArrayTemp("REAL")
Dim varlN, vardN, varlArray, vardArray, varlScan
varlN = 1& 'Set varlN type to Long
vardN = 1#  'Set vardN type to Double
varlScan = 0&   'Init varlScan to 0 (start of string)
While McFromText(sText, varlN, varlScan) > 0 And _
McFromText(sText, vardN, varlScan) > 0
lArray.OpSelfConcat varlN ' Concatenate LONG number to LONG array
dArray.OpSelfConcat vardN ' Concatenate Double number to Double array
Wend ' While more number pairs
Results.Text = Results.Text + vbCrlf + "Your Longs were: " + McToText(lArray) + _
vbCrlf + "Your Doubles were: " + McToText(dArray)
'Example 3. Find all numbers on each line in a file.
Set fs = CreateObject("Scripting.FileSystemObject")
Set f = fs.OpenTextFile("c:\testfile.txt")
sText = f.ReadAll
f.Close
Dim iSrch As Long, iLine As Long
iSrch = 0
iLine = 0
Dim rN As Variant
rN = 0# ' Init rN as a Double Variant
' rNums is 2-D Double array, each row gets filled from one line
Dim rNums As IMcObject
Set rNums = McArrayTemp("REAL", Array(0, 0)) ' empty 2-D array
' Use SearchString to find lines using a regular expression
Do
Dim iScan As Variant
iScan = McSearchString("^.*$", sText, mcobjAllowRegularExpression, iSrch)
If iScan(0) < 0 Then Exit Do
iSrch = iScan(0) + iScan(1) + 1 ' start next search past this one
Dim nFound As Long
nFound = McFromText(sText, rN, iScan, 100)  ' 100 max per line
iLine = iLine + 1
Results.Text = Results.Text + vbCrlf + "On line #" + Str(iLine) + _
" we found " + Str(nFound) + " real numbers."
rNums.OpSelfConcatConcat (rN) ' add a row to our accumulating results
Loop While True ' end of while another line was found
Results.Text = Results.Text + vbCrlf + "The accumulated result: " + McToText(rNums)
See Also