Class FormatItem

This is an infrastructure class; instances represent a FormatItem found in the FormatString associated with the FormatStringParser that owns it.

The static methods of this class are public, and are very handy for creating compact summary reports.

Use them to construct composite format items that have their characteristics, especially their widths, established at runtime. Setting the width dynamically permits summary totals and their labels, all of which may have widely varying widths that are unknown in advance to be set in such a way that a set of numeric values and their labels can be printed with labels on the left, and a minimum amount of white space between the longest label and the numbers.

Inheritance
System.Object
FormatItem
Namespace: WizardWrx.FormatStringEngine
Assembly: WizardWrx.FormatStringEngine.dll
Syntax
public class FormatItem : object
Remarks

While the class, itself, is marked Public, everything else about it is marked as Internal, so that only instances of classes defined in this assembly can create instances, while instances of the FormatStringParser class expose a collection of them through its FormatItems property, a FormatItemsCollection.

Fields

| Improve this Doc View Source

APPEARANCE_ORDER_NOT_SET

The ApperanceOrder property evaluating to this value means that the property is uninitialized.

Declaration
public const uint APPEARANCE_ORDER_NOT_SET = null
Field Value
Type Description
System.UInt32
| Improve this Doc View Source

INTEGER_PER_REG_SETTINGS

Like all good array subscripts, format item indexes start at zero.

Declaration
public const string INTEGER_PER_REG_SETTINGS = null
Field Value
Type Description
System.String
| Improve this Doc View Source

INVALID_INDEX

Make the lower bound of an index visible to class consumers.

Declaration
public const int INVALID_INDEX = null
Field Value
Type Description
System.Int32
| Improve this Doc View Source

INVALID_OFFSET

Make the lower bound of a string offset visible to class consumers.

Declaration
public const int INVALID_OFFSET = null
Field Value
Type Description
System.Int32
| Improve this Doc View Source

INVALID_RAW_LENGTH

Make the lower bound of the RawLength property visible to class consumers.

Declaration
public const int INVALID_RAW_LENGTH = null
Field Value
Type Description
System.Int32
| Improve this Doc View Source

INVALID_WIDTH

Make the lower bound of the MinimumWidth property visible to class consumers.

Declaration
public const int INVALID_WIDTH = null
Field Value
Type Description
System.Int32
| Improve this Doc View Source

MINIMUM_VALID_FORMAT_ITEM_INDEX

Like all good array subscripts, format item indexes start at zero.

Declaration
public const int MINIMUM_VALID_FORMAT_ITEM_INDEX = null
Field Value
Type Description
System.Int32

Properties

| Improve this Doc View Source

AppearanceOrder

Gets the AppearanceOrder property, which is the order, counting from 1, of its appearance in the format string.

Declaration
public uint AppearanceOrder { get; }
Property Value
Type Description
System.UInt32
Remarks

This property is set when the Add method of a FormatItemsCollection object calls the SetAppearanceOrder on the instance just added. This is achieved by overriding the Add method of its base class.

| Improve this Doc View Source

Index

Gets the Index property of the item, which is the first, or only, number found within the item string.

A return value of minus one means that the Index property is uninitialized, which should be true only when the entire object is uninitialized.

Declaration
public int Index { get; }
Property Value
Type Description
System.Int32
| Improve this Doc View Source

ItemFormat

Gets or sets the optional ItemFormat property of the item.

A return value of null (Nothing in Visual Basic) means that the ItemFormat property is undefined, which is permissible, since it is optional.

Declaration
public string ItemFormat { get; set; }
Property Value
Type Description
System.String
| Improve this Doc View Source

MinimumWidth

Gets or sets the optional MinimumWidth property of the item.

A return value of zero means that the MinimumWidth property is undefined, which is permissible, since it is optional.

Declaration
public int MinimumWidth { get; set; }
Property Value
Type Description
System.Int32
Remarks

Once initialized, this property may subsequently be updated by calling the UpdateMinimumWidth method on the instance. The synopsis of the UpdateMinimumWidth method explains in greater detail.

| Improve this Doc View Source

RawLength

Gets the RawLength property, the length, in characters, of the raw format item in the format string.

A return value of zero means that the StartOffset property is uninitialized or partially initialized.

Declaration
public int RawLength { get; }
Property Value
Type Description
System.Int32
Remarks

Instance method SetRawLength is called when the closing French brace is found to set this property.

| Improve this Doc View Source

StartOffset

Gets the required StartOffset property, the offset, counting from 0, where the format item appears in the format string.

