newObjects ActiveX Pack1 StringUtilities

Overview | Creation | Reference 

The StringUtilities object implements several methods that allow the application to create formatted output to streams or strings by passing a format specification and set of variables to be replaced in it. The format specification is compatible with the format specification found in the printf/sprintf methods in the standard C libraries. If you have even small C language programming experience you will find it quite familiar. However this object is designed to work in COM and most often scripting environments which makes certain extensions to the standard C format very useful. Thus the format supported is an extended version of what you may know from C run-time libraries, for instance it supports date/time formatting, auto-formatting of arguments according to what they contain and the rules specified, support for Null values for better database integration.

The properties of the StringUtilities object allow you change some of the general format settings and thus you can create, configure and keep several copies of the object ready to serve different tasks. For example the object does not use the system supplied locale settings, you can specify these parameters yourself and have it producing what you need even if the system does not support a locale settings that will match your need. This is especially useful for languages that use delimiter characters or decimal point character which is not recognized by other applications (for example many locales use "," for decimal point which is not compatible with the SQL language). For more details see the format specification - it refers to the related properties wherever they concern certain format syntactic element. 

See also Sample usage and Format specification

The object performs all its tasks in UNICODE character set and no conversions are made. There is no need to be concerned about the code pages and the content of the strings when using it.


Threading model: Both
Program ID: newObjects.utilctls.StringUtilities
ClassID: {B43BED8B-B48C-410B-BEB7-7FAF22ACE9FC}
Threading model: Free
ClassID: {CF542753-0204-4709-B459-2B67BD54CDFB}

Methods and properties

method.gif (107 bytes) Sprintf Syntax:
str = object.Sprintf(format_spec [, arg1 [, arg2 [, arg3 [ ... ]]]])

Returns a string using the format specification and the arguments passed to the method. The function may take any number of arguments, but they should be at least as much as the format specified requires. If the arguments are not enough an error will occur.

arg1 ... aggN - VARIANT-s passed to the method. Their type should be compatible with the corresponding format element in the format string. The Sprintf will try to convert each variable to the type required by the corresponding entry in the format string. If this is impossible an error will occur. 


a = "Some text"
b = 123
c = 123.456
d = Now
str = Sprintf("%s and %010d and %G",a,b,c)
Response.Write str
' will produce:
' Some text and 0000000123 and 123.456
str = Sprintf("Today is %hT",d)
Response.Write str
' will produce for instance (with the default settings):
' Today is 2004-11-20
method.gif (107 bytes) SAprintf Syntax:
str = object.SAprintf(format_spec,arr)

Returns a string using the format specification and the array elements passed to the method. The function takes an array of elements which are used in the output the same way the arguments are used in the Sprintf method.

The array (arr) must be array of VARIANT-s. The elements from it are fetched beginning from the first element (LBound) so there is no problem to use any boundaries with the array (for example 0-based and 1-based array will produce the same results as long as they contain the same elements in the same order). 


Dim a(3)
a(0) = "Some text"
a(1) = 123
a(2) = 123.456
a(3) = Now
str = Sprintf("%s and %010d and %G and today is: %hT",a)
Response.Write str
' will produce:
' Some text and 0000000123 and 123.456 and today is 2004-11-20
method.gif (107 bytes) SCprintf Syntax:
str = object.SCprintf(format_spec,col)

Returns a string using the format specification and the collection/dictionary of elements passed to the method. The function takes an object which must be a collection/dictionary. It is then used in the output the same way the arguments are used in the Sprintf method and also the usage of [name] format specification is allowed.

The col must be an object that acts like a dictionary/collection with the following features:

  • It must have a default indexed property (the name of the property is not important).
  • The property must support one of the following types for its index argument:
    • Numeric, convertible to long integer 0 or 1 based if [name] format specification is not used
    • String with element name role if the [name] format is used.

This is extremely convenient when you want to format data received in some kind of collection or dictionary object. The SCprintf works with ADO recordsets, VarDictionaries, ASP Request, Session, Application objects and many others. Having the ability to pass the received set of data directly to the function saves a lot of work. You can use both normal format string or extend some format escape commands elements with [name] (see the format specification) which will fetch a value by name from the collection instead of fetching the values sequentially (in the order in which the escape sequences are found in the format string - which is the default behavior if [name] is not used).

Note! It is not recommended to use both named and unnamed escape sequences in a single format string because of the behaviour of the function. 

Can I use other objects like the mentioned above with this method? Yes - many others! If something seems to match the above requirements it will most likely work ok. Create a few lines test code with at least 2 parameters specified to see if it will pass. 


' Suppose we have a table with some data in it in a database accessed through ADO
' the db is ADODB.Connection object connected to it
Set rst = db.Execute("SELECT Field1,Field2,Field3 FROM Table1")
str = SCprintf("Field2 is %[Field2]s Field1 is %[Field1]d and Field3 is %[Field3]T",rst)
Response.Write str
' Supposing that Field1 is integer, Field2 is text and Field3 DATE
' This will produce something like this (depending on the data in the table)
' Field2 is some text Field1 is 314 and Field3 is 2004-11-20 10:00:11

' If unnamed escapes are used (as usual) we can do a similar thing:
str = SCprintf("Field1 is %d Field2 is %s and Field3 is %T",rst)
Response.Write str
' But here we cannot reorder the results using names !!!
' They will be fetched in the order in which they appear in the recordset

str = SCprintf("Field2 is %[Field2]s Field1 is %d and Field3 is %T",rst)
Response.Write str
' Because it will (try to) in fact print for the %d the Field2 again 
' because the internal parameter index is incremented no matter if name
' is present or not.
' This behaviour is intended, because internally we allow the object that
' acts as argument supplier to choose what to use index or name.
' Currently there is no public function that benefits from this but it is 
' a rule we intend to obey.

