Library Classes

In Returned Function Values, the suggestion was made to look at the Painter class and split out repeated ideas into functions, leading to a function to prompt the user and return a double value. The same section included the example program addition2/addition2.cs. In that case there were repeated prompts for integers. Clearly another common situation is to prompt for a string. We can create functions to do all these things and more, and embed them into a class specially written for a new interactive program.

A neater thing is to put them as a class in a separate library that can be used directly for multiple programs. We can create functions PromptLine, PromptInt, and PromptDouble, and put them in their own class, UIF (for User Input First version) in project ui’s file uif.cs. We explain the namespace line after the code:

using System;

namespace IntroCS
{
/// User Input First version (bombs in Parse with mistyping)
   public class UIF
   {
      /// After displaying the prompt, return a line from the keyboard.
      public static string PromptLine(string prompt)
      {
         Console.Write(prompt);
         return Console.ReadLine();
      }

      /// After displaying the prompt,
      /// return an integer entered from the keyboard.
      public static int PromptInt(string prompt)
      {
         return int.Parse(PromptLine(prompt));
      }

      /// After displaying the prompt,
      /// return a double entered from the keyboard.
      public static double PromptDouble(string prompt)
      {
         return double.Parse(PromptLine(prompt));
      }

      /// After displaying the prompt,
      /// return  true if 'y' is entered from the keyboard
      /// and false otherwise.
      public static bool Agree(string prompt)
      {
         return "y" == PromptLine(prompt);
      }
   }
}

We have been using System in every program. System is a namespace that collects a particular group of class names, making them available to the program, and distinguishes them form any classes in a different namespace that might have the same class names.

Once we start writing and using multiple classes at once, it is a good idea for us to specify our own namespace. We will consistently use IntroCS in our multi-file examples in this book.

Specifying a namespace makes it possible for all other classes in the same namespace to reference public parts of the current class, and vice-versa.

Public classes and functions start their heading with public.

The code included in a namespace is enclosed in braces, so the general syntax is

namespace name

{

class definition(s)…

}

We will keep user input library classes like this one, uif.cs, in a project ui.

Notice that the functions we want accessible in UIF are all marked public, so that any class can use them.

We can write a modified example addition program, addition3/addition3.cs, as an example of using UIF:

using System;
namespace IntroCS
{
   class Addition3 // using UIF
   {
      /// Return a sentence stating the sum of x and y.
      static string SumProblemString(int x, int y)
      {
         int sum = x + y;
         string sentence = "The sum of " + x + " and " + y +
                           " is " + sum + ".";
         return sentence;
      }

      public static void Main()
      {
         Console.WriteLine(SumProblemString(2, 3));
         Console.WriteLine(SumProblemString(12345, 53579));
         int a = UIF.PromptInt("Enter an integer: ");
         int b = UIF.PromptInt("Enter another integer: ");
         Console.WriteLine(SumProblemString(a, b));
      }
   }
}

To allow access to UIF, we have added the IntroCS namespace for the class. To reference the static functions in the different class UIF, we put UIF. (with the dot) at the start of each reference to a static function in the class UIF.

Warning

In Xamarin Studio, if you use a file from a library project (without just copying the present version of that file into the current project), be sure that the current project includes a reference to the library project. If you expand the references in the Xamarin Studio project addition3, by clicking on the References line in the solution pad, you should see the project ui.

Shortly you will see the optional section for making your own Library Projects in Xamarin Studio (Optional).

Though we have not discussed all the C# syntax needed yet, there is also an improved class UI in the ui project that we discuss later. It includes all the function names in UIF, and keeps your program from bombing out if the user enters an illegal format for a number.

Function Documentation

In keeping with Two Roles: Writer and Consumer of Functions, in future you will be a consumer of the library classes. It is particularly important to document library classes with the interface information users will need. Documentation could be written in a separate document, but much developer history has shown that such documentation does not tend to either get written in the first place, or not updated well to stay consistent with updates in the code. Inconsistent documentation is useless. Documentation is much more likely to be seen and maintained by the implementers if it sits right with the code, like our comments before the class and function headings.