A return value of minus one means that the StartOffset property is uninitialized, which should be true only when the entire object is uninitialized.

Declaration
public int StartOffset { get; }
Property Value
Type Description
System.Int32
Remarks

This property is immutable.

| Improve this Doc View Source

TextAlignment

Gets or sets the Alignment property, if any, associated with the item.

Declaration
public FormatItem.Alignment TextAlignment { get; set; }
Property Value
Type Description
FormatItem.Alignment

Methods

| Improve this Doc View Source

AdjustItemNumberWidthPerMaxValue(String, Int32, Int32)

Replace a basic format item of the form "{n}" where "n" is the item number, with a composite item that right aligns a numeric value in a screen width that will accommodate the maximum value that will be substituted for it in the current instance.

Declaration
public static string AdjustItemNumberWidthPerMaxValue(string pstrInputFormatString, int pintItemIndex, int pintHighestValue)
Parameters
Type Name Description
System.String pstrInputFormatString

Specify the format string into which to substitute the composite format item.
System.Int32 pintItemIndex

Specify the index number of the item to be replaced. The string must contain a format item "{pintItemIndex}" which is replaced.
System.Int32 pintHighestValue

Specify the highest value that you expect to substitute for format item {pintItemIndex} such as the Count property of an array that holds items to be listed.
Returns
Type Description
System.String

A new string is returned, with format item {pintItemIndex} replaced with {pintItemIndex,m:N0}, where m = the minimum width required to display pintHighestValue using the numeric formatting defined by the current Region and Language settings in the Windows Control Panel, overriding the decimal places value with a value of zero.
| Improve this Doc View Source

AdjustItemNumberWidthPerMaxValue(String, Int32, UInt32)

Replace a basic format item of the form "{n}" where "n" is the item number, with a composite item that right aligns a numeric value in a screen width that will accommodate the maximum value that will be substituted for it in the current instance.

Declaration
public static string AdjustItemNumberWidthPerMaxValue(string pstrInputFormatString, int pintItemIndex, uint puintHighestValue)
Parameters
Type Name Description
System.String pstrInputFormatString

Specify the format string into which to substitute the composite format item.
System.Int32 pintItemIndex

Specify the index number of the item to be replaced. The string must contain a format item "{pintItemIndex}" which is replaced.
System.UInt32 puintHighestValue

Specify the highest value that you expect to substitute for format item {pintItemIndex} such as the Count property of an array that holds items to be listed.
Returns
Type Description
System.String

A new string is returned, with format item {pintItemIndex} replaced with {pintItemIndex,m:N0}, where m = the minimum width required to display pintHighestValue using the numeric formatting defined by the current Region and Language settings in the Windows Control Panel, overriding the decimal places value with a value of zero.
| Improve this Doc View Source

AdjustItemNumberWidthPerMaxValue(String, Int32, FormatItem.Alignment, Int32, String)

Replace a basic format item of the form "{n}" where "n" is the item number, with a composite item that right aligns a numeric value in a screen width that will accommodate the maximum value that will be substituted for it in the current instance.

Declaration
public static string AdjustItemNumberWidthPerMaxValue(string pstrFormat, int pintItemIndex, FormatItem.Alignment penmAlignment, int pintMaximumWidth, string pstrFormatString)
Parameters
Type Name Description
System.String pstrFormat

Specify a valid format string to upgrade. The string must contain a token of the form {n}, where n is equal to pintItemIndex.
System.Int32 pintItemIndex

Specify the index of the item to be upgraded. The integer must be positive, and pstrFormat must contain at least once instance of a correspondingly numbered format item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.Int32 pintMaximumWidth

The maximum width is a positive integer that specifies the desired width of the item.
System.String pstrFormatString

Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.
Returns
Type Description
System.String

The return value is a new format control string, with the original vanilla format item at the specified index replaced with a new one that has its width adjusted precisely to accommodate the widest expected value.
| Improve this Doc View Source

AdjustItemNumberWidthPerMaxValue(String, UInt32, Int32)

Replace a basic format item of the form "{n}" where "n" is the item number, with a composite item that right aligns a numeric value in a screen width that will accommodate the maximum value that will be substituted for it in the current instance.

Declaration
public static string AdjustItemNumberWidthPerMaxValue(string pstrInputFormatString, uint puintItemIndex, int pintHighestValue)
Parameters
Type Name Description
System.String pstrInputFormatString

Specify the format string into which to substitute the composite format item.
System.UInt32 puintItemIndex

Specify the index number of the item to be replaced. The string must contain a format item "{pintItemIndex}" which is replaced.
System.Int32 pintHighestValue

