McFromText Method

Description

Scans a character string for numeric values.

Return Type

A Long value.

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.

Syntax

object.McFromText (SourceText, NumbersFound, [CharLimits], [MaxNumbersToScan])

The McFromText Method syntax has these parts:

Part	Description
object	An expression evaluating to an object of type McOMGlobal.
SourceText	Required. A String value. A text string to be scanned for numbers.
NumbersFound	Required. A Variant value. 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. A Variant value. 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. A Long value. 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.

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