From f6f7cde267a29f164d41c292bc0a5de5c4de27e5 Mon Sep 17 00:00:00 2001 From: Zong Zheng Li Date: Tue, 30 Jul 2013 04:10:37 -0400 Subject: [PATCH] Document Format class New: documentation for all Format methods Fix: typos in documentation for Terminal --- Source/Utilities/Format.cs | 110 +++++++++++++++++++++++++++++------ Source/Utilities/Terminal.cs | 8 +-- 2 files changed, 97 insertions(+), 21 deletions(-) diff --git a/Source/Utilities/Format.cs b/Source/Utilities/Format.cs index 5dcedea..7c169ff 100644 --- a/Source/Utilities/Format.cs +++ b/Source/Utilities/Format.cs @@ -2,8 +2,19 @@ using System.Text; namespace AbsoluteZero { + + /// + /// Provides string formatting methods. + /// static class Format { + /// + /// Returns a string of the given length consisting entirely of the given + /// character. If a character is not specified the space character is used. + /// + /// The length of the string. + /// The character that is repeated to produce the string. + /// A string of the given length consisting entirely of the given character. public static String Pad(Int32 length, Char character = ' ') { Char[] pad = new Char[length]; for (Int32 i = 0; i < pad.Length; i++) @@ -11,32 +22,83 @@ public static String Pad(Int32 length, Char character = ' ') { return new String(pad); } - public static String PadRight(String value, Int32 width, Char character = ' ') { - Int32 length = Math.Max(0, width - value.Length); - return value + Pad(length); + /// + /// Pads the right side of the given string with the given character so that + /// the resultant string is of the given length. If a character is not + /// specified the space character is used. + /// + /// The value to pad. + /// The length of the padded string. + /// The character that is repeated to pad the string. + /// The given value padded to the given length with the given character. + public static String PadRight(String value, Int32 length, Char character = ' ') { + Int32 len = Math.Max(0, length - value.Length); + return value + Pad(len); } - public static String PadRight(Object value, Int32 width, Char character = ' ') { - return PadRight(value.ToString(), width, character); + /// + /// Pads the right side of the text representation of the given object with + /// the given character so that the resultant string is of the given length. + /// If a character is not specified the space character is used. + /// + /// The value to pad. + /// The length of the padded string. + /// The character that is repeated to pad the string. + /// The given value padded to the given length with the given character. + public static String PadRight(Object value, Int32 length, Char character = ' ') { + return PadRight(value.ToString(), length, character); } - public static String PadRightAll(Int32 width, params Object[] values) { - StringBuilder sequence = new StringBuilder(width * values.Length); + /// + /// Pads the right side of all of the text representations of the given + /// objects with spaces until they are each of the given length and then + /// concatenates them together. + /// + /// The length of each of the padded strings. + /// The values to pad. + /// The concatenation of all the given values padded to the right with spaces. + public static String PadRightAll(Int32 length, params Object[] values) { + StringBuilder sequence = new StringBuilder(length * values.Length); for (Int32 i = 0; i < values.Length - 1; i++) - sequence.Append(PadRight(values[i], width)); + sequence.Append(PadRight(values[i], length)); sequence.Append(values[values.Length - 1]); return sequence.ToString(); } - - public static String PadLeft(String value, Int32 width, Char character = ' ') { - Int32 length = Math.Max(0, width - value.Length); - return Pad(length) + value; + + /// + /// Pads the left side of the given string with the given character so that + /// the resultant string is of the given length. If a character is not + /// specified the space character is used. + /// + /// The value to pad. + /// The length of the padded string. + /// The character that is repeated to pad the string. + /// The given value padded to the given length with the given character. + public static String PadLeft(String value, Int32 length, Char character = ' ') { + Int32 len = Math.Max(0, length - value.Length); + return Pad(len) + value; } - public static String PadLeft(Object value, Int32 width, Char character = ' ') { - return PadLeft(value.ToString(), width, character); + /// + /// Pads the left side of the text representation of the given object with + /// the given character so that the resultant string is of the given length. + /// If a character is not specified the space character is used. + /// + /// The value to pad. + /// The length of the padded string. + /// The character that is repeated to pad the string. + /// The given value padded to the given length with the given character. + public static String PadLeft(Object value, Int32 length, Char character = ' ') { + return PadLeft(value.ToString(), length, character); } - + + /// + /// Returns a string that is the given floating point value rounded to the + /// specified number of decimal digits. + /// + /// The value to round. + /// The number of decimal digits to round to. + /// A string that is the given value rounded to the specified number of decimal digits. public static String Precision(Double value, Int32 digits = 0) { Double result = Math.Round(value, digits, MidpointRounding.AwayFromZero); if (digits > 0) @@ -44,13 +106,27 @@ public static String Precision(Double value, Int32 digits = 0) { return result.ToString(); } + /// + /// Returns a string that is the given floating point value rounded to the + /// specified number of decimal digits with its sign explicitedly stated. + /// This method gives zero a positive sign. + /// + /// The value to format. + /// The number of decimal digits to format to. + /// A string that is the given value rounded to the specified number of decimal digits with an explicit sign. public static String PrecisionAndSign(Double value, Int32 digits = 0) { String result = Precision(value, digits); - return result[0] == '-' ? result : '+' + result; + return (result[0] == '-') ? result : '+' + result; } + /// + /// Returns a string that is the given integer with its sign explicitedly + /// stated. This method gives zero a positive sign. + /// + /// The value to format. + /// A string that is the given integer with an explicit sign. public static String Sign(Int64 value) { - return value < 0 ? value.ToString() : "+" + value; + return (value < 0) ? value.ToString() : "+" + value; } } } diff --git a/Source/Utilities/Terminal.cs b/Source/Utilities/Terminal.cs index 361aab6..5e9daf1 100644 --- a/Source/Utilities/Terminal.cs +++ b/Source/Utilities/Terminal.cs @@ -45,8 +45,8 @@ public static void Write(String value) { } /// - /// Writes the text representation of the specified object string to the - /// standard output stream. + /// Writes the text representation of the specified object to the standard + /// output stream. /// /// The value to write. public static void Write(Object value) { @@ -64,8 +64,8 @@ public static void WriteLine(String value = "") { } /// - /// Writes the text representation of the specified object string, followed - /// by the current line terminator, to the standard output stream. + /// Writes the text representation of the specified object, followed by the + /// current line terminator, to the standard output stream. /// /// The value to write. public static void WriteLine(Object value) {