You will note that instead of the usual line comment syntax //, we have added an extra /, making ///. That will also start a comment. (The third / is technically just a part of the comment.) There is a special reason for the notation: Though it is convenient for the implementer of code to have the documentation right with the code, a user of the functions only needs the interface information found in good documentation. The /// lines before heading are specially recognized by separate automatic documentation generating programs.

There are many documentation generating programs and conventions. For now we will just use plain text in the /// lines. This is recognized by the Xamarin Studio system. If you open our examples solution, in Xamarin Studio, and edit window for addition3/addition3.cs, you can place your mouse over UIF and a popup window shows the UIF class heading documentation.

If you move the mouse over PromptInt, you should see the popup label showing the function signature and the function documentation. If you change the two /// lines in uif.cs above the PromptInt heading to start with just //. you should no longer be able to see the documentation part of the popup for PromptInt in the addition3.cs edit window. (Be sure to change back to ///.)

There are more elaborate documentation conventions that can be used for Xamarin Studio and other documentation generation programs, not discussed here.

This documentation also works inside a single program file. If you have a long program with lots of functions defined, this can also be helpful when calling one of your own functions. You can avoid jumping around to be reminded of the signature and use of your functions.

Library Projects in Xamarin Studio (Optional)

Xamarin Studio has a multi-step process for creating a library project and for separately referencing it in other projects. The advantage of this approach is when you want to change the implementation but not the interface to library functions, you just do it once, in the library project. Other projects reference that project.

Some students find the Xamarin Studio overhead of setting up and referencing library projects onerous. As a practical matter with files that you want to reuse but are not likely to change, you can just copy the source file into the new project, and avoid the Xamarin Studio library setup overhead. Many of our already created example projects use a library version of UIF and several other utility files. You can do the same with your solutions, following the instructions below, or you can just copy in the needed utility files for each project.

Hence the rest of the section here is optional:

Try adding a reference yourself. Follow these instructions:

In your own Xamarin Studio solution, start to add a project, but instead of leaving Console Project selected in the dialog window, select Library Project.
Then add the project name ui, and continue like when starting previous projects.
Copy in the .cs files from our ui project, uif.cs and ui.cs. Now you have your library project.
Create another regular Console project, addition3, in your same solution, and copy in our addition3/addition3.cs, so that is the only file.

Warning

Xamarin Studio remembers the last kind of project you created. That is fine when you are creating a sequence of Console projects. However, if you have just explicitly chosen to create a library project, the default for your next project will also be library, and really mess up your next Console project. You can fix such an error after the fact as described next.

If you created a Library project by mistake, you can either start over from scratch using the wizard again, but concentrating on making a Console project this time, or you can change the current project settings options manually:
- Double click on the project in the Solution Pad (if that does anything, or right-click it and select Options). An elaborate Project Options dialog window appears.
- In the left pane under Build, select General. In the right pane, you problably see Compile Target: Library. Change Library to Executable.
- Finally finish as in the first error fix discussed in Xamarin Studio Reminders and Fixes, so the Console is used for input and output. (You should already have the Project options displayed from the steps above.)
In the Solutions pad, in your addition3 project, click on the References entry just inside the project. You should see that the project is automatically set up to reference System.
Open the local menu for the References, and select Edit References.
Click the Projects tab in the window that pops up. This limits the length of the list that you search.
Possibly after scrolling down, find the recently made ui project and check the box beside it.
Click OK in the bottom right corner of the window. Now look at the References again. You should see ui listed!
Run your addition3 project.

You only need to add a library project once, but every further project that needs it, must have a reference to the library project added. You might try another for yourself with the next exercise!

Again this approach allows you to change the implementation of your library class in just one copy in one project, which can be referenced from many places. If you copy the file into different projects, and then decide the code needs to be updated, you are stuck finding and editing all the copies! Not good. Our library files uif.cs, ui.cs, and later fio.cs, should not be moving targets, so copying should not cause a problem. This may simplify your life, but the tradeoff is not getting used to using library references, which are useful in the larger scheme of things.

Quotient UI Exercise

Create quotient_u_i.cs by modifying quotient_return.cs in Quotient String Return Exercise so that the program accomplishes the same thing, but use the UIF class for all user input.