synopsis.
a small set of functions that get console input when the user enters an end-of-line symbol (a carriage-return, "[CR]", or a newline - "[LF]"). These routines use the layer-0 I/O subroutine z_getline_stdin(). End-of-lines are indicated in this context as EOL.

[C] functions (aka subroutines):

simply_get_yes()
SIGNATURE: boolean simply_get_yes (const string_o &msg)
SYNOPSIS:
processes console input text when the user types in something via the keyboard and presses EOL. If the first character typed is a 'y' (or 'Y'), this routine returns TRUE.
Example:

  boolean result = simply_get_yes("do you want to continue?");
  if (!result)
    return 1;

PARAMETERS

msg: a string object containing any text to output before prompting for input. No EOL is added to this text (although the string itself may have EOLs).

RETURNS:
TRUE: first character of keyboard input is 'y' or 'Y'.
FALSE: otherwise.
 

simply_get_number()
SIGNATURE: count_t simply_get_number (const string_o &msg)
SYNOPSIS:
gets console input text when the user types in something at the keyboard and then presses EOL. This will convert the input to a cardinal number and returns the result as a count_t (long int) type.
Example:

  count_t n = simply_get_number("how many?");
  if (n > 100)
    std::cout << "Too many!\n";

PARAMETERS

msg: a string object containing any text to output before prompting for input. Nothing else is emitted (such as EOL, although the string itself may contain EOLs).

RETURNS: the input, as a [long int] number.
 

simply_get_real_number()
SIGNATURE: double simply_get_real_number (const string_o &msg)
SYNOPSIS:
this subroutine is very similar to simply_get_number(), except that the input is expected to be and processed as a real (ie floating-point) number. Very little (if any) error checking is done to ensure that the input is conformant to the syntax for a real number.
PARAMETERS

msg: a string object containing any text to output before prompting for input. Nothing else is emitted (such as EOL, although the string itself may contain EOLs).

RETURNS: the input, as a double
 

simply_get_line()
SIGNATURE: string_o simply_get_line (const string_o &msg, boolean trim, int *pi)
SYNOPSIS:
returns the text typed at the console input when the user presses EOL. The contents of this input is not processed. Rather, it is stuffed into a string object, which is simply returned.
PARAMETERS

• msg: a string object containing any text to output before prompting for input. Nothing else is emitted (not EOL, nor any spaces afterward).
  You may want to have 1 blank character at the end of this string so that the message text is separate from the input typed by the user.
• trim: [input] if FALSE, any EOL at the end of the string is not removed.
• pi: [output] error indicator variable. values:
  0: success (always)

 

[ostream] operator <<()
SIGNATURE: std::ostream &operator <<; (std::ostream &os, const string_o &str)
SYNOPSIS:
this subroutine provides a convenient way to print a Z Directory string object to stdout. no special formatting is done and nothing except the contents of 'str' is emitted.
PARAMETERS

• os: the "ostream" [standard output stream] object where the string is to be printed to.
• str: [input] the string object to be printed

 

[istream] operator >>()
SIGNATURE: std::istream &operator >> (std::istream &is, string_o &str)
SYNOPSIS: this subroutine provides a convenient way to get console input into a Z Directory string object
PARAMETERS

• is: the standard input stream. normally this is equivalent to keyboard input.
• str: [output] the string object that recieves the input.

 

history.

Wed 09/17/2003: added the function 'simply_get_line()'
Sun 08/21/2011: add "\n" to output of 'simply_get_line()' [--GeG]
Fri 02/01/2013: moved to the "io" group