C++ Reference Material
Overview of the Instructor-Supplied Utilities Package

The instructor-supplied utilities package consists of the following three items:

  1. utilities.h (which is found on the server, and which you must #include in any source code file where you plan to use some feature found in the package)
  2. utilities.o (which is found on the server, which you link to your own .o file obtained from a source code file that included the utilities.h file and used one or more features from that utilities package)
  3. Full doxygen-generated documentation (which you study to see how the contents of the utilities package may be used)

The Linux versions of these files are found only on the server, but the documentation and some programs useful for testing are found on the website in the utilities2023 subdirectory under the Sample Code link on the CSCI 2342 course home page.

One way to find out what's in the utilities package is, of course, to study the utilities.h file directly, but for a full doxygen-generated description of all utilities package features, see here.

However, a little bit of somewhat less formal discussion might be helpful, so that's what is provided here.

The term utilities generally refers to items that serve in a supporting or auxiliary role of some kind. Such is the case with this utilities package. It contains a number of functions and classes that you would have to re-invent over and over again in some form if they did not exist. Getting familiar with the contents of this package and using what's available on a regular basis will save you a great deal of development time.

Here are some lists showing the features provided, in their various categories, with a brief and informal description of each item. Once again, though, remember that you will need to study the utilities.h file and the html documentation for more precise descriptions, and to make sure you are using any particular utility in the correct way. And be sure to study the supplied sample test programs to see some usage examples. Another thing it is critical to remember is that everything in this package is in namespace Scobey.

There are fifteen free functions defined in the utilities package. These are:

  1. ClearScreen() This free function clears the screen of a console program. See test_misc_utilities.cpp.
  2. DisplayOpeningScreen() This free function is useful for displaying the required opening screen for all course submissions of console programs. It also calls the Pause() function to provide an automatic pause at the end of that screen display. See test_displayopeningscreen.cpp.
  3. DisplayTextfile() This free function can be used to display any textfile. The point of having such a function is that we may frequently be writing C++ programs that manipulate textfiles in various ways, and it is very convenient to have the program that did the manipulation also be able to easily display the file, either before manipulation, after manipulation or creation, or both. See test_displaytextfile.cpp.
  4. gcd(...) This free function finds the greatest common divisor of two positive integers. See test_misc_utilities.cpp.
  5. isEven()This free function tests whether a positive integer is even. See test_misc_utilities.cpp.
  6. isOdd()This free function tests whether a positive integer is odd. See test_misc_utilities.cpp.
  7. numberOfDigits() This free function finds and returns the number of digits in a positive integer. See test_misc_utilities.cpp.
  8. Pause() This free function causes a console program to pause and wait for the user to press the Enter key, provided the standard input stream is empty when it is called. You may also supply a message to be displayed before the pause, and another parameter that gives the pause an ID number if you have several pauses and want them to be identified in that way. See test_pause1.cpp and test_pause2.cpp.
  9. ReadInt(), ReadDouble(), ReadChar(), ReadString(), ReadNextLine(), ReadThisLine() These free functions are all similar in purpose and usage. The idea is that you supply a prompt for the user, as well as the name of a variable in which to store a value that will be entered by the user. The function then prompts the user with the prompt you supplied, and reads in the value entered by the user in response to that prompt. Some of these functions exhibit a certain amount of "robustness" if users do not enter the requested input. See test_readfuns.cpp.
  10. userSaysYes() This boolean free function can be used to ask the user any yes-or-no type of question and return the user's response. This is a very useful utility since our programs will frequently have to get user input to decide what to do next. The question to be asked is supplied as a parameter, and the function handles all the details. See test_usersaysyes.cpp.

There are five classes defined in the utilities package. These are:

  1. Menu An object of this class allows you to easily handle the menuing chores in a console program. You simply create a menu object, give it a title, and add to it whatever menu options you need. Then at any later time you can display the menu, get the user's choice, and proceed accordingly. See test_menu1.cpp and test_menu2.cpp.
  2. OperationCounter An object of this class allows you to easily keep track of, and later display, the number of operations of various types that a program performs in carrying out some task. It is therefore particularly useful for empirical studies of algorithm performance. The operations that can be tracked are comparisons, exchanges, assignments, and one other operation of the client's choice, if desired. See test_operationcounter.cpp.
  3. RandomGenerator An object of this class allows you to generate random integer, real and string values from various ranges. It is a great timesaver when you need randomly generated data sets of various kinds and sizes (when you are testing or comparing algorithms, for example). See test_randomgenerator1.cpp and test_randomgenerator2.cpp.
  4. Stopwatch An object of this class can be used as a timer for measuring how long it takes a program to perform a particular task. The timer may be started and later stopped, and will keep track of the elapsed time, which can be obtained directly in various units. See test_stopwatch.cpp.
  5. TextItems An object of this class is particularly useful for displaying program descriptions and program instructions or other on-line help. However, it can be used just as easily to display any number of lines of text, which taken together form a logical unit of text for some purpose, and are referred to as a "text item". Hence the name of the class. Text items are placed in a file, which may contain any number of text items, and the file must be formatted in a certain way so that each text item may be identified, retrieved, and properly displayed. See test_textitems.cpp and the sample input files textitems.dat, textitems_empty.dat and textitems_short.dat.

There are also eleven named constants defined in the utilities package. These are:

  1. CARD_DECK
    A 52-element array of string objects containing 2-character representations of the cards in a deck.
  2. DAYS_OF_THE_WEEK_LONG
    A 7-element array of string objects containing the full names of the days of the week.
  3. DAYS_OF_THE_WEEK_SHORT
    A 7-element array of string objects containing 3-letter abbreviations of the days of the week.
  4. DEFAULT_PROGRAM_INFO
    A string object containing a default (generic) text, which will normally be replaced by a brief title or description, as required, in an opening screen display.
  5. DEFAULT_PROGRAMMER_INFO
    A string object containing default (generic) programmer identification information, which will normally be replaced by the programmer's own information, in an opening screen display.
  6. MONTHS_OF_THE_YEAR_LONG
    A 12-element array of string objects containing the full names of the months of the year.
  7. MONTHS_OF_THE_YEAR_SHORT
    A 12-element array of string objects containing 3-letter abbreviations of the months of the year.
  8. NAMES_3CHAR
    A 50-element array of string objects containing 3-letter (first) names, some male and some female, arranged in alphabetical order.
  9. NAMES_FAMILY
    A 100-element array of string objects containing family names (surnames), arranged in order of frequency among the US population.
  10. NAMES_FEMALE
    A 300-element array of string objects containing female first names, arranged in order of frequency among the US population.
  11. NAMES_MALE
    A 300-element array of string objects containing male first names, arranged in order of frequency among the US population.

See test_displayopeningscreen.cpp for an example using DEFAULT_PROGRAM_INFO and DEFAULT_PROGRAMMER_INFO, and test_misc_utilities.cpp for an example using some of the other defined constants.

Finally, there is one typedef defined in the utilities package, though these days there should be no need to use it. This is:

  1. String80 This is just a typedef for a character array of size 81. The extra character is for the null character that must be used to terminate a C-string, thus permitting up to 80 characters of actual data to be stored in an array of this type.