class Menu
class OperationCounter
class RandomGenerator
class Stopwatch
class TextItems
1: /** @file utilities.h
2: Header file corresponding to utilities.cpp and utilities.obj, and
3: containing specifications for the facilities in namespace Scobey.
5: @author P. %Scobey
6: @date Monday, July 28, 2008
7: @version 2008.0
9: The source code that makes use of this utilities package must include
10: this header file and link to the corresponding object file (which
11: is called utilities.obj under Windows XP, for example).
13: The package contains features on four categories, as listed below.
15: One typedef
16: - String80
18: Eleven named constants:
19: - CARD_DECK
20: - DAYS_OF_THE_WEEK_LONG
21: - DAYS_OF_THE_WEEK_SHORT
22: - DEFAULT_PROGRAMMER_INFO
23: - DEFAULT_PROGRAM_INFO
24: - MONTHS_OF_THE_YEAR_LONG
25: - MONTHS_OF_THE_YEAR_SHORT
26: - NAMES_3CHAR
27: - NAMES_FEMALE
28: - NAMES_MALE
29: - NAMES_FAMILY
31: Fifteen free functions:
32: - ClearScreen
33: - DisplayOpeningScreen (inline)
34: - DisplayTextfile
35: - gcd
36: - isEven
37: - isOdd
38: - numberOfDigits
39: - Pause
40: - ReadChar
41: - ReadDouble
42: - ReadInt
43: - ReadNextLine
44: - ReadThisLine
45: - ReadString
46: - userSaysYes
48: Note that each member of the Read* sequence of free functions
49: in the list above provides the same kind of service: it prompts
50: for, and then reads in, from the standard input, a single value
51: of the type suggested by the function name. Only ReadInt and
52: ReadDouble contain error checking, and each continues to prompt
53: the user for a value of the correct type if one is not entered
54: on the first attempt.
56: Five utility classes:
57: - Menu
58: - OperationCounter
59: - RandomGenerator
60: - Stopwatch
61: - TextItems
62: */
64: /**
65: @mainpage
66: This is the Fall, 2008 version of the documentation for the
67: instructor-supplied C++ utilities package to be used in CSCI 2341
68: and CSCI 2342. You will find here descriptions of some very useful
69: (time-saving) constant definitions, free functions, and classes.
70: It will take some time to become thoroughly familiar with all that
71: is available, but you need to start using the package immediately
72: and learn some new facilities each week as the term progresses.
73: @section whatsnew_sec What's New
74: Those who are familiar with this utilities package from last year
75: should note the changes and additions listed below. Those who may
76: have used it previous to that will find more significant changes and
77: they should review the documentation in its entirety, as should those
78: who are encountering the package for the first time.
79: -# The DisplayIDInfo() free function has been renamed DisplayOpeningScreen(),
80: but retains essentially the same functionality. This function is also now
81: an inline function, which helps to avoid multiply-defined function name
82: compile-time errors when utilities.h is included in several different source
83: files of the same program. The two named constants which provide values for
84: the default parameters of the DisplayOpeningScreen() function have also been
85: renamed: DEFAULT_DESCRIPTION is now called DEFAULT_PROGRAM_INFO, and
86: DEFAULT_ID_INFO is now called DEFAULT_PROGRAMMER_INFO.
87: -# There is a new ClearScreen() function that clears the screen and positions
88: the cursor to write at the bottom left corner of the screen. This a portable
89: function that works simply by writing blank lines to the screen.
90: -# The ReadLine() free function has been replaced by two very similar
91: free functions, the ReadNextLine() function and the ReadThisLine() function.
92: The ReadNextLine() function displays a prompt and moves the cursor to the
93: next line for the user to enter as much as a full line of text, while the
94: ReadThisLine() function displays a prompt and keeps the cursor on the same
95: line as that prompt so that the user can enter (a presumably shorter piece
96: of) text on the same line as the prompt. Note that the ReadNextLine()
97: function has exactly the same functionality as the previous ReadLine()
98: function. In both cases all text entered, except the terminating newline
99: character, is read into the string variable receiving the input.
100: -# There are three new constant arrays containing names: one containing
101: 300 first names for females, one containing 300 first names for males,
102: and one containing 100 family names, all ranked in the order of name
103: frequency as observed in the United States and reported on the Internet
104: at these sites:
105: <br>www.census.gov/genealogy/names/dist.female.first
106: <br>names.mongabay.com/male_names_alpha.htm
107: <br>en.wikipedia.org/wiki/List_of_most_common_surnames#United_States
108: */
110: #ifndef UTILITIES_H
111: #define UTILITIES_H
113: #include <iostream>
114: #include <cstdlib>
115: #include <ctime>
116: #include <string>
117: #include <vector>
118: using std::cout;
119: using std::string;
120: using std::vector;
122: /**
123: Contains one typedef, eleven named constants,
124: fifteen free functions, and five utility classes.
125: */
126: namespace Scobey
127: {
129: //************************************************************************
130: //Typedef Section
132: typedef char String80[81];
133: /**<
134: Provides a legacy C-string type for holding up to 80 characters of text.
135: */
137: //
138: //
139: //************************************************************************
140: //Named Constant Section
142: const string CARD_DECK[] =
143: { "AS", "2S", "3S", "4S", "5S", "6S", "7S",
144: "8S", "9S", "TS", "JS", "QS", "KS",
145: "AH", "2H", "3H", "4H", "5H", "6H", "7H",
146: "8H", "9H", "TH", "JH", "QH", "KH",
147: "AD", "2D", "3D", "4D", "5D", "6D", "7D",
148: "8D", "9D", "TD", "JD", "QD", "KD",
149: "AC", "2C", "3C", "4C", "5C", "6C", "7C",
150: "8C", "9C", "TC", "JC", "QC", "KC"
151: };
152: /**<
153: Provides 2-character representations of each of the fifty-two cards
154: in a standard deck of cards.
155: */
158: const string DAYS_OF_THE_WEEK_LONG[] =
159: { "Monday", "Tuesday", "Wednesday", "Thursday",
160: "Friday", "Saturday", "Sunday"
161: };
162: /**<
163: Provides full names for days of the week.
164: */
167: const string DAYS_OF_THE_WEEK_SHORT[] =
168: { "Mon", "Tue", "Wed", "Thu",
169: "Fri", "Sat", "Sun"
170: };
171: /**<
172: Provides 3-letter abbreviations for days of the week.
173: */
176: const string DEFAULT_PROGRAM_INFO =
177: "Descriptive text required here is specificed elsewhere.";
178: /**<
179: Provides a placeholder value for a program title or brief description.
180: */
183: const string DEFAULT_PROGRAMMER_INFO =
184: "Lastname:Firstname:A00123456:CSC?????";
185: /**<
186: Provides a placeholder value for programmer identification information.
187: */
190: const string MONTHS_OF_THE_YEAR_LONG[] =
191: { "January", "February", "March", "April",
192: "May", "June", "July", "August",
193: "September", "October", "November", "December"
194: };
195: /**<
196: Provides full names for months of the year.
197: */
200: const string MONTHS_OF_THE_YEAR_SHORT[] =
201: { "Jan", "Feb", "Mar", "Apr", "May", "Jun",
202: "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
203: };
204: /**<
205: Provides 3-letter abbreviations for months of the year.
206: */
209: const string NAMES_3CHAR[] =
210: { "Ace", "Ali", "Amy", "Ann", "Art",
211: "Ben", "Bob", "Cal", "Dan", "Del",
212: "Don", "Dot", "Eva", "Eve", "Fay",
213: "Gil", "Guy", "Hal", "Ian", "Jan",
214: "Jim", "Jon", "Kay", "Ken", "Kim",
215: "Liz", "Mac", "Min", "Nan", "Ora",
216: "Pam", "Red", "Rex", "Rik", "Rip",
217: "Rob", "Rod", "Rog", "Ron", "Roy",
218: "Sal", "Sam", "Sue", "Tad", "Tim",
219: "Tom", "Uma", "Val", "Wes", "Zig"
220: };
221: /**<
222: Provides fifty 3-character first names, some male and some female,
223: in alphabetical order.
224: */
227: const string NAMES_FAMILY[] =
228: { "Smith", "Johnson", "Williams", "Brown", "Jones",
229: "Miller", "Davis", "Garcia", "Rodriguez", "Wilson",
230: "Martinez", "Anderson", "Taylor", "Thomas", "Hernandez",
231: "Moore", "Martin", "Jackson", "Thompson", "White",
232: "Lopez", "Le", "Gonzalez", "Harris", "Clark",
233: "Lewis", "Robinson", "Walker", "Perez", "Hall",
234: "Young", "Allen", "Sanchez", "Wright", "King",
235: "Scott", "Green", "Baker", "Adams", "Nelson",
236: "Hill", "Ramirez", "Campbell", "Mitchell", "Roberts",
237: "Carter", "Phillips", "Evans", "Turner", "Torres",
238: "Parker", "Collins", "Edwards", "Stewart", "Flores",
239: "Morris", "Nguyen", "Murphy", "Rivera", "Cook",
240: "Rogers", "Morgan", "Peterson", "Cooper", "Reed",
241: "Bailey", "Bell", "Gomez", "Kelly", "Howard",
242: "Ward", "Cox", "Diaz", "Richardson", "Wood",
243: "Watson", "Brooks", "Bennett", "Gray", "James",
244: "Reyes", "Cruz", "Hughes", "Price", "Myers",
245: "Long", "Foster", "Sanders", "Ross", "Morales",
246: "Powell", "Sullivan", "Russell", "Ortiz", "Jenkins",
247: "Gutierrez", "Perry", "Butler", "Barnes", "Fisher"
248: };
249: /**<
250: Provides 100 family names (surnames), ranked in order of frequency
251: as found in the United States of America.
252: */
255: const string NAMES_FEMALE[] =
256: { "Mary", "Patricia", "Linda", "Barbara", "Elizabeth", "Jennifer",
257: "Maria", "Susan", "Margaret", "Dorothy", "Lisa", "Nancy",
258: "Karen", "Betty", "Helen", "Sandra", "Donna", "Carol",
259: "Ruth", "Sharon", "Michelle", "Laura", "Sarah", "Kimberly",
260: "Deborah", "Jessica", "Shirley", "Cynthia", "Angela", "Melissa",
261: "Brenda", "Amy", "Anna", "Rebecca", "Virginia", "Kathleen",
262: "Pamela", "Martha", "Debra", "Amanda", "Stephanie", "Carolyn",
263: "Christine", "Marie", "Janet", "Catherine", "Frances", "Ann",
264: "Joyce", "Diane", "Alice", "Julie", "Heather", "Teresa",
265: "Doris", "Gloria", "Evelyn", "Jean", "Cheryl", "Mildred",
266: "Katherine", "Joan", "Ashley", "Judith", "Rose", "Janice",
267: "Kelly", "Nicole", "Judy", "Christina", "Kathy", "Theresa",
268: "Beverly", "Denise", "Tammy", "Irene", "Jane", "Lori",
269: "Rachel", "Marilyn", "Andrea", "Kathryn", "Louise", "Sara",
270: "Anne", "Jacqueline", "Wanda", "Bonnie", "Julia", "Ruby",
271: "Lois", "Tina", "Phyllis", "Norma", "Paula", "Diana",
272: "Annie", "Lillian", "Emily", "Robin", "Peggy", "Crystal",
273: "Gladys", "Rita", "Dawn", "Connie", "Florence", "Tracy",
274: "Edna", "Tiffany", "Carmen", "Rosa", "Cindy", "Grace",
275: "Wendy", "Victoria", "Edith", "Kim", "Sherry", "Sylvia",
276: "Josephine", "Thelma", "Shannon", "Sheila", "Ethel", "Ellen",
277: "Elaine", "Marjorie", "Carrie", "Charlotte", "Monica", "Esther",
278: "Pauline", "Emma", "Juanita", "Anita", "Rhonda", "Hazel",
279: "Amber", "Eva", "Debbie", "April", "Leslie", "Clara",
280: "Lucille", "Jamie", "Joanne", "Eleanor", "Valerie", "Danielle",
281: "Megan", "Alicia", "Suzanne", "Michele", "Gail", "Bertha",
282: "Darlene", "Veronica", "Jill", "Erin", "Geraldine", "Lauren",
283: "Cathy", "Joann", "Lorraine", "Lynn", "Sally", "Regina",
284: "Erica", "Beatrice", "Dolores", "Bernice", "Audrey", "Yvonne",
285: "Annette", "June", "Samantha", "Marion", "Dana", "Stacy",
286: "Ana", "Renee", "Ida", "Vivian", "Roberta", "Holly",
287: "Brittany", "Melanie", "Loretta", "Yolanda", "Jeanette", "Laurie",
288: "Katie", "Kristen", "Vanessa", "Alma", "Sue", "Elsie",
289: "Beth", "Jeanne", "Vicki", "Carla", "Tara", "Rosemary",
290: "Eileen", "Terri", "Gertrude", "Lucy", "Tonya", "Ella",
291: "Stacey", "Wilma", "Gina", "Kristin", "Jessie", "Natalie",
292: "Agnes", "Vera", "Willie", "Charlene", "Bessie", "Delores",
293: "Melinda", "Pearl", "Arlene", "Maureen", "Colleen", "Allison",
294: "Tamara", "Joy", "Georgia", "Constance", "Lillie", "Claudia",
295: "Jackie", "Marcia", "Tanya", "Nellie", "Minnie", "Marlene",
296: "Heidi", "Glenda", "Lydia", "Viola", "Courtney", "Marian",
297: "Stella", "Caroline", "Dora", "Jo", "Vickie", "Mattie",
298: "Terry", "Maxine", "Irma", "Mabel", "Marsha", "Myrtle",
299: "Lena", "Christy", "Deanna", "Patsy", "Hilda", "Gwendolyn",
300: "Jennie", "Nora", "Margie", "Nina", "Cassandra", "Leah",
301: "Penny", "Kay", "Priscilla", "Naomi", "Carole", "Brandy",
302: "Olga", "Billie", "Dianne", "Tracey", "Leona", "Jenny",
303: "Felicia", "Sonia", "Miriam", "Velma", "Becky", "Bobbie",
304: "Violet", "Kristina", "Toni", "Misty", "Mae", "Shelly",
305: "Daisy", "Ramona", "Sherri", "Erika", "Katrina", "Claire"
306: };
307: /**<
308: Provides 300 female first names, ranked in order of frequency as found
309: in the United States of America.
310: */
313: const string NAMES_MALE[] =
314: { "James", "John", "Robert", "Michael", "William", "David",
315: "Richard", "Charles", "Joseph", "Thomas", "Christopher", "Daniel",
316: "Paul", "Mark", "Donald", "George", "Kenneth", "Steven",
317: "Edward", "Brian", "Ronald", "Anthony", "Kevin", "Jason",
318: "Matthew", "Gary", "Timothy", "Jose", "Larry", "Jeffrey",
319: "Frank", "Scott", "Eric", "Stephen", "Andrew", "Raymond",
320: "Gregory", "Joshua", "Jerry", "Dennis", "Walter", "Patrick",
321: "Peter", "Harold", "Douglas", "Henry", "Carl", "Arthur",
322: "Ryan", "Roger", "Joe", "Juan", "Jack", "Albert",
323: "Jonathan", "Justin", "Terry", "Gerald", "Keith", "Samuel",
324: "Willie", "Ralph", "Lawrence", "Nicholas", "Roy", "Benjamin",
325: "Bruce", "Brandon", "Adam", "Harry", "Fred", "Wayne",
326: "Billy", "Steve", "Louis", "Jeremy", "Aaron", "Randy",
327: "Howard", "Eugene", "Carlos", "Russell", "Bobby", "Victor",
328: "Martin", "Ernest", "Phillip", "Todd", "Jesse", "Craig",
329: "Alan", "Shawn", "Clarence", "Sean", "Philip", "Chris",
330: "Johnny", "Earl", "Jimmy", "Antonio", "Danny", "Bryan",
331: "Tony", "Luis", "Mike", "Stanley", "Leonard", "Nathan",
332: "Dale", "Manuel", "Rodney", "Curtis", "Norman", "Allen",
333: "Marvin", "Vincent", "Glenn", "Jeffery", "Travis", "Jeff",
334: "Chad", "Jacob", "Lee", "Melvin", "Alfred", "Kyle",
335: "Francis", "Bradley", "Jesus", "Herbert", "Frederick", "Ray",
336: "Joel", "Edwin", "Don", "Eddie", "Ricky", "Troy",
337: "Randall", "Barry", "Alexander", "Bernard", "Mario", "Leroy",
338: "Francisco", "Marcus", "Micheal", "Theodore", "Clifford", "Miguel",
339: "Oscar", "Jay", "Jim", "Tom", "Calvin", "Alex",
340: "Jon", "Ronnie", "Bill", "Lloyd", "Tommy", "Leon",
341: "Derek", "Warren", "Darrell", "Jerome", "Floyd", "Leo",
342: "Alvin", "Tim", "Wesley", "Gordon", "Dean", "Greg",
343: "Jorge", "Dustin", "Pedro", "Derrick", "Dan", "Lewis",
344: "Zachary", "Corey", "Herman", "Maurice", "Vernon", "Roberto",
345: "Clyde", "Glen", "Hector", "Shane", "Ricardo", "Sam",
346: "Rick", "Lester", "Brent", "Ramon", "Charlie", "Tyler",
347: "Gilbert", "Gene", "Marc", "Reginald", "Ruben", "Brett",
348: "Angel", "Nathaniel", "Rafael", "Leslie", "Edgar", "Milton",
349: "Raul", "Ben", "Chester", "Cecil", "Duane", "Franklin",
350: "Andre", "Elmer", "Brad", "Gabriel", "Ron", "Mitchell",
351: "Roland", "Arnold", "Harvey", "Jared", "Adrian", "Karl",
352: "Cory", "Claude", "Erik", "Darryl", "Jamie", "Neil",
353: "Jessie", "Christian", "Javier", "Fernando", "Clinton", "Ted",
354: "Mathew", "Tyrone", "Darren", "Lonnie", "Lance", "Cody",
355: "Julio", "Kelly", "Kurt", "Allan", "Nelson", "Guy",
356: "Clayton", "Hugh", "Max", "Dwayne", "Dwight", "Armando",
357: "Felix", "Jimmie", "Everett", "Jordan", "Ian", "Wallace",
358: "Ken", "Bob", "Jaime", "Casey", "Alfredo", "Alberto",
359: "Dave", "Ivan", "Johnnie", "Sidney", "Byron", "Julian",
360: "Isaac", "Morris", "Clifton", "Willard", "Daryl", "Ross",
361: "Virgil", "Andy", "Marshall", "Salvador", "Perry", "Kirk",
362: "Sergio", "Marion", "Tracy", "Seth", "Kent", "Terrance",
363: "Rene", "Eduardo", "Terrence", "Enrique", "Freddie", "Wade"
364: };
365: /**<
366: A named constant containing 300 male first names, 6 per line,
367: ranked in order of frequency as found in the United States.
368: */
370: //
371: //
372: //************************************************************************
373: //Free Function Section
375: void ClearScreen
376: (
377: int numLines = 25 //in
378: );
379: /**<
380: Clears the screen (the default output stream, which is assumed by
381: default to have 25 lines).
382: @return void
383: @param numLines The number of lines on the screen.
384: @pre None
385: @post <em>numLines</em> blank lines have been displayed on the standard
386: output stream (the screen).
387: */
390: void DisplayOpeningScreen
391: (
392: const string& programmerInfo = DEFAULT_PROGRAMMER_INFO, //in
393: const string& programInfo = DEFAULT_PROGRAM_INFO, //in
394: int numBlankLinesBefore = 11, //in
395: int numBlankLinesAfter = 12 //in
396: );
397: /**<
398: Displays an opening screen for any console program. The default display
399: shows a first line of programmer identification, the date and time of
400: the current program build on the second line, and a generic program
401: description on the third line of output. These three lines of output
402: are centered vertically, more or less, on an otherwise blank screen.
403: The idea is to keep the program description as short as possible
404: (preferably one or two lines), and to center vertically on the screen
405: all lines of output. To help accomplish these goals the user is permitted
406: to choose the number of blank lines to output both before and after the
407: lines containing information.
408: @return void
409: @param programmerInfo Text containing the programmer's ID info in the
410: appropriate form (specified elsewhere, but not in this documentation).
411: @param programInfo Text containing a brief (one-or-two-line)
412: description of the program.
413: @param numBlankLinesBefore The number of blank lines appearing on
414: the screen before the display of the contents of <em>programmerInfo</em>.
415: @param numBlankLinesAfter The number of blank lines appearing on the
416: screen after the display of the contents of <em>programInfo</em>.
417: @pre Note that default values are provided for all parameters and
418: the default values of <em>programmerInfo</em> and <em>programInfo</em>
419: are given by the named constants <em>DEFAULT_PROGRAMMER_INFO</em> and
420: <em>DEFAULT_PROGRAMMER_INFO</em> (respectively), which are described
421: elsewhere in this documentation. Here are the additional preconditions:
422: -# The standard input stream cin is empty.
423: -# Any newline character(s) required to begin a new line of output
424: have been included in the values of the string input parameter(s)
425: <em>programmerInfo</em> and/or <em>programInfo</em>.
426: @post
427: -# The contents of <em>programmerInfo</em> and <em>programInfo</em>
428: have been displayed, in that order, followed by a line similar to
429: the following:
430: <pre>
431: This executable was built on May 25 2007 at 23:47:51.
432: </pre>
433: There are no blank lines separating any of these lines of information,
434: but <em>numBlankLinesBefore</em> blank lines are output before the
435: contents of <em>programmerInfo</em> and <em>numBlankLinesAfter</em> blank lines
436: are output after the line containing the build date and time.
437: -# The program has paused after displaying a pause message, and the
438: user has pressed Enter.
439: */
442: void DisplayTextfile
443: (
444: const string& fileName, //in
445: int numberOfLinesPerPause = 23 //in
446: );
447: /**<
448: Displays a file of text numberOfLinesPerPause lines at a time.
449: This function allows the user to display any textfile on the
450: standard output and also lets the user decide how many lines
451: to display "between pauses", i.e., between the times when the
452: function pauses and waits for the user to press Enter to continue.
453: @return void
454: @param fileName The name of the file to be displayed.
455: @param numberOfLinesPerPause The number of lines displayed between
456: pauses.
457: @pre
458: <em>fileName</em> has been initialized.
459: @post
460: - Case 1 (typical): If <em>fileName</em> contains the name of an
461: existing and readable textfile in the current directory, or the full
462: pathname of an existing and readable textfile in some other accessible
463: directory, that file has been displayed on the screen numberOfLinesPerPause
464: lines at at time, preceded by the message
465: <pre>
466: ==================================================
467: The file display will begin when you continue after this pause.
468: And note that one blank line not in the file will appear after each pause.
469: Press Enter to continue ...
470: </pre>
471: and followed by this message:
472: <pre>
473: End of file has been reached.
474: Press Enter to continue ...
475: </pre>
476: In addition, after each group of lines has been displayed, the program
477: pauses and waits for the user to press Enter, with a message like the
478: following:
479: <pre>
480: =====Line immediately above is line ## of file name-of-file.
481: Press Enter to continue ...
482: </pre>
483: - Case 2 (error): If the file designated by <em>fileName</em> cannot
484: be opened, the function pauses and waits for the user to press Enter to
485: continue, with the message
486: <pre>
487: Error: \<\<name-of-file\>\> could not be opened.
488: Press Enter to continue ...
489: </pre>
490: and then returns.
491: */
494: int gcd
495: (
496: int a, //in
497: int b //in
498: );
499: /**<
500: Finds the greatest common divisor of two nonnegative integers,
501: at least one of which is strictly positive.
502: @return The greatest common divisor of the two input integers.
503: @param a A nonnegative integer.
504: @param b A nonnegative integer.
505: @pre Both <em>a</em> and <em>b</em> have been initialized with
506: nonnegative integer values, and at least one of <em>a</em> or
507: <em>b</em> is strictly positive.
508: @post No side effects.
509: */
512: bool isEven
513: (
514: int n //in
515: );
516: /**<
517: Determines if a positive integer is even.
518: @return <tt>true</tt> if n is an even integer, <tt>false</tt> if n is odd.
519: @param n The integer whose "evenness" is to be determined.
520: @pre <em>n</em> is a nonnegative integer.
521: @post No side effects.
522: */
525: bool isOdd
526: (
527: int n //in
528: );
529: /**<
530: Determines if a positive integer is odd.
531: @return <tt>true</tt> if n is an odd integer, <tt>false</tt> if n is even.
532: @param n The integer whose "oddness" is to be determined.
533: @pre <em>n</em> is a nonnegative integer.
534: @post No side effects.
535: */
538: int numberOfDigits
539: (
540: int n //in
541: );
542: /**<
543: Finds the number of digits in a positive integer.
544: @return The number of digits in the input integer.
545: @param n The integer whose digits are to be counted.
546: @pre <em>n</em> is a positive integer.
547: @post No side effects.
548: */
551: void Pause
552: (
553: int indentLevel = 0, //in
554: string message = "", //in
555: int pauseNumber = 0 //in
556: );
557: /**<
558: Causes the program to pause and wait for the user to press Enter
559: to continue, with default values for the indentation level, the
560: message supplying any additional information to the user, and the
561: pause number.
562: @return void
563: @param indentLevel The number of spaces to indent the first line
564: of each part of the output from the left margin.
565: @param message The message to be displayed, giving the reason for
566: this particular pause, if such a message is supplied.
567: @param pauseNumber The number of this particular pause, if pauses
568: are being numbered.
569: @pre
570: The input stream cin is empty.
571: @post
572: -# Each line of output produced by this function is automatically
573: indented <em>indentLevel</em> spaces, except for the second and any
574: subsequent lines of the text in <em>message</em>, which require a
575: newline character to start a new line.
576: -# If <em>pauseNumber</em> is 0 (the default value), there is no
577: corresponding output, while if <em>pauseNumber</em> is any positive
578: value (6 for example), a line like the following has been displayed
579: as the first line of output:
580: <pre>
581: This is pause #6.
582: </pre>
583: -# If <em>message</em> is non-empty, its content has been displayed
584: next, starting on the next line. An automatic newline is also inserted
585: following the text of <em>message</em>, so the text of <em>message</em>
586: itself need not (though it may) contain one or more newline characters.
587: -# As the last line of output, in all cases, the message
588: <pre>
589: Press Enter to continue ...
590: </pre>
591: has been displayed, with the cursor at the end of the line.
592: -# The user has pressed Enter.
593: */
596: void ReadChar
597: (
598: const string& userPrompt, //in
599: char& charValue //out
600: );
601: /**<
602: Gets a character (char) value from the user.
603: @param userPrompt Text of the prompt displayed to the user.
604: @param charValue Contains the character entered by the user.
605: @return void
606: @pre <em>userPrompt</em> has been initialized.
607: @post
608: -# The text in <em>userPrompt</em> has been displayed and the user
609: has entered a character (a value of type char), which is returned in
610: <em>charValue</em>. It is important to note that <strong>any</strong>
611: char value will be read, including any whitespace character.
612: -# The input stream cin is empty.
613: */
616: void ReadDouble
617: (
618: const string& userPrompt, //in
619: double& doubleValue //out
620: );
621: /**<
622: Gets a real (double) value from the user.
623: @return void
624: @param userPrompt Text of the prompt displayed to the user.
625: @param doubleValue Contains the real number entered by the user.
626: @pre
627: <em>userPrompt</em> has been initialized.
628: @post
629: -# The text in <em>userPrompt</em> has been displayed and the user
630: has entered a real number (a value of type <tt>double</tt>), which
631: is returned in <em>doubleValue</em>. If the user does not enter a
632: valid real number, the following message is displayed:
633: <pre>
634: Error: That was not a valid real number. Try again.
635: Press Enter to continue ...
636: </pre>
637: after which the prompt is displayed again and the user gets another
638: chance. This is essentially an infinite loop, so the user must eventually
639: enter a valid real number for the process to terminate normally.
640: -# The input stream cin is empty.
641: */
644: void ReadInt
645: (
646: const string& userPrompt, //in
647: int& intValue //out
648: );
649: /**<
650: Gets an integer (int) value from the user.
651: @return void
652: @param userPrompt Text of the prompt displayed to the user.
653: @param intValue Contains the integer value entered by the user.
654: @pre
655: <em>userPrompt</em> has been initialized.
656: @post
657: -# The text in <em>userPrompt</em> has been displayed and the user
658: has entered an integer (a value of type <tt>int</tt>), which is returned
659: in <em>intValue</em>. If the user does not enter a valid integer, the
660: following message is displayed:
661: <pre>
662: Error: That was not a valid integer. Try again.
663: Press Enter to continue ...
664: </pre>
665: after which the prompt is displayed again and the user gets another
666: chance. This is essentially an infinite loop, so the user must eventually
667: enter a valid integer value for the process to terminate normally.
668: -# The input stream cin is empty.
669: */
672: void ReadThisLine
673: (
674: const string& userPrompt, //in
675: string& lineValue //out
676: );
677: /**<
678: Reads the text entered by a user on the same line as the prompt.
679: @return void
680: @param userPrompt Text of the prompt displayed to the user.
681: @param lineValue Contains the text entered by the user.
682: @pre
683: <em>userPrompt</em> has been initialized.
684: @post
685: -# The text in <em>userPrompt</em> has been displayed and the user has
686: entered some text and then pressed Enter. All text entered on same line
687: as the prompt, after the prompt, (including all intermediate whitespace,
688: but not including the terminating newline character) is returned in
689: <em>lineValue</em>.
690: -# The input stream cin is empty.
691: */
694: void ReadNextLine
695: (
696: const string& userPrompt, //in
697: string& lineValue //out
698: );
699: /**<
700: Reads the text entered by a user on the line following the prompt.
701: @return void
702: @param userPrompt Text of the prompt displayed to the user.
703: @param lineValue Contains the line of text entered by the user.
704: @pre
705: <em>userPrompt</em> has been initialized.
706: @post
707: -# The text in <em>userPrompt</em> has been displayed and the
708: user has entered a line of input and then pressed Enter. The entire
709: line of input (including all intermediate whitespace, but not including
710: the terminating newline character) is returned in <em>lineValue</em>.
711: Note that in this case the input is entered on the line following
712: the prompt, while in each of the other Read* functions, the value is
713: entered by the user on the same line as the prompt for that value.
714: -# The input stream cin is empty.
715: */
718: void ReadString
719: (
720: const string& userPrompt, //in
721: string& stringValue //out
722: );
723: /**<
724: Gets a whitespace-delimited string value from the user.
725: @return void
726: @param userPrompt Text of the prompt displayed to the user.
727: @param stringValue Contains the string entered by the user.
728: @pre <em>userPrompt</em> has been initialized.
729: @post
730: -# The text in <em>userPrompt</em> has been displayed, and the user
731: has entered a string value and pressed Enter. The string value is
732: returned in <em>stringValue</em>. Note that the string read will be
733: terminated by any whitespace.
734: -# The input stream cin is empty.
735: */
738: bool userSaysYes
739: (
740: const string& question //in
741: );
742: /**<
743: Gets the user's yes-or-no answer to a single question.
744: @return <tt>true</tt> if the user answers "Yes" to the question asked,
745: and <tt>false</tt> otherwise.
746: @param question Text of the question the user is asked, including the
747: question mark.
748: @pre <em>question</em> has been initialized.
749: @post The text in <em>question</em> has been displayed, followed by
750: <tt>y/[n]</tt> and the user has responded by entering a character
751: and pressing Enter. The value <tt>true</tt> is returned if the user
752: responds positively to the question asked by entering a <tt>y</tt> or
753: a <tt>Y</tt>, or by entering any word beginning with either of these
754: letters. Entering any other letter or word, as well as simply
755: pressing the Enter key, will be interpreted as a negative response
756: and the return value will be <tt>false</tt>. The use of <tt>[n]</tt>
757: as part of the user prompt is meant to indicate to the user that simply
758: pressing Enter will generate a (default) response of "no". This is a
759: convention of reasonably widespread use in console applications.
760: */
763: //
764: //
765: //************************************************************************
766: //Utility Class Section
768: class Menu
769: /**
770: For displaying menus and getting user menu choices in console applications.
771: The <tt>%Menu</tt> class provides a convenient way for simple text-based
772: console programs to display for the user a menu of choices. A menu has a
773: title and up to 20 numbered options which are separated from the title by
774: a blank line when the menu is displayed. A menu knows what its range of
775: valid options is, and can get from the user a valid choice from that
776: range, or return an error value of -1 if the user fails to enter a valid
777: option number during three attempts (by default), or during some
778: client-chosen number of attempts.
779: */
780: {
781: public:
783: Menu();
784: /**<
785: Default constructor; creates a "blank" menu.
786: @pre None
787: @post A "blank" menu has been constructed which has
788: the (default) title <tt>"Empty Menu"</tt> and no options.
789: */
792: Menu
793: (
794: const string& menuTitle //in
795: );
796: /**<
797: Constructor for creating a menu with a user-supplied title
798: but no options.
799: @param menuTitle The text of the title for this menu.
800: @pre <em>menuTitle</em> has been initialized and does not exceed
801: 70 characters in length.
802: @post
803: - Case 1 (typical): A menu has been constructed with a title
804: given by the contents of <em>menuTitle</em>, and having 0 options.
805: - Case 2 (error): If an attempt was made to use a title whose
806: length exceeded the maximum length of 70 characters, the following
807: message has been displayed and the user has pressed Enter:
808: <pre>
809: ===== Error: %Menu title cannot exceed 70 characters in length.
810: The title
811: \<\<text_of_title_that_was_too_long_appears_here\>\>
812: was not added to the menu.
813: This menu has been given the following default title:
814: Empty %Menu
815: Press Enter to continue ...
816: </pre>
817: */
820: void setTitle
821: (
822: const string& menuTitle //in
823: );
824: /**<
825: Sets (or resets) the menu title.
826: @return void
827: @param menuTitle Contains the text of the title for the menu.
828: @pre <em>menuTitle</em> has been initialized and
829: <em>menuTitle.length() <= 70</em>.
830: @post
831: - Case 1 (typical): The text in <em>menuTitle</em> has been
832: assigned as the title of the menu.
833: - Case 2 (error): If an attempt was made to set a title which
834: exceeded the maximum length of 70 characters, the
835: following message has been displayed, and the user has pressed
836: Enter:
837: <pre>
838: ===== Error: %Menu title cannot exceed 70 characters in length.
839: The title
840: \<\<text_of_title_that_was_too_long_appears_here\>\>
841: was not added to the menu. Previous title remains unchanged.
842: Press Enter to continue ...
843: </pre>
844: In either case, the number of menu options is unchanged.
845: */
848: void addOption
849: (
850: const string& option //in
851: );
852: /**<
853: Adds a new option to the menu and assigns it the next available
854: option number.
855: @return void
856: @param option The text of the next option to be added to the menu.
857: @pre
858: The number of options on the menu is < 20.\n
859: <em>option</em> has been initialized and has length <= 70 characters.
860: @post
861: - Case 1 (typical): The number of menu options has been
862: incremented by 1 and the text in <em>option</em> has become the
863: option with the new option number.
864: - Case 2 (error): If the number of options was 20, then the
865: following message has been displayed and the user has pressed
866: Enter:
867: <pre>
868: ===== Error: Number of menu options cannot exceed 20.
869: Option \<\<text_of_option_goes_here\>\> not added.
870: Press Enter to continue ...
871: </pre>
872: - Case 3 (error): If an attempt was made to add an option which
873: exceeded the maximum length of 70 characters, the following
874: message has been displayed and the user has pressed Enter:
875: <pre>
876: ===== Error: %Menu option cannot exceed 70 characters in length.
877: The option
878: \<\<text_of_option_that_was_too_long_appears_here\>\>
879: was not added to the menu.
880: Press Enter to continue ...
881: </pre>
882: */
885: void display() const;
886: /**<
887: Displays a "centered" menu on the screen.
888: @return void
889: @pre The menu has been initialized.
890: @post The menu has been displayed on the screen, more or less
891: centered left-to-right and top-to-bottom, but with a slight
892: top-left bias. Note, however, that a blank menu, or a menu with
893: just a title, is displayed with its title left-justified and with
894: only the bias toward the top. Such a title is followed by a blank
895: line and the following 1-line message, which also starts at the
896: left margin:
897: <pre>
898: This menu currently has no options ...
899: </pre>
900: The (typical) display format is achieved in the following way:
901: - First, by displaying (1/2)(24-numMenuLines)+1 blank lines at
902: the bottom of the screen.
903: - Second, by arranging that column 38 (rather than column 40, of a
904: typical 80 line display) be the column about which the menu title
905: and the menu options are "centered" in the display.
906: */
909: int getChoice
910: (
911: int maxNumTries = 3, //in
912: string userPrompt =
913: "Enter the number of your menu choice here and press Enter: " //in
914: ) const;
915: /**<
916: Gets a menu choice from the user, or a default value if the user
917: fails to enter a valid menu choice before the permitted number
918: of attempts runs out.
919: @return The user's menu choice, or the default value of -1.
920: @param maxNumTries The maximum number of tries permitted to the
921: user to enter a valid menu choice.
922: @param userPrompt The text of the prompt to be used to ask the
923: user for a menu choice.
924: @pre
925: Typically, a menu has been initialized, and presumably
926: displayed, though in fact this is not technically a necessary
927: pre-condition for this function.
928: @post
929: - Case 1 (typical): A valid menu choice for the menu has been
930: entered by the user and returned.
931: - Case 2 (error): If a choice was sought from a blank menu, the
932: message
933: <pre>
934: ===== Error: The menu has no options from which to choose.
935: Press Enter to continue ...
936: </pre>
937: has been displayed and the user has pressed Enter.
938: - Case 3 (error): If an invalid menu choice has been entered, the
939: displayed message is:
940: <pre>
941: ===== Error: Sorry! Invalid response. Please try again:
942: </pre>
943: If <em>maxNumTries</em> unsuccessful attempts have
944: been made, the displayed message is:
945: <pre>
946: ===== Error: Sorry, but you only get \<\<maxNumTries\>\> chances.
947: Press Enter to continue ...
948: </pre>
949: and the user has pressed Enter, after which the value of -1
950: is returned. Note that if no prompt is supplied by the client,
951: the default prompt
952: <pre>
953: Enter the number of your menu choice here and press Enter:
954: </pre>
955: is displayed slighty left-of-center on the screen below the
956: menu.
957: Note as well that anything other than a valid menu choice for
958: the current menu will be read and rejected, including (for example)
959: a valid menu choice followed by extraneous characters, as well
960: as simply pressing Enter.
961: */
963: private:
964: static const int MAX_NUM_OPTIONS = 20;
965: static const int MAX_OPTION_LENGTH = 70;
966: static const int MAX_TITLE_LENGTH = 70;
968: int numOptions;
969: //Number of options currently on the menu.
971: vector<string> menuText;
972: //Contains the title and the options
973: //Both constructors set the size of menuText to 1+MAX_NUM_OPTIONS,
974: //which includes one row to hold the menu title, and MAX_NUM_OPTIONS
975: //rows to hold the options.
976: };
979: class OperationCounter
980: /**
981: For counting operations performed by an algorithm.
982: An object of the <tt>%OperationCounter</tt> class may be used to keep
983: a count of the number of each of several different kinds operations
984: performed during the application of an algorithm to a data set. The
985: operations that can be counted are the usual comparisons, exchanges,
986: and assignments that one might be interested in tracking, as well as
987: one other kind of operation chosen by the client. The client may also
988: supply a name for that "other" operation, and use that name in summary
989: output.
990: */
991: {
992: public:
994: OperationCounter();
995: /**<
996: Default constructor.
997: @pre None
998: @post A counter object has been constructed, with all operation
999: counters set to 0 and the name of the "other" operation set to
1000: "Other Op".
1001: */
1004: void reset();
1005: /**<
1006: Resets all operation counters to zero and the name of the "other"
1007: operation, if any, to an empty string.
1008: @return void
1009: @pre None
1010: @post All counting data members have been reset to 0, and the
1011: name of the "other" operation has been set to "Other Op".
1012: */
1015: void incrementAssignments
1016: (
1017: int numTimes = 1 //in
1018: );
1019: /**<
1020: Increments the counter for the number of assignment operations.
1021: @return void
1022: @param numTimes The number of times the assignment counter
1023: is to be incremented.
1024: @return void
1025: @pre None
1026: @post The number of assignment operations has been incremented
1027: by the value of <em>numTimes</em>.
1028: */
1031: void incrementComparisons
1032: (
1033: int numTimes = 1 //in
1034: );
1035: /**<
1036: Increments the counter for the number of comparison operations.
1037: @return void
1038: @param numTimes The number of times the comparison counter
1039: is to be incremented.
1040: @pre None
1041: @post The number of comparison operations has been incremented
1042: by the value of <em>numTimes</em>.
1043: */
1046: void incrementExchanges
1047: (
1048: int numTimes = 1 //in
1049: );
1050: /**<
1051: Increments the counter for the number of exchange operations.
1052: @return void
1053: @param numTimes The number of times the exchange counter
1054: is to be incremented.
1055: @pre None
1056: @post The number of exchange operations has been incremented
1057: by the value of <em>numTimes</em>.
1058: */
1061: void incrementOtherOp
1062: (
1063: int numTimes = 1 //in
1064: );
1065: /**<
1066: Increments the counter for the number of "other" operations.
1067: @return void
1068: @param numTimes The number of times the counter of the
1069: "other" operation is to be incremented.
1070: @pre None
1071: @post The number of "other" operations has been incremented
1072: by the value of <em>numTimes</em>.
1073: */
1076: int getNumberOfComparisons() const;
1077: /**<
1078: Gets the number of comparison operations counted.
1079: @return The number of comparison operations counted.
1080: @pre None
1081: @post No side effects.
1082: */
1085: int getNumberOfExchanges() const;
1086: /**<
1087: Gets the number of exchange operations counted.
1088: @return The number of exchange operations counted.
1089: @pre None
1090: @post No side effects.
1091: */
1094: int getNumberOfAssignments() const;
1095: /**<
1096: Gets the number of assignment operations counted.
1097: @return The number of assignment operations counted.
1098: @pre None
1099: @post No side effects.
1100: */
1103: int getNumberOfOtherOp() const;
1104: /**<
1105: Gets the number of "other" operations performed.
1106: @return The number of "other" operations counted.
1107: @pre None
1108: @post No side effects.
1109: */
1112: void setNameOfOtherOp
1113: (
1114: string nameOfOtherOp //in
1115: );
1116: /**<
1117: Sets (or resets) the name of the "other" operation.
1118: @return void
1119: @param nameOfOtherOp Text for the name of the "other" operation.
1120: @pre <em>nameOfOtherOp</em> has been initialized.
1121: @post The value of <em>nameOfOtherOp</em> has been assigned as
1122: the name of the other operation.
1123: */
1126: string getNameOfOtherOp() const;
1127: /**<
1128: Gets the name of the "other" operation.
1129: @return The name of the "other" operation.
1130: @pre None
1131: @post The name of the "other operation" has been returned (and
1132: will be "Other Op" unless it has been set to something
1133: else with setNameOfOtherOp().
1134: */
1137: void displayNonZeroCounts() const;
1138: /**<
1139: Displays a summary of the counts for all operations actually performed
1140: (and which therefore have non-zero counts). This method would normally
1141: be called if only one or two operations were being counted and the
1142: user did not want to take up space in the output with zero counts
1143: for the other operations.
1144: @return void
1145: @pre None
1146: @post
1147: - Case 1: Whatever counts of comparisons, number of exchanges, number
1148: of assignments and/or the number of operations of the "other" kind (if
1149: applicable) have been recorded by counter object and are non-zero have
1150: been displayed as shown below. That is, the title is displayed, along
1151: with those lines corresponding to non-zero counts.
1152: <pre>
1153: Summary of Non-Zero Operation Counts
1154: Comparisons = #
1155: Exchanges = #
1156: Assignments = #
1157: Name of Other Operation = #
1158: </pre>
1159: - Case 2: If all counts are zero, the following message is displayed.
1160: <pre>
1161: Summary of Non-Zero Operation Counts
1162: No operations of any kind have been counted.
1163: </pre>
1164: */
1167: void displayAllCounts() const;
1168: /**<
1169: Displays a summary of the number of operations counted. This method
1170: would normally be used when the user desires to see all counts, even
1171: if some are (and are known to be) zero.
1172: @return void
1173: @pre None
1174: @post
1175: - Case 1: All operation counts are displayed in the format shown below.
1176: <pre>
1177: Summary of All Operation Counts
1178: Comparisons = #
1179: Exchanges = #
1180: Assignments = #
1181: Name of Other Operation = #
1182: </pre>
1183: - Case 2: If all counts are zero, the following message is displayed:
1184: <pre>
1185: Summary of All Operation Counts
1186: No operations of any kind have been counted.
1187: </pre>
1188: */
1191: private:
1192: int numComparisons;
1193: int numExchanges;
1194: int numAssignments;
1195: int numOtherOp;
1196: string nameOfOtherOp;
1197: };
1201: class RandomGenerator
1202: /**
1203: For generating pseudorandom integer, real, character and string values.
1204: The <tt>%RandomGenerator</tt> class can be used to generate pseudorandom
1205: values of the following types:
1206: - int values in a user-chosen range
1207: - double values in a user-chosen range
1208: - char values in a user chosen range
1209: - string values of a user chosen size, containing user-chosen characters
1210: */
1211: {
1212: public:
1214: RandomGenerator();
1215: /**<
1216: Default constructor, based on seed obtained from a call to the
1217: <tt>time()</tt> function. If a random generator constructed by
1218: this constructor is used, the sequence of random values will be
1219: different each time.
1220: @pre None
1221: @post The generator has been initialized with a random seed value
1222: obtained by a call to the <tt>time()</tt> function.
1223: */
1226: RandomGenerator
1227: (
1228: int userSeedValue //in
1229: );
1230: /**<
1231: Constructor based on a client-supplied seed. If a random generator
1232: constructed by this constructor is used, the <em>userSeedValue</em>
1233: used determines the sequence of random values obtained, and the same
1234: sequence of values can be obtained on a subsequent run by reusing
1235: the same <em>userSeedValue</em>. This same <em>userSeedValue</em> can
1236: be used to construct a new random generator object using this constructor,
1237: or to reset an already existing random generator object using the reset()
1238: method; either way, you get the same sequence of values as you did when
1239: that <em>userSeedValue</em> was employed previously.
1240: @param userSeedValue A seed value supplied by the client.
1241: @pre <em>userSeedValue</em> has been initialized.
1242: @post The generator has been initialized using a seed value
1243: (<em>userSeedValue</em>) supplied by the client.
1244: */
1247: void reset();
1248: /**<
1249: Resets the random generator using a seed obtained by a call to
1250: the <tt>time()</tt> function.
1251: @return void
1252: @pre None
1253: @post The generator has been re-initialized using a random seed
1254: value obtained by a call to the time function.
1255: */
1258: void reset
1259: (
1260: int userSeedValue //in
1261: );
1262: /**<
1263: Resets the random generator using a seed supplied by the client.
1264: @return void
1265: @pre userSeedValue has been initialized.
1266: @post The generator has been re-initialized using a seed value
1267: (userSeedValue) supplied by the client.
1268: */
1271: //
1272: //
1273: //********** Random int generators **********
1274: int getNext
1275: (
1276: int n //in
1277: );
1278: /**<
1279: Gets a pseudorandom integer in the range <em>[0,n)</em>.
1280: @return A pseudorandom int value in the range <em>[0,n)</em>.
1281: @param n A positive integer value.
1282: @pre <em>n</em> has been initialized and <em>n > 0</em>.
1283: @post The object's internal random number generator has been
1284: called once.
1285: */
1288: int getNextInt
1289: (
1290: int n //in
1291: );
1292: /**<
1293: Same as getNext(int n) above, but with a more explicit name,
1294: for readability rather than for ease of use when programming
1295: "generically".
1296: */
1299: int getNext
1300: (
1301: int low, //in
1302: int high //in
1303: );
1304: /**<
1305: Gets a pseudorandom integer in the range [low,high].
1306: @return A pseudorandom integer value in the range <em>[low,high]</em>.
1307: @param low A positive integer value <= the value of <em>high</em>.
1308: @param high A positive integer value >= the value of <em>low</em>.
1309: @pre <em>low</em> and <em>high</em> have been initialized, and
1310: <em>low <= high</em>.
1311: @post The object's internal random number generator has been called
1312: once.
1313: */
1316: int getNextInt
1317: (
1318: int low, //in
1319: int high //in
1320: );
1321: /**<
1322: Same as getNext(int low, int high) above, but with a more
1323: explicit name, for readability rather than for ease of use
1324: when programming "generically".
1325: */
1328: //
1329: //
1330: //********** Random double generators **********
1331: double getNext
1332: (
1333: double x //in
1334: );
1335: /**<
1336: Gets a pseudorandom real (double) in the range [0,x).
1337: @return A pseudorandom double value in the range <em>[0,x)</em>.
1338: @param x A positive real (double) number.
1339: @pre <em>x</em> has been initialized and <em>x > 0</em>.
1340: @post The object's internal random number generator has been called
1341: once.
1342: */
1345: double getNextDouble
1346: (
1347: double x //in
1348: );
1349: /**<
1350: Same as getNext(double x) above, but with a more explicit name,
1351: for readability rather than for ease of use when programming
1352: "generically".
1353: */
1356: double getNext
1357: (
1358: double low, //in
1359: double high //in
1360: );
1361: /**<
1362: Gets a pseudorandom real (double) value in the range [low,high).
1363: @return A pseudorandom real (double) value in the range
1364: <em>[low,high)</em>.
1365: @param low A positive real (double) value < the value of <em>high</em>.
1366: @param high A positive real (double) value > the value of <em>low</em>.
1367: @pre <em>low</em> and <em>high</em> have been initialized, and
1368: <em>low < high</em>.
1369: @post The object's internal random number generator has been called
1370: once.
1371: */
1374: double getNextDouble
1375: (
1376: double low, //in
1377: double high //in
1378: );
1379: /**<
1380: Same as getNext(double low, double high) above, but with a more
1381: explicit name, for readability rather than for ease of use
1382: when programming "generically".
1383: */
1386: //
1387: //
1388: //********** Random string generators **********
1389: string getNext
1390: (
1391: const string& s //in
1392: );
1393: /**<
1394: Gets a pseudorandom string based on the length and content of
1395: <em>s</em>.
1396: @return A pseudorandom string object.
1397: @param s Any string of characters.
1398: @pre <em>s</em> has been initialized and <em>s.length() >= 2</em>.
1399: Let <em>a</em> and <em>b</em> represent the first two distinct
1400: characters in <em>s</em>. Suppose <em>a</em> occurs in the first
1401: <em>low</em> contiguous locations in <em>s</em>. Suppose <em>b</em>
1402: occurs in the next <em>high</em> contiguous locations in <em>s</em>.
1403: It is required that <em>a < b</em> and that <em>low <= high</em>.
1404: @post
1405: A pseudorandom string object has been returned, according to these rules:
1406: -# If <em>low == high</em>, then the length of any returned
1407: string is their common value.
1408: -# If <em>low < high</em>, then the length of any returned value
1409: is a random value in the range [low,high].
1410: -# If <em>s.length() == low+high</em>, the characters in the
1411: returned value are in the char range [a,b].
1412: -# If <em>s.length() > low+high</em>, the characters in any
1413: returned value come from the set of all characters in s, excluding
1414: the first two distinct characters.
1415: */
1418: string getNextString
1419: (
1420: const string& s //in
1421: );
1422: /**<
1423: Same as getNext(const string& s) above, but with a more explicit
1424: name, for readability rather than for ease of use when programming
1425: "generically".
1426: */
1429: string getNext
1430: (
1431: const string& first, //in
1432: const string& second //in
1433: );
1434: /**<
1435: Gets a random string in the "range" between the two strings
1436: <em>first</em> and <em>second</em>.
1437: @return A pseudorandom string object.
1438: @param first The "lower bound" of a "string range" from which
1439: the pseudorandom string object will be chosen.
1440: @param second The "upper bound" of a "string range" from which
1441: the pseudorandom string object will be chosen.
1442: @pre
1443: -# <em>first</em> and <em>second</em> have been initialized.
1444: -# <em>first <= second</em>.
1445: -# <em>first.length() <= second.length()</em>.
1446: @post A pseudorandom string value <tt>r</tt> satisfying the
1447: following three conditions is returned:
1448: -# <em>first <= r <= second</em>.
1449: -# <em>first.length() <= r.length() <= second.length()</em>.
1450: -# <em>r</em> contains only characters found in either
1451: <em>first</em> or <em>second</em>.
1452: */
1455: string getNextString
1456: (
1457: const string& first, //in
1458: const string& second //in
1459: );
1460: /**<
1461: Same as getNext(const string& first, const string& second)
1462: above, but with a more explicit name, for readability rather than
1463: for ease of use when programming "generically".
1464: */
1467: //
1468: //
1469: //********** Auxiliary random string generators **********
1470: //These are public since they may also be useful to class clients.
1471: string getNextStringFromCharRange
1472: (
1473: int size, //in
1474: char firstChar, //in
1475: char lastChar //in
1476: );
1477: /**<
1478: Gets a pseudorandom string containing <em>size</em> characters
1479: from the character range <em>[firstChar,secondChar]</em>.
1480: @return A pseudorandom string object.
1481: @param size The size of the string to be returned.
1482: @param firstChar The lower bound of the character range from which the
1483: characters for the returned string will be taken.
1484: @param lastChar The upper bound of the character range from which the
1485: characters for the returned string will be taken.
1486: @pre <em>size</em>, <em>first</em> and <em>last</em> have been
1487: initialized, with <em>size >=1</em>, <em>first <= last</em>.
1488: @post A pseudorandom string value containing <em>size</em> printable
1489: characters in the range <em>[first,last]</em> has been returned.
1490: */
1492: string getNextStringFromString
1493: (
1494: int size, //in
1495: const string& source //in
1496: );
1497: /**<
1498: Gets a pseudorandom string containing <tt>size</tt> characters taken
1499: from the string <tt>s</tt>.
1500: @return A pseudorandom string object.
1501: @param size The size of the string to be returned.
1502: @param source The string from which the characters for the returned
1503: string will be taken.
1504: @pre <em>size</em> and <em>source</em> have been initialized, with
1505: <em>size >= 1</em> and <em>source</em> containing only printable
1506: characters.
1507: @post A random string value containing <em>size</em> printable
1508: characters, all of which appear in <em>source</em>, has been returned.
1509: */
1511: private:
1512: int seed;
1513: void my_srand(int& seed);
1514: int my_rand();
1515: };
1519: class Stopwatch
1520: /**
1521: For measuring the time taken by an algorithm to perform its task.
1522: An object of class <tt>%Stopwatch</tt> will behave like a stopwatch.
1523: It can be started, stopped, and asked for the time elapsed.
1524: This time can be computer time (clock ticks), or real time as measured
1525: in seconds, minutes, or hours.
1526: */
1527: {
1528: public:
1530: Stopwatch();
1531: /**<
1532: Default constructor.
1533: @pre None
1534: @post The clock time at the time of declaration has been recorded.
1535: */
1537: Stopwatch
1538: (
1539: const string nameOfEventToBeTimed //in
1540: );
1541: /**<
1542: Constructor which allows the naming of the event to be timed.
1543: @pre None
1544: @post The clock time at the time of declaration has been recorded,
1545: as well as the name of the event to be timed.
1546: */
1548: void setEventName
1549: (
1550: const string nameOfEventToBeTimed //in
1551: );
1552: /**<
1553: Sets, or resets, the name of the event to be timed.
1554: @return void
1555: @pre None
1556: @post The name of the event to be timed has been set to be the text
1557: contained in nameOfEventToBeTimed, which may be the empty string
1558: if no name is desired.
1559: */
1561: string getEventName() const;
1562: /**<
1563: Gets the current name of the event to be timed.
1564: @return The current name of the event to be timed.
1565: @pre None
1566: @post No side effects.
1567: */
1570: void start();
1571: /**<
1572: Causes the stopwatch to start running.
1573: @return void
1574: @pre <em>stop()</em> has been called, or <em>start()</em> has
1575: never been called.
1576: @post The stopwatch timer has been "started" and the clock time
1577: at start time has been recorded, in computer clock ticks.
1578: */
1581: void stop();
1582: /**<
1583: Causes the stopwatch to stop running.
1584: @return void
1585: @pre <em>start()</em> has been called.
1586: @post The stopwatch timer has been "stopped" and the accumulated
1587: time since <em>start()</em> was called has been recorded.
1588: */
1591: void delay
1592: (
1593: int delayFactor = 1 //in
1594: ) const;
1595: /**<
1596: Adds some multiple of an artifical amount of time to the
1597: accumulated time on the stopwatch.
1598: @return void
1599: @pre <tt>start()</tt> has been called.
1600: @post An artificial amount of time has been added to the total
1601: computer process time as reported by the clock function. In other
1602: words, during this delay time the "stopwatch" continues to
1603: accumulate time but nothing else happens. Thus this is a way to
1604: make an operation appear to take longer than it actually does.
1605: It can be used to cause the stopwatch to accumulate "artificial"
1606: time when monitoring the performance of an algorithm on a relatively
1607: small data set. This helps us to overcome the problem of trying to
1608: measure the amount of time taken to perform a calulation and finding
1609: that it took "no time at all". Note that we still cannot measure the
1610: absoute time taken, but fortunately we are often only interested in
1611: measuring the relative time taken by the same algorithm on data sets
1612: of different sizes, or by different algorithms on data sets of the
1613: same size. The input parameter <em>delayFactor</em> is a linear
1614: multiplier for increasing the amount of delay time. For example,
1615: a <em>delayFactor</em> of 2 doubles the amount of delay time
1616: accumulated by a single call to the <em>delay()</em> member function.
1617: */
1620: clock_t getTicks() const;
1621: /**<
1622: Gets the number of clock ticks between the most recent calls of
1623: <em>start()</em> and <em>stop()</em>.
1624: @return The number of clock ticks between the last calls to
1625: <em>start()</em> and <em>stop()</em>.
1626: @pre <em>start()</em> and <em>stop()</em> have been called (in that
1627: order).
1628: @post The accumulated time, in computer clock ticks, between the times
1629: when the stopwatch was last started and stopped, has been returned.
1630: */
1633: double getSeconds() const;
1634: /**<
1635: Gets the number of seconds between the last calls of
1636: <em>start()</em> and <em>stop()</em>.
1637: @return The number of seconds between the last calls to
1638: <em>start()</em> and <em>stop()</em>.
1639: @pre <em>start()</em> and <em>stop()</em> have been called
1640: (in that order).
1641: @post The accumulated time, in seconds, between the times when the
1642: stopwatch was last started and stopped, has been returned.
1643: */
1646: double getMinutes() const;
1647: /**<
1648: Gets the number of minutes between the last calls of
1649: <em>start()</em> and <em>stop()</em>.
1650: @return The number of minutes between the last calls to
1651: <em>start()</em> and <em>stop()</em>.
1652: @pre <em>start()</em> and <em>stop()</em> have been called (in
1653: that order).
1654: @post The accumulated time, in minutes, between the times when the
1655: stopwatch was last started and stopped, has been returned.
1656: */
1659: double getHours() const;
1660: /**<
1661: Gets the number of hours between the last calls of
1662: <em>start()</em> and <em>stop()</em>.
1663: @return The number of hours between the last calls to
1664: <em>start()</em> and <em>stop()</em>.
1665: @pre <em>start()</em> and <em>stop()</em> have been called
1666: (in that order).
1667: @post The accumulated time, in hours, between the times when
1668: the stopwatch was last started and stopped, has been returned.
1669: */
1672: void display() const;
1673: /**<
1674: Displays the time, in hours (as an integer value), minutes (as an
1675: integer value), and seconds (as a double value), between the last
1676: time this <tt>%Stopwatch</tt> object was started and stopped.
1677: @pre <em>start()</em> and <em>stop()</em> must have been called,
1678: in that order.
1679: @post
1680: - Case 1: If no name has been given to the event that has just been
1681: timed, the ouput displayed is this:
1682: <pre>
1683: Total time elapsed = hh:mm:ss.sss
1684: </pre>
1685: - Case 2: If a name (name-of-event) has been given to the event that
1686: has just been timed, the ouput displayed is this:
1687: <pre>
1688: Total time elapsed for event name-of-event = hh:mm:ss.sss
1689: </pre>
1690: */
1692: private:
1693: clock_t numClockTicksPassed;
1694: string eventName;
1695: };
1698: class TextItems
1699: /**
1700: For displaying on-line help and other text messages in
1701: console applications.
1702: The Textitems class provides a convenient mechanism for holding, in
1703: memory, any number of "text items" and displaying any one of these text
1704: items as required by the program. A "text item" consists of one or more
1705: lines of text and all text items are loaded in from a textfile, which
1706: must have the format specified below. One obvious use for this class
1707: would be for handling on-line help, but any text item, consisting of
1708: any number of lines, that needs to be displayed one or more times by
1709: a program may be considered a candiate to become a "text item".
1711: Any textfile containing text items must contain at least one text
1712: item. Any such file and each text item in it must be formatted
1713: according to the following rules:
1715: -# All lines of text from the beginning of the file down to the first
1716: line consisting of 40 equal signs will be ignored. Thus one or more
1717: lines that serve to identify file content to a human reader of the
1718: file may be placed before this line. Such a line of 40 equal signs
1719: must be left-justified. A left-justified line of 40 equal signs looks
1720: like this:
1721: <pre>
1722: ========================================
1723: </pre>
1724: -# The first line of each text item must be its "title", i.e., the
1725: exact string that will be used by the program to access that particular
1726: text item for display. The title is not displayed when the text item is
1727: displayed; it is used solely for identifying the item. There must be no
1728: leading or trailing spaces in the title.
1729: -# Each text item must be terminated by a line of exactly 40 dashes
1730: (hyphens) which is not regarded as part of the item itself (and is
1731: therefore not displayed when the text item is shown on the screen).
1732: Each item-terminating line of 40 dashes must be left-justified.
1733: A left-justified line of 40 dashes looks like this:
1734: <pre>
1735: ----------------------------------------
1736: </pre>
1737: -# The body of a text item may contain one or more lines consisting
1738: of exactly 40 exclamation marks (!) among the lines of "regular" text.
1739: Such a line indicates a point where the display must pause and ask the
1740: user to press Enter to continue, but the line itself is not displayed.
1741: Such a line of 40 exclamation marks must be left-justified. A
1742: left-justified line of 40 exclamation marks looks like this:
1743: <pre>
1744: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1745: </pre>
1746: -# The last text item in the file must be followed immediately by an
1747: additional line of 40 equal signs like that shown above. Any text
1748: following this line in the file will also be ignored. It may thus
1749: be inferred that a file of text items will normally contain exactly
1750: two left-justified lines consisting of 40 equal signs, and there may
1751: (or may not) be text before the first one, and after the second one,
1752: with all such text being ingored by any program reading the file.
1753: -# Keep all lines in a text item strictly less than 80 characters in
1754: length. In the first place, any line longer than this will likely wrap
1755: to a second line, and may not break where you'd like it to. Second,
1756: some systems (DOS/Windows, for example) seem to put an automatic line
1757: feed at the end of each line of exactly 80 characters.
1758: So, keeping lines under 80 characters in length will avoid extraneous
1759: blank lines in the output that might be introduced in this way.
1760: */
1761: {
1762: public:
1764: TextItems();
1765: /**<
1766: Default constructor.
1767: @pre None
1768: @post The list of text items has been initialized and is empty.
1769: However, the program is then terminated after displaying the
1770: following 6-line message:
1771: <pre>
1772: Error: File name must be supplied when declaring
1773: a %TextItems object, as in (for example):
1774: %TextItems myTextItems("my_text_item_file.dat");
1775: Program is now terminating.
1776: Press Enter to continue ...
1777: </pre>
1778: */
1781: TextItems
1782: (
1783: const string fileName //in
1784: );
1785: /**<
1786: Constructor which gets its list of text items from a textfile.
1787: @pre <em>fileName</em> has been initialized.
1788: @post
1789: - Case 1 (typical): If <em>fileName</em> contains the name (or
1790: the full pathname) of a properly-formatted file of text items, all
1791: text items in that file have been read into memory and the constructed
1792: object contains this list of text items.
1793: - Case 2 (error): If <em>fileName</em> contains the name of
1794: an empty file, the program displays this 3-line message:
1795: <pre>
1796: Error: Input file of text items is empty.
1797: Program is now terminating.
1798: Press Enter to continue ...
1799: </pre>
1800: - Case 3: If <em>fileName</em> contains the name of a file that
1801: doesn't exist, the program will give the user one opportunity to
1802: rectify the situation by entering, from the standard input, the
1803: name of a valid file of text items (or the name and path to the
1804: file if it's not in the working directory). If the user then fails
1805: to do so, the program displays this 3-line message:
1806: <pre>
1807: Error: Input file of text items does not exist.
1808: Program is now terminating.
1809: Press Enter to continue ...
1810: </pre>
1811: The program thus terminates if a validly-named file is empty, or
1812: if the name of a valid file is not supplied, either initially, or
1813: during the one additional permitted attempt.
1814: */
1817: void displayItem
1818: (
1819: const string title //in
1820: ) const;
1821: /**<
1822: Displays a text item on the standard output.
1823: @pre <em>title</em> has been initialized.
1824: @post
1825: - Case 1 (typical): The text item identified by <em>title</em>
1826: has been displayed.
1827: - Case 2 (error): If the text item designated by <em>title</em>
1828: cannot be found, the following 2-line message is displayed:
1829: <pre>
1830: Error: Text item \<\<title\>\> not found.
1831: Press Enter to continue ...
1832: </pre>
1833: */
1835: private:
1836: vector< vector<string> > itemList;
1837: };
1840: //DisplayOpeningScreen free function
1841: //********************************************************************
1842: inline void DisplayOpeningScreen
1843: (
1844: const string& programmerInfo, //in
1845: const string& programInfo, //in
1846: int numBlankLinesBefore, //in
1847: int numBlankLinesAfter //in
1848: )
1849: {
1850: string blankLinesBefore(numBlankLinesBefore, '\n'),
1851: blankLinesAfter(numBlankLinesAfter, '\n');
1852: cout << blankLinesBefore
1853: << programmerInfo << "\n"
1854: << programInfo
1855: //<< "\nThis executable was built on " << __DATE__
1856: //<< " at " << __TIME__ << ".\n"
1857: << "\nThe main driver of this executable was built on "
1858: << __DATE__
1859: << " at " << __TIME__ << ".\n"
1860: << blankLinesAfter;
1861: Pause();
1862: }
1864: } //End of this part of namespace Scobey
1866: #endif