IMcOMGlobalMcToText Method

Parameters

varToText

Type: SystemObject
A value or array of values to render into text form. May be a scalar or array of any numeric, text or DATE Variant type. It may also be a McObject instance of a numeric, text or date/time McObject type.

Format_Value_BeforeAll_BetweenVals_AfterAll_BetweenRows (Optional)

Type: SystemObject
An array of up to five formating strings, as follows 0 C style printf format string (e.g., "%d") or a date/time Format string applied to EACH element of a varToText array. In the case where varToText is a string, each character is considered an element, so the default format is "%c". The rules for the format string are different for mcobjTypeDATETIME (i.e., DATE type Variants) from all other types of varToText values. The rules are discussed fully in "Remarks". 1 Before all string to be placed in front of converted values 2 String to be placed between each converted value within a "row". In the case of strings, this is placed between each character. 3 After all string to be placed after all converted values 4 String to be placed between each "row", or in the case of string sources, between each string. If only one format string is given as (rather than an array of strings), then the string is interpreted as the formatting string for each value (element 0 in the above table). If missing, the default format string for this data type is used (see Remarks), placing a space between multiple numeric values, vbLf between rows and with nothing before or after the converted values.

Return Value

Type: McObject
The converted, formatted text string.

This function is analagous to the C language 'sprintf' function and the VB Format function. Its purpose is to convert numerical data stored in binary form in a Variant into readable text returned in a mcobjTypeCHAR (i.e., a String). The primary advantage of McToText over more traditional ways of converting numeric data into text is its simplicity and flexibility. McToText can be passed a Variant source without being concerned if it contains scalar or array data. For arrays, McToText is a much more convenient way of showing values, since there is no need to write a loop to handle the array values. For both arrays and scalar values, McToText gives access to the powerful "C" printf style value formating. In addition, VB-style Format of dates and times is supported with extensions for displaying fractions of a second. Only the first argument, the Variant to convert, is required. In this default formating case you will get a reasonable default conversion with a compact representation of each number or date/time. For numeric sources, if the array length to be converted is greater than one, then each value in the array is separated by one space. No leading or trailing space appears, and each "row" of two (or higher) dimensional arrays is separated by a line-feed, vbLf. For String sources, the default is to separate each string after the first by a vbLf, thus placing each string on its own line. The default will work for most cases, but substantial flexibilty in the output format of the Variant to be converted is supported. The conversion format for each value can be specified (using C's printf formating rules or VB's date/time Format rules). You can also specify strings to be to be placed before and/or after all numbers (or source text strings), a string to be place between multiple values of a array (or between individual characters of source text strings) and a string to be placed between the "rows" of multi-dimensional arrays (or between succesive strings in a source array of them). When converting several scalar values or user-defined-types (structures) to text, consider using McSprintf instead of McToText. McSprintf can deal with an arbitrary number of arguments and allows you to specify a formatting string for all arguments together. If the number of strings in the Format_Value_BeforeAll_BetweenVals_AfterAll_BetweenRows array is less than five or if any element is a blank string, then a default is used for the missing formatting array element. The default is to separate numeric array elements by spaces and to place a line-break between the "rows" of 2-D arrays or arrays of strings. If the Format_Value_BeforeAll_BetweenVals_AfterAll_BetweenRows string is given, the user is responsible for matching the each-value formatting string (element 0 of the formatting string) to the varToText data type. Default formats for each basic data type (and types derived therefrom) are: String (mcobjTypeCHAR) "%c", Long (mcobjTypeINTEGER) "%d", Integer (mcobjTypeSHORT)"%hd", Byte (mcobjTypeBYTE) "%d", Single (mcobjTypeFLOAT) or Double (mcobjTypeREAL) "%g". The default for DATE Variant (mcobjTypeDATETIME McObject) type format is "General Date". The default formatting for Boolean Variant (mcobjTypeBOOLEAN McOject) type is to show "True" or "False" as the value; giving any non-default value format treats the source as if it were mcobjTypeINTEGER. The full rules for the each-value formatting string are given below. Format Specification Fields: for numeric and String (non Date/Time) type values The format specification, which consists of optional and required fields, has the following form. %[flags] [width] [.precision] [{h | l | I64 | L}]type Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %d). If a percent sign is followed by a character that has no meaning as a format field, the character is copied without change. For example, to print a percent-sign character, use %%. The optional fields, which appear before the type character, control other aspects of the formatting, as follows. type - Required character that determines whether the associated argument is interpreted as a character, a string, or a number. flags - Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification. width - Optional number that specifies the minimum number of characters output. precision - Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values. h | l | I64 | L - Optional prefixes to type-that specify the size of argument. Details of the Type field character - The type character is the only required format field; it appears after any optional format fields. The type character determines whether the associated argument is interpreted as a character or number. c, specifies a single-byte character. This is the type to use, and is the default, for any mcobjTypeCHAR McObject or String type Variant source. The types below are suitable for mcobjTypeINTEGER McObject (Long type Variants), mcobjTypeBYTE McObject (Byte type Variants), and when preceeded by an h mcobjTypeSHORT McObject (Integer type Variants) sources. d, Signed decimal integer. i, Signed decimal integer. o, Unsigned octal integer. u, Unsigned decimal integer. x, Unsigned hexadecimal integer, using �abcdef.� X, Unsigned hexadecimal integer, using �ABCDEF.� The types below are suitable for mcobjTypeREAL or mcobjTypeFLOAT McObject types (Double or Single type Variants) There is no need to distinguish between Double or Single since a cast to Double is made automatically before applying the format. e, Signed value having the form [ � ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or �. E, Identical to the e format except that E rather than e introduces the exponent. f, Signed value having the form [ � ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. g, Signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than �4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it. G, Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate). Details of the Flag Directives - The first optional field of the format specification is flags. A flag directive is a character that justifies output and prints signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a format specification. �, Left align the result within the given field width. Default is Right align. +, Prefix the output value with a sign (+ or �) if the output value is of a signed type. Default is Sign appears only for negative signed values (�). 0, If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and � appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. Default is No padding. blank (' '), Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. Default is No blank appears. #, When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. Default is No blank appears. #, When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. Default is Decimal point appears only if digits follow it. #, When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Default is Decimal point appears only if digits follow it. Trailing zeros are truncated. Details of the Width Specification - The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values � depending on whether the � flag (for left alignment) is specified � until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers). The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification). Details of the Precision Specification - The third optional field of the format specification is the precision specification. It specifies a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits (see Table R.5). Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output. The type determines the interpretation of precision and the default when precision is omitted, as shown below. How Precision Values Affect Type c, C - The precision has no effect. Default is Character is printed. d, i, u, o, x, X - The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. Default precision is 1. e, E - The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed. f The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed. g, G The precision specifies the maximum number of significant digits printed. By default, six significant digits are printed, with any trailing zeros truncated. Date and Time Formatting. For mcobjTypeDATETIME McObject or DATE type Variant sources, the value formatting string is very similar to that of the VB Format function. Extensions have been added to support display of fractions of a second. The mcobjTypeDATETIME McObject and DATE type Variant hold a Double (mcobjTypeREAL) value that encodes the date as the number of days since December 31, 1899 in the integer portion of the value and the time as a fraction of a day. The rules for the date and time formatting string are as follows "General Date" or "GD" is the default. If the value is a date only (i.e. the time fraction is zero, exactly midnight), no time is displayed; if the value is a time only, no date is displayed. This setting is a combination of the Short Date and Long Time settings. Example - 4/3/93 05:34:00 PM "Long Date" or "LD" Same as the Long Date setting in the Regional Settings Properties dialog box in Windows Control Panel. Example - Saturday, April 3, 1993 "Medium Date" or "MD" Abbreviated month name. Example - Apr 3, 1993 "Short Date" or "SD" Same as the Short Date setting in the Regional Settings Properties dialog box in Windows Control Panel. Example - 4/3/93. Warning, the Short Date setting assumes that dates between 1/1/00 and 12/31/29 are twenty-first century dates (that is, the years are assumed to be 2000 to 2029). Dates between 1/1/30 and 12/31/99 are assumed to be twentieth century dates (that is, the years are assumed to be 1930 to 1999). "Long Time" or "LT" Same as the setting on the Time tab in the Regional Settings Properties dialog box in Windows Control Panel. No fractional seconds are displayed. Example - 5:34:23 PM "Medium Time" or "MT" A 24-hour representation of the time, including three digits of fractional seconds (i.e., millseconds). Example - 17:34:23.000 "Short Time" or "ST" Hours and minutes only, using a 24-hour clock. Example - 17:34 Custom Date/Time Formats - You can create custom date and time formats by using the following symbols. : (colon) Time separator. Separators are set in the Regional Settings Properties dialog box in Windows Control Panel. / Date separator. c Same as the General Date predefined format. d Day of the month in one or two numeric digits, as needed (1 to 31). dd Day of the month in two numeric digits (01 to 31). ddd First three letters of the weekday (Sun to Sat). dddd Full name of the weekday (Sunday to Saturday). ddddd Same as the Short Date predefined format. dddddd Same as the Long Date predefined format. w Day of the week (1 to 7). ww Week of the year (1 to 53). m Month of the year in one or two numeric digits, as needed (1 to 12). mm Month of the year in two numeric digits (01 to 12). mmm First three letters of the month (Jan to Dec). mmmm Full name of the month (January to December). q Date displayed as the quarter of the year (1 to 4). y Number of the day of the year (1 to 366). yy Last two digits of the year (01 to 99). yyyy Full year (0100 to 9999). h Hour in one or two digits, as needed (0 to 23). hh Hour in two digits (00 to 23). n Minute in one or two digits, as needed (0 to 59). nn Minute in two digits (00 to 59). s Second in one or two digits, as needed (0 to 59). ss Second in two digits (00 to 59). . the decimal separator (for fractional seconds) f one digit of fractional seconds (ff for two digits) fff three digits of fractional seconds (milliseconds) ffffff six digits of fractional seconds (microseconds) ttttt Same as the Long Time predefined format. AM/PM Twelve-hour clock with the uppercase letters "AM" or "PM", as appropriate. am/pm Twelve-hour clock with the lowercase letters "am" or "pm", as appropriate. A/P Twelve-hour clock with the uppercase letter "A" or "P", as appropriate. a/p Twelve-hour clock with the lowercase letter "a" or "p", as appropriate. AMPM Twelve-hour clock with the appropriate morning/afternoon designator as defined in the Regional Settings Properties dialog box in Windows Control Panel. Custom formats are displayed according to the settings specified in the Regional Settings Properties dialog box in Windows Control Panel. Custom formats inconsistent with the settings specified in the Regional Settings Properties dialog box are ignored. If you want to add a comma or other separator to your custom format, enclose the separator in quotation marks like this: "mmm d"", ""yyyy"

'Show indices of Selected regions using default formatting
vSelected = ThisApplication.ActiveImage.RegionFeatures.Selected
ResultsText.Text = McToText( vSelected) 'display it
'Show 1st Region outline points as (X,Y lf tab X,Y lf tab etc..)
Dim fMyPoints As Variant 'an empty Variant
vNumPoints = Engine.ActiveImage.RegionFeatures.GetFeaturePoints(0,fMyPoints)
vsMyFmt = Array( "%6.2f", "(", ",", ")", CMcStr("\n\t") )
ResultsText.Text = "There are " + McToText(vNumPoints) +_
" points " + McToText(fMyPoints, vsMyFmt)

'This is ObjectManagerDateTimeSamples.bas

Option Explicit

Sub DateAndTimeMcToTextFormats()
    Dim dtT As Variant
    dtT = #1/2/2006 8:12:03 PM#
    Const cOneSec = 1# / (60# * 60 * 24) ' 1/86400 days
    dtT = dtT + cOneSec / 2 + cOneSec / 20 + cOneSec / 200 'add 555 msec
    Output.Show ("Output")
    Output.Clear
    Output.PrintMessage "*** Named Date and Time formats ***"
    Output.PrintMessage "General Date and Time: " + McToText(dtT) ' or "General Date" or "GD"
    Output.PrintMessage "Long Date: " + McToText(dtT, "Long Date") 'or "LD"
    Output.PrintMessage "Medium Date: " + McToText(dtT, "Medium Date") 'or "MD"
    Output.PrintMessage "Short Date: " + McToText(dtT, "Short Date") 'or "SD"
    Output.PrintMessage "Long Time: " + McToText(dtT, "Long Time") 'or "LT"
    Output.PrintMessage "Medium Time: " + McToText(dtT, "Medium Time") 'or "MT"
    Output.PrintMessage "Short Time: " + McToText(dtT, "Short Time") 'or "ST"
    Output.PrintMessage "*** Custom Date and Time format examples ***"
    Output.PrintMessage "Full date and 24-hr time with milliseconds: " + _
        McToText(dtT, "dddd, mmmm d, yyyy at hh:mm:ss.fff")
    Output.PrintMessage "24-hr time with microseconds: " + McToText(dtT, "hh:mm:ss.ffffff")
    Output.PrintMessage "AM/PM time hours and minutes only: " + McToText(dtT, "hh:mm AM/PM")
    Output.PrintMessage "Abbreviations, no milliseconds: " + _
        McToText(dtT, "ddd, mmm d, yy at h:mm:ss A/P")
'    The above produces the following output:
'
'    *** Named Date and Time formats ***
'    General Date and Time: 1/2/2006 8:12:04 PM
'    Long Date: Monday, January 02, 2006
'    Medium Date: Jan 2, 2006
'    Short Date: 1/2/2006
'    Long Time: 8:12:04 PM
'    Medium Time: 20:12:03.555
'    Short Time: 20:12
'    *** Custom Date and Time format examples ***
'    Full date and 24-hr time with milliseconds: Monday, January 2, 2006 at 20:12:03.555
'    24-hr time with microseconds: 20:12:03.555000
'    AM/PM time hours and minutes only: 08:12 PM
'    Abbreviations, no milliseconds: Mon, Jan 2, 06 at 8:12:03 P
End Sub 'DateAndTimeMcToTextFormats

Sub CreateDateTimeMcObjects()
    Dim datetimeT As Variant
    datetimeT = #1/2/2006 9:02:06 PM#
    datetimeT = datetimeT + 1# / (60# * 60 * 24 * 20) 'add 50 msec
    Dim mcobjDT As McObject
    Set mcobjDT = McObjectTemp(datetimeT)
    Dim datetimeT2 As Variant
    datetimeT2 = mcobjDT.Value
    Output.Show ("Output")
    Output.Clear
    Output.PrintMessage "A date and time with milliseconds: " + _
        McToText(datetimeT2, "mm/dd/yyyy hh:mm:ss.fff AM/PM")
    Dim mcobjNow As McObject
    Set mcobjNow = McObjects.Add(mcobjTypeDATETIME, , , Now)
    Output.PrintMessage "It is now " + McToText(mcobjNow, "Long Date") + _
        " at " + McToText(mcobjNow, "Long Time")
    Dim mcobjTomorrow As McObject
    Set mcobjTomorrow = McOpAdd(mcobjNow, 1#)
    Output.PrintMessage "Tomorrow will be " + McToText(mcobjTomorrow, "Long Date")
    Dim mcobjNext4Weeks As McObject
    Set mcobjNext4Weeks = McOpAdd(McOpCast(McOpMul(McOpFillIn(1, 5), 7), "DATETIME"), mcobjNow)
    Output.PrintMessage McToText(mcobjNext4Weeks, Array("Medium Date", "Next 4 weeks: ", " --> "))
'    The above produces the following output:
'
'    A date and time with milliseconds: 01/02/2006 09:02:06.050 PM
'    It is now Wednesday, January 04, 2006 at 8:45:17 PM
'    Tomorrow will be Thursday, January 05, 2006
'    Next 4 weeks: Jan 11, 2006 --> Jan 18, 2006 --> Jan 25, 2006 --> Feb 1, 2006
End Sub 'CreateDateTimeMcObjects