Understanding O.O.P. Documentation in .Net
By David M. Woods
Published October 13, 2006, 1:47 pm in Software.
Give me some Static!
Continuing in the DateTime structure object, take a look at the property called "Now," which returns the current system date and time. The signature for this member includes a very important keyword: In C#, it's called "static"; in VB, it's called "shared." This modifier means that, in order to use that member, it is not necessary to instantiate the class. Instead, you simply qualify the member name by prefacing it with the Class name and a dot. (See "Love.those.dots", above.)
The output of the "Now" property is a System.Date.Time, so as before, we'll need an appropriate object variable for that. Assuming that the "NewDate" variable has been so declared, we can implement the "Now" property with this code (VB programmers need only omit the semicolon ; at the end):
NewDate = DateTime.Now;In the above code, "DateTime" is the name of the class or structure.
Objects in the parameters
You can have bats in the belfry and slime in the ice machine, so why not objects in the parameters?
Still working in the "DateTime" object, examine the method called "Subtract". This method calculates the time interval between any two dates or times. The method has two overloaded versions; the first one that takes in a DateTime object and returns a "TimeSpan" object; the second one takes in a TimeSpan object and returns a DateTime object. We will implement the first one. The signature in C# is:
public System.TimeSpan Subtract (System.DateTime value)VB programmers, by now, should be able to extract the necessary information from the above C# signature.
First, note that the method is NOT static or shared, so we will need an instantiated object to run it. Let's assume that the DT variable, created a few steps above to represent Oct 2, 2006, exists and is ready to roll.
Secondly, we need a place to store the output, which the signature tells us is a "System.TimeSpan" object. Assuming that the "System" namespace is properly included, let's create it and call it "TS". In C#:
TimeSpan TS;VB programmers, by now, should be able to figure out how to convert C# code such as the above: add the "Dim" command; reverse the variable and class/structure names and put the keyword "as" between them; and omit the semicolon at the end.
Lastly, the signature tells us we have an object in the parameter. We need to feed the method a value of type "System.DateTime". Let's create one using the "Now" method, described earlier, and call it "DT2". In C#:
DT2 = DateTime.Now;Now we're ready. To implement the "Subtract" method in C#:
TS = DT.Subtract(DT2);Of course, you probably like to LOOK AT what the Subtract method just produced. Scroll down to the "TimeSpan" structure, and notice that it has a property called "Days", which displays the number of days in a TimeSpan. Here is the signature in C#:
public int Days [get]The output of the "Days" property is our good old friend the integer type, so let's use this. (The "[get]" annotation means that the property is read-only.) Create an integer variable called "D" to hold the results, and use the object variable "TS" we created previously. The entire code in C# is:
TS = DT.Subtract(DT2);
int D = TS.Days; Ok, you knew this was coming: let's take all of the above code and combine it into a single line, with no interim variables! Here are the steps:
1. Replace "TS" with "DT.Subtract(DT2)"
2. Replace "DT" with "new DateTime(2006, 10, 2)"
3. Replace "DT2" with "DateTime.Now"
And here's the final result in C#, a command to calculate the number of days between today and Oct 2, 2006, and store it in an integer called "D":
int D = DateTime.Now.Subtract(new DateTime(2006,10,2)).Days;Let's take a moment to review, and analyze all the dots in that expression: "Now" is a member of "DateTime"; "Subtract" is a member of "DateTime.Now"; and "Days" is a member of "DateTime.Now.Subtract()".
Constructors, or the lack thereof
The classes and structures we have looked at so far all have public constructors, but that is not always the case. Scroll up and take a look at the "TimeZone" class. Actually, it has a constructor, but it's "protected", which means we cannot invoke it externally, so it's no good to us. So how do we instantiate it?
That question can have many answers, and sometime you might have to dig a little. In the "TimeZone" class above, browse through the members, and you find a property called "CurrentTimeZone". Lo and behold, it's output type is "System.TimeZone", so it fits the bill! Furthermore, it's static (or "shared" in VB), so no pre-instantiation is necessary. But we will need to preface the property name with the class name and a dot. The code in C# to create and instantiate a variable called "TZ" is:
TimeZone TZ = TimeZone.CurrentTimeZone;Another way to instantiate object variables without constructors is via methods that do it all "behind the scenes." Database programmers may be familiar with the class "System.Data.DataSet". A common way to instantiate it is via the "Fill" method of the DataAdapter. The only thing the "Fill" method returns is an integer value which represents the number of rows added to the DataSet. But after you invoke it, the DataSet object is full of data and ready to roll; no human intervention required!
Make A Comment.