If the object supplied as parameter can be enumerated - is this feature used?
The answer is no. Too many (but not all) collections when enumerated (For ... Each statments) enumerate the names of their elements and not the elements themselves. As this behaviour is not predictable it is hard to rely on it and it is better to use the safe and simple technique available through the default indexed property which is supported by all the collection/dictionary - like objects and always returns an element - not name of element. 

Decimal Syntax:
str = object.Decimal
object.Decimal = value

Sets or Gets the current character used as decimal point. By default it is "." (dot). This concerns the floating point numbers for example.

str = object.DateFormat
object.DateFormat = value

str = object.TimeFormat
object.TimeFormat = value

str = object.DateTimeFormat
object.DateTimeFormat = value

Each of these properties sets one of the 3 date/time formats used by the Sprintf/SAprintf functions. They correspond to:
DateTimeFormat - %T or %lT or %lt
TimeFormat - %t or %ht
DateFormat - %hT

Although the property names and their corresponding format specifications imply certain meanings (such as long date and time format, date only, time only) any valid format string can be specified. Each format string may contain up to 63 characters.

The date/time format can be specified using the syntax specified below. Each character listed below is replaced by certain part of the date or time values:

d - Day of the month, 0-padded. E.g. 3-th will be 03.
y - 2 digit year. The last 2 digits of the year.
Y - 4 digit year.
D - Day of the week. 1- digit. Sunday is 1, Monday is 2 and so on.
W - Week day name as specified by the WeekDays property.
O - Month name as specified by the Months propery.
M - Month number. 2 - digits, 0 - left padded. January is 1, February is 2 and so on.
H - Hour - 00 to 24
m - Minute 00 to 59
s - Seconds 00 to 59
h - Hour 00 to 12
p - AM/PM suffix as specified by the AM and PM properties.

Good examples are the default formats:

DateFromat = "Y-M-d"
TimeFormat = "H:m:s"
DateTimeFormat = "Y-M-d H:m:s"

To specify English date format you can do this for example:
o.DateFormat = "M/d/y"
o.DateFormat = "M/d/Y"

Or to specify 12 hour time format you can specify this:
o.TimeFormat = "h:m:s p"
Which will resolve for example to "05:20:31 am"

str = o.AM
o.AM = value

str = o.PM
o.PM = value

Specifies the AM and PM suffixes. They are used (if specified anywhere) when date/time is formatted according to the formats specified by the (TimeFormat, DateFormat and DateTimeFormat properties). The p key character is replaced with one of these suffixes according to the value of the formatted argument/element. 

The default values are "am" and "pm".

str = object.NullName
object.NullName = value

str = object.NaNName
object.NaNName = value

Get/Set the names used instead of Null and NaN (Not a number) values where applicable and allowed. When the format element allows null value to be passed in the corresponding element it puts the value specified in the NullName property if that argument/element is Null. NaN is used currently only when formatting floating point values that do not represent numbers and is rarely actually displayed. On the other hand the Null values are extremely useful when composing SQL statements or strings intended for routines that treat Null-s with special meaning. You can adjust the value placed instead of Null values to match the requirements of the DB engine or other routine.

The Default values are "Null" and "NaN"

WeekDays Indexed property.
str = object.WeekDays(index)
object.WeekDays(index) = value

Index must be between 1 and 7 where 1 is Sunday and 7 is Saturday. Using this property you can set the day names for the date formatting (see W key character in the format properties above).

By default the English names are used.

Months Indexed property.
str = object.Months(index)
object.Months(index) = value

Index must be between 1 and 12 where 1 is January and 12 is December. Using this property you can set the month names for the date formatting (see O key character in the format properties above).

By default the English names are used.

AutoFormatTypes Syntax:
str = object.AutoFormatTypes
object.AutoFormatTypes = value

Specifies the allowed formats for auto-formatting.  It is a set of characters - each corresponds to one of the type characters defined by the format specification.

The order of the type characters is important. When auto-formatted the type of each argument/element is determined and the internal list of the possible type conversions is tested against the content of this property. The first match is used. By specifying custom auto-format sequence you can control how the auto-format works.

The default value is: "diuxXgGsT"

Which means: Try integer, then unsigned integer, then general floating point, then string, then date/time format.

See the relevant parts of the format specification syntax for more information.

method.gif (107 bytes) HexToBin Syntax:
v = object.HexToBin(string)
string - hexdecimal string.

Each two characters in the string define one byte. No spaces or characters not in the hexdecimal range (0 - F) are allowed. If such character occurs it is treated as 0. The result is a variant packing a byte array (binary data) in VT_UI1 | VT_ARRAY format which can be passed to any member of an object expecting binary data as argument.

Note: It is not recommended to call the function with odd number of characters. It will work correctly, but this may cause a human mistake later. If the number of characters is odd the last character of the string corresponds to the high half-byte of the last byte in the returned data. Thus the low half-byte of the last byte will be 0. This sounds obvious, but still one may implicitly assume otherwise in a mistake, to avoid possible confusion in other coworkers try to always convert even number of characters if possible. 

method.gif (107 bytes) BinToHex Syntax:
s = object.BinToHex(v)
v - is a byte array (VT_UI1 | VT_ARRAY). For example obtained from SFStream.ReadBin, ADO field holding binary data, SFBinary data and many others.

The returned string contains the hexdecimal representation of the data where each two characters will represent one byte. The letters A-F are used (capital letters).


newObjects Copyright 2001-2006 newObjects [ ]