Specify the highest value that you expect to substitute for format item {pintItemIndex} such as the Count property of an array that holds items to be listed.
Returns
Type Description
System.String

A new string is returned, with format item {pintItemIndex} replaced with {pintItemIndex,m:N0}, where m = the minimum width required to display pintHighestValue using the numeric formatting defined by the current Region and Language settings in the Windows Control Panel, overriding the decimal places value with a value of zero.
| Improve this Doc View Source

AdjustItemNumberWidthPerMaxValue(String, UInt32, UInt32)

Replace a basic format item of the form "{n}" where "n" is the item number, with a composite item that right aligns a numeric value in a screen width that will accommodate the maximum value that will be substituted for it in the current instance.

Declaration
public static string AdjustItemNumberWidthPerMaxValue(string pstrInputFormatString, uint puintItemIndex, uint puintHighestValue)
Parameters
Type Name Description
System.String pstrInputFormatString

Specify the format string into which to substitute the composite format item.
System.UInt32 puintItemIndex

Specify the index number of the item to be replaced. The string must contain a format item "{pintItemIndex}" which is replaced.
System.UInt32 puintHighestValue

Specify the highest value that you expect to substitute for format item {pintItemIndex} such as the Count property of an array that holds items to be listed.
Returns
Type Description
System.String

A new string is returned, with format item {pintItemIndex} replaced with {pintItemIndex,m:N0}, where m = the minimum width required to display pintHighestValue using the numeric formatting defined by the current Region and Language settings in the Windows Control Panel, overriding the decimal places value with a value of zero.
| Improve this Doc View Source

AdjustToMaximumWidth(Int32, Int32, FormatItem.Alignment, String)

Assemble a composite format item from its constituents.

Declaration
public static string AdjustToMaximumWidth(int pintItemIndex, int pintMaximumWidth, FormatItem.Alignment penmAlignment, string pstrFormatString)
Parameters
Type Name Description
System.Int32 pintItemIndex

The index is a standard zero based array subscript which corresponds to the position of an item in a list of objects. The list happens to be the items that correspond to the format items in a format string.
System.Int32 pintMaximumWidth

The maximum width is a positive integer that specifies the desired width of the item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.
Returns
Type Description
System.String

The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

The safest way to insert it into a format string is by calling a companion method, UpgradeFormatItem, which expects a format string, puintItemIndex, and the string returned by this method.
| Improve this Doc View Source

AdjustToMaximumWidth(Int32, UInt32, FormatItem.Alignment, String)

Assemble a composite format item from its constituents.

Declaration
public static string AdjustToMaximumWidth(int pintItemIndex, uint puintMaximumWidth, FormatItem.Alignment penmAlignment, string pstrFormatString)
Parameters
Type Name Description
System.Int32 pintItemIndex

The index is a standard zero based array subscript which corresponds to the position of an item in a list of objects. The list happens to be the items that correspond to the format items in a format string.
System.UInt32 puintMaximumWidth

The maximum width is a positive integer that specifies the desired width of the item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.
Returns
Type Description
System.String

The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

The safest way to insert it into a format string is by calling a companion method, UpgradeFormatItem, which expects a format string, puintItemIndex, and the string returned by this method.
| Improve this Doc View Source

AdjustToMaximumWidth(UInt32, Int32, FormatItem.Alignment, String)

Assemble a composite format item from its constituents.

Declaration
public static string AdjustToMaximumWidth(uint puintItemIndex, int pintMaximumWidth, FormatItem.Alignment penmAlignment, string pstrFormatString)
Parameters
Type Name Description
System.UInt32 puintItemIndex

The index is a standard zero based array subscript which corresponds to the position of an item in a list of objects. The list happens to be the items that correspond to the format items in a format string.
System.Int32 pintMaximumWidth

The maximum width is a positive integer that specifies the desired width of the item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.
Returns
Type Description
System.String

The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

The safest way to insert it into a format string is by calling a companion method, UpgradeFormatItem, which expects a format string, puintItemIndex, and the string returned by this method.
| Improve this Doc View Source

AdjustToMaximumWidth(UInt32, UInt32, FormatItem.Alignment, String)

Assemble a composite format item from its constituents.

Declaration
public static string AdjustToMaximumWidth(uint puintItemIndex, uint puintMaximumWidth, FormatItem.Alignment penmAlignment, string pstrFormatString)
Parameters
Type Name Description
System.UInt32 puintItemIndex

