String and Stream Input and Output (GNU MPC 1.4.1)

### 5.4 String and Stream Input and Output ¶

Function: `int` mpc_strtoc `(mpc_t rop, const char *nptr, char **endptr, int base, mpc_rnd_t rnd)` ¶

  Read a complex number from a string nptr in base base, rounded to the precision of rop with the given rounding mode rnd. The base must be either 0 or a number from 2 to 36 (otherwise the behaviour is undefined). If nptr starts with valid data, the result is stored in rop, the usual inexact value is returned (see Return Value) and, if endptr is not the null pointer, *endptr points to the character just after the valid data. Otherwise, rop is set to `NaN + i * NaN`, -1 is returned and, if endptr is not the null pointer, the value of nptr is stored in the location referenced by endptr.

  The expected form of a complex number string is either a real number (an optional leading whitespace, an optional sign followed by a floating-point number), or a pair of real numbers in parentheses separated by whitespace. If a real number is read, the missing imaginary part is set to +0. The form of a floating-point number depends on the base and is described in the documentation of `mpfr_strtofr` in the GNU MPFR manual. For instance, `"3.1415926"`, `"(1.25e+7 +.17)"`, `"(@nan@ 2)"` and `"(-0 -7)"` are valid strings for base = 10. If base = 0, then a prefix may be used to indicate the base in which the floating-point number is written. Use prefix ’0b’ for binary numbers, prefix ’0x’ for hexadecimal numbers, and no prefix for decimal numbers. The real and imaginary part may then be written in different bases. For instance, `"(1.024e+3 +2.05e+3)"` and `"(0b1p+10 +0x802)"` are valid strings for `base`=0 and represent the same value.

Function: `int` mpc_set_str `(mpc_t rop, const char *s, int base, mpc_rnd_t rnd)` ¶

  Set rop to the value of the string s in base base, rounded to the precision of rop with the given rounding mode rnd. See the documentation of `mpc_strtoc` for a detailed description of the valid string formats. Contrarily to `mpc_strtoc`, `mpc_set_str` requires the whole string to represent a valid complex number (potentially followed by additional white space). This function returns the usual inexact value (see Return Value) if the entire string up to the final null character is a valid number in base base; otherwise it returns −1, and rop is set to NaN+i*NaN.

Function: `char *` mpc_get_str `(int b, size_t n, const mpc_t op, mpc_rnd_t rnd)` ¶

  Convert op to a string containing its real and imaginary parts, separated by a space and enclosed in a pair of parentheses. The numbers are written in base b (which may vary from 2 to 36) and rounded according to rnd. The number of significant digits, at least 2, is given by n. It is also possible to let n be zero, in which case the number of digits is chosen large enough so that re-reading the printed value with the same precision, assuming both output and input use rounding to nearest, will recover the original value of op. Note that `mpc_get_str` uses the decimal point of the current locale if available, and ‘`.`’ otherwise.

  The string is generated using the current memory allocation function (`malloc` by default, unless it has been modified using the custom memory allocation interface of `gmp`); once it is not needed any more, it should be freed by calling `mpc_free_str`.

Function: `void` mpc_free_str `(char *str)` ¶

  Free the string str, which needs to have been allocated by a call to `mpc_get_str`.

The following two functions read numbers from input streams and write them to output streams. When using any of these functions, you need to include `stdio.h` before `mpc.h`.

Function: `int` mpc_inp_str `(mpc_t rop, FILE *stream, size_t *read, int base, mpc_rnd_t rnd)` ¶

  Input a string in base base in the same format as for `mpc_strtoc` from stdio stream stream, rounded according to rnd, and put the read complex number into rop. If stream is the null pointer, rop is read from `stdin`. Return the usual inexact value; if an error occurs, set rop to `NaN + i * NaN` and return -1. If read is not the null pointer, it is set to the number of read characters.

  Unlike `mpc_strtoc`, the function `mpc_inp_str` does not possess perfect knowledge of the string to transform and has to read it character by character, so it behaves slightly differently: It tries to read a string describing a complex number and processes this string through a call to `mpc_set_str`. Precisely, after skipping optional whitespace, a minimal string is read according to the regular expression `mpfr | '(' \s* mpfr \s+ mpfr \s* ')'`, where `\s` denotes a whitespace, and `mpfr` is either a string containing neither whitespaces nor parentheses, or `nan(n-char-sequence)` or `@nan@(n-char-sequence)` (regardless of capitalisation) with `n-char-sequence` a string of ascii letters, digits or `'_'`.

  For instance, upon input of `"nan(13 1)"`, the function `mpc_inp_str` starts to recognise a value of NaN followed by an n-char-sequence indicated by the opening parenthesis; as soon as the space is reached, it becomes clear that the expression in parentheses is not an n-char-sequence, and the error flag -1 is returned after 6 characters have been consumed from the stream (the whitespace itself remaining in the stream). The function `mpc_strtoc`, on the other hand, may track back when reaching the whitespace; it treats the string as the two successive complex numbers `NaN + i * 0` and `13 + i`. It is thus recommended to have a whitespace follow each floating-point number to avoid this problem.

Function: `size_t` mpc_out_str `(FILE *stream, int base, size_t n_digits, const mpc_t op, mpc_rnd_t rnd)` ¶

  Output op on stdio stream stream in base base, rounded according to rnd, in the same format as for `mpc_strtoc` If stream is the null pointer, rop is written to `stdout`.

  Return the number of characters written.