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, 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 becocmes 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, 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.