category-group: io
layer: 2
header file(s): z_dirt.h

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