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