Overview | Creation
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
Threading model: Free
Methods and properties
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)
' will produce:
' Some text and 0000000123 and 123.456
str = Sprintf("Today is %hT",d)
' will produce for instance (with the default settings):
' Today is 2004-11-20
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).
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)
' will produce:
' Some text and 0000000123 and 123.456 and today is 2004-11-20
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
- 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
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
' 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)
' 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)
' But here we cannot reorder the results using names !!!
' They will be fetched in the order in which they appear in the recordset
' Never do this (NEGATIVE SAMPLE LINES FOLLOW):
str = SCprintf("Field2 is %[Field2]s Field1 is %d and Field3 is %T",rst)
' 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
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
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
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.
values are "Null" and "NaN"
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
By default the English names are used.
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
By default the English names are used.
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
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
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.
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
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
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).