The index is a standard zero based array subscript which corresponds to the position of an item in a list of objects. The list happens to be the items that correspond to the format items in a format string.
System.UInt32 puintMaximumWidth

The maximum width is a positive integer that specifies the desired width of the item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.
Returns
Type Description
System.String

The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

The safest way to insert it into a format string is by calling a companion method, UpgradeFormatItem, which expects a format string, puintItemIndex, and the string returned by this method.
| Improve this Doc View Source

IntegerPerRegSettings()

Return a string suitable for formatting an integer per the Regional Settings, overriding the default number of digits to display to the right of the decimal point to display zero digits to the right of the decimal point.

Declaration
public static string IntegerPerRegSettings()
Returns
Type Description
System.String

Format string suitable for formatting an integer
See Also
| Improve this Doc View Source

UpgradeFormatItem(String, Int32, String)

Upgrade a plain vanilla format item of the form {n}, where n is the number of a format item that exists somewhere in a format string to a composite string that specifies a width that is computed at run time to be appropriate to the current data set.

Declaration
public static string UpgradeFormatItem(string pstrFormat, int pintItemIndex, string pstrUpgrade)
Parameters
Type Name Description
System.String pstrFormat

Specify a valid format string to upgrade. The string must contain a token of the form {n}, where n is equal to pintItemIndex.
System.Int32 pintItemIndex

Specify the index of the item to be upgraded. The integer must be positive, and pstrFormat must contain at least once instance of a correspondingly numbered format item.
System.String pstrUpgrade

Specify the upgraded format item, such as the string returned by the static AdjustToMaximumWidth method of this class.

Contrast this with pstrFormatString, which expects you to supply a standard or custom Numeric or DateTime format string, from which it constructs a complete, well formed Format Item.
Returns
Type Description
System.String

If the function succeeds, the return value is the upgraded format string, in which the indicated plain vanilla format item has been replaced with a dynamically generated composite format item.
Remarks

This routine expends a good deal of effort to validate its inputs, so that it can be safely used to process user input, such as data read into the program from a configuration file.

| Improve this Doc View Source

UpgradeFormatItem(String, Int32, FormatItem.Alignment, String, String[])

Upgrade a plain vanilla format item of the form {n}, where n is the number of a format item that exists somewhere in a format string to a composite string that specifies a width that is computed at run time to be appropriate to the current data set.

Declaration
public static string UpgradeFormatItem(string pstrFormat, int pintItemIndex, FormatItem.Alignment penmAlignment, string pstrFormatString, string[] pastrValueArray)
Parameters
Type Name Description
System.String pstrFormat

Specify a valid format string to upgrade. The string must contain a token of the form {n}, where n is equal to pintItemIndex.
System.Int32 pintItemIndex

Specify the index of the item to be upgraded. The integer must be positive, and pstrFormat must contain at least once instance of a correspondingly numbered format item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a standard or custom Numeric or DateTime format string.

Contrast this with pstrUpgrade, which expects you to supply the entire format item, ready for substitution.
System.String[] pastrValueArray

Specify an array of strings, all of which are values intended to be formatted by the upgraded format item. This routine determines the length of the longest string, which becomes the basis of the alignment parameter inserted into the upgraded format item.
Returns
Type Description
System.String

If the function succeeds, the return value is the upgraded format string, in which the indicated plain vanilla format item has been replaced with a dynamically generated composite format item.
| Improve this Doc View Source

UpgradeFormatItem(String, UInt32, String)

Upgrade a plain vanilla format item of the form {n}, where n is the number of a format item that exists somewhere in a format string to a composite string that specifies a width that is computed at run time to be appropriate to the current data set.

Declaration
public static string UpgradeFormatItem(string pstrFormat, uint puintItemIndex, string pstrUpgrade)
Parameters
Type Name Description
System.String pstrFormat

Specify a valid format string to upgrade. The string must contain a token of the form {n}, where n is equal to puintItemIndex.
System.UInt32 puintItemIndex

Specify the index of the item to be upgraded. The integer must be positive, and pstrFormat must contain at least once instance of a correspondingly numbered format item.
System.String pstrUpgrade

Specify the upgraded format item, such as the string returned by the static AdjustToMaximumWidth method of this class.

Contrast this with pstrFormatString, which expects you to supply a standard or custom Numeric or DateTime format string, from which it constructs a complete, well formed Format Item.
Returns
Type Description
System.String

If the function succeeds, the return value is the upgraded format string, in which the indicated plain vanilla format item has been replaced with a dynamically generated composite format item.
Remarks

This routine expends a good deal of effort to validate its inputs, so that it can be safely used to process user input, such as data read into the program from a configuration file.

| Improve this Doc View Source

UpgradeFormatItem(String, UInt32, FormatItem.Alignment, String, List<String>)

Upgrade a plain vanilla format item of the form {n}, where n is the number of a format item that exists somewhere in a format string to a composite string that specifies a width that is computed at run time to be appropriate to the current data set.

Declaration
public static string UpgradeFormatItem(string pstrFormat, uint puintItemIndex, FormatItem.Alignment penmAlignment, string pstrFormatString, List<string> pastrValueArray)
Parameters
Type Name Description
System.String pstrFormat

Specify a valid format string to upgrade. The string must contain a token of the form {n}, where n is equal to pintItemIndex.
System.UInt32 puintItemIndex

Specify the index of the item to be upgraded. The integer must be positive, and pstrFormat must contain at least once instance of a correspondingly numbered format item.
FormatItem.Alignment penmAlignment

Specify Left or Right. Center alignment is unsupported, although it could be achieved with custom code.
System.String pstrFormatString

Specify a standard or custom Numeric or DateTime format string.

Contrast this with pstrUpgrade, which expects you to supply the entire format item, ready for substitution.
List<System.String> pastrValueArray

Specify an array of strings, all of which are values intended to be formatted by the upgraded format item. This routine determines the length of the longest string, which becomes the basis of the alignment parameter inserted into the upgraded format item.
Returns
Type Description
System.String

If the function succeeds, the return value is the upgraded format string, in which the indicated plain vanilla format item has been replaced with a dynamically generated composite format item.
| Improve this Doc View Source

XofY(Int32, Int32)

Given two integral values X and Y, where X is less than or equal to Y, return a string of the form "X of Y" for use on a report.

Declaration
public static string XofY(int pintX, int pintY)
Parameters
Type Name Description
System.Int32 pintX

X is the ordinal number of the item in the list, expressed as a signed integer.
System.Int32 pintY

Y is the total number of items in the list, expressed as a signed integer.
Returns
Type Description
System.String

The returned string is literally "X of Y," where X and Y are the two integers representing, respectively, the current item number and the total number of items in the set. The formatting of X and Y is such that a list is guaranteed to be vertically aligned, because X is set in a right aligned field whose width is the same as that of a string representation of Y.
| Improve this Doc View Source

XofY(Int32, UInt32)

Given two integral values X and Y, where X is less than or equal to Y, return a string of the form "X of Y" for use on a report.

Declaration
public static string XofY(int pintX, uint puintY)
Parameters
Type Name Description
System.Int32 pintX

X is the ordinal number of the item in the list, expressed as a signed integer.
System.UInt32 puintY

Y is the total number of items in the list, expressed as an unsigned integer.
Returns
Type Description
System.String

The returned string is literally "X of Y," where X and Y are the two integers representing, respectively, the current item number and the total number of items in the set. The formatting of X and Y is such that a list is guaranteed to be vertically aligned, because X is set in a right aligned field whose width is the same as that of a string representation of Y.
| Improve this Doc View Source

XofY(UInt32, Int32)

Given two integral values X and Y, where X is less than or equal to Y, return a string of the form "X of Y" for use on a report.

Declaration
public static string XofY(uint puintX, int pintY)
Parameters
Type Name Description
System.UInt32 puintX

X is the ordinal number of the item in the list, expressed as an unsigned integer.
System.Int32 pintY

Y is the total number of items in the list, expressed as a signed integer.
Returns
Type Description
System.String

The returned string is literally "X of Y," where X and Y are the two integers representing, respectively, the current item number and the total number of items in the set. The formatting of X and Y is such that a list is guaranteed to be vertically aligned, because X is set in a right aligned field whose width is the same as that of a string representation of Y.
| Improve this Doc View Source

XofY(UInt32, UInt32)

Given two integral values X and Y, where X is less than or equal to Y, return a string of the form "X of Y" for use on a report.

Declaration
public static string XofY(uint puintX, uint puintY)
Parameters
Type Name Description
System.UInt32 puintX

X is the ordinal number of the item in the list, expressed as an unsigned integer.
System.UInt32 puintY

Y is the total number of items in the list, expressed as an unsigned integer.
Returns
Type Description
System.String

The returned string is literally "X of Y," where X and Y are the two integers representing, respectively, the current item number and the total number of items in the set. The formatting of X and Y is such that a list is guaranteed to be vertically aligned, because X is set in a right aligned field whose width is the same as that of a string representation